<!--
SPDX-FileCopyrightText: Amolith <amolith@secluded.site>

SPDX-License-Identifier: CC0-1.0
-->

# AGENTS.md

This file guides LLM agents through interacting with and maintaining
the lune project—a CLI for the Lunatask productivity app.

## Lunatask concepts

Lunatask is end-to-end encrypted and any sensitive information
(person/task/note/habit names, contents, etc.) is all omitted. The API
only returns basic metadata (IDs, timestamps, status, etc.). That also
means there is no way to dynamically list the user's areas, habits, or
notebooks; they must copy those details from the desktop app into lune
during interactive initialisation or reconfiguration.

## Commands

Run these most to least often:

```bash
task fmt lint:fix staticcheck test  # Important ones to run often
task                                # Include vulnerability and copyright checks
```

The Taskfile auto-installs tools (gofumpt, staticcheck, govulncheck) when
running their respective tasks.

## Architecture

```
main.go              → cmd.Execute() entrypoint
cmd/
  root.go            → Root command, registers all subcommands and groups
  init.go, ping.go   → Top-level commands
  add.go, done.go, jrnl.go  → Shortcuts (delegate to resource commands)
  task/              → task add/list/get/update/delete
  note/              → note add/list/get/update/delete
  person/            → person add/list/get/update/delete/timeline
  journal/           → journal add
  habit/             → habit track
internal/
  client/            → Lunatask API client factory (uses system keyring)
  config/            → TOML config at ~/.config/lunatask/config.toml
  ui/                → Lipgloss styles (Success, Warning, Error, Muted, Bold)
  validate/          → Input validation (UUID format)
```

**Command flow**: `fang.Execute()` wraps Cobra with version/commit info and
signal handling. Resource commands live in subpackages (`cmd/task/`); shortcuts
in `cmd/` delegate to resource commands by calling their `RunE` directly and
copying their flagset.

## Command patterns

**Resource commands** (task, note, person, etc.):

- Parent command in `<resource>.go` with `GroupID: "resources"`
- Subcommands (add, list, get, update, delete) in separate files
- Export the `*Cmd` vars for shortcuts to reference

**Shortcuts** (add, done, jrnl):

- Live in `cmd/` directly with `GroupID: "shortcuts"`
- Copy flags from resource command:
  `addCmd.Flags().AddFlagSet(task.AddCmd.Flags())`
- Call resource command's `RunE` directly

**Shell completions** registered inline via `RegisterFlagCompletionFunc`;
see `cmd/task/add.go:43-56` for examples. Config-based completions load
from `config.Load()`.

## Core dependencies

Reference docs via context7 or doc-agent when unsure:

- `git.secluded.site/go-lunatask` (context7:
  `/websites/pkg_go_dev_git_secluded_site_go-lunatask`): Lunatask API client.
  Amolith maintains it, so issues can be resolved or missing features added
  quickly.
- `github.com/charmbracelet/huh` (context7: `/charmbracelet/huh`):
  powerful and attractive libs for interactive forms and prompts
- `github.com/charmbracelet/lipgloss` (context7: `/charmbracelet/lipgloss`):
  Terminal styling.
- `github.com/charmbracelet/fang` (context7: `/charmbracelet/fang`): Cobra
  wrapper with fancy styling, version injection, signal handling.
- `github.com/zalando/go-keyring` (context7: `/zalando/go-keyring`):
  Cross-platform interface to the system keyring
- `github.com/BurntSushi/toml` (context7: `/burntsushi/toml`): Config file
  parsing.
- `github.com/spf13/cobra` (context7:
  `/websites/pkg_go_dev_github_com_spf13_cobra`): CLI framework.

## Gotchas

### Linter exclusions for cmd/

The `.golangci.yaml` disables several linters for `cmd/`:

- `gochecknoglobals`, `gochecknoinits`: Cobra requires package-level vars and
  `init()`
- `errcheck`, `godox`: Stub implementations deliberately print without checking,
  TODOs are placeholders
- `wrapcheck`: CLI returns errors for display; wrapping adds noise

These patterns are intentional.

### Access token

Read from system keyring via `internal/client.New()`. No interactive
prompts—fail fast with `client.ErrNoToken` if not configured.

### Output formatting

Use `cmd.OutOrStdout()` and `cmd.ErrOrStderr()` for testability. Styles are in
`internal/ui/styles.go`—use `ui.Success`, `ui.Error`, etc. rather than inline
colors.

## Testing

Currently stub implementations with `// TODO` markers. When implementing, use
`cmd.SetOut()` / `cmd.SetErr()` to capture output.