vikunja/veans/AGENTS.md

# AGENT Instructions for veans

Things to know before touching this submodule that aren't obvious from
reading the code. The parent repo's `CLAUDE.md` covers the rest of Vikunja;
this file is veans-specific.

## Module layout

- `veans/` is its own Go module (`code.vikunja.io/veans`), separate from
  the parent. Don't try to import `code.vikunja.io/api/...` — that pulls
  XORM into the CLI binary. Wire types live in `internal/client/types.go`
  as plain JSON-tagged structs that mirror the parent models.
- License headers are enforced by `goheader` in `veans/.golangci.yml`.
  Every new `.go` file needs the AGPLv3 banner from
  `veans/code-header-template.txt` (a copy of the parent's, kept local
  so the linter resolves the path relative to this module).

## Building and testing

- `mage build` → `./veans` binary. The `Aliases` map in `magefile.go`
  routes bare names like `mage test` to `Test.All` — without aliases,
  mage rejects namespace invocations ("Unknown target specified").
- Unit tests: `mage test` (passes `-short`) or `go test -short ./...`.
  The e2e package's `TestMain` gates the suite on `-short`, mirroring
  the parent monorepo's `pkg/webtests` convention. Without `-short`
  and without `VEANS_E2E_API_URL` set, the e2e tests fail loudly with
  a "configure or pass -short" hint.
- E2e tests: `mage test:e2e` (no `-short`). Assumes an externally-
  running Vikunja at `VEANS_E2E_API_URL`. The harness seeds its own
  admin user via `PATCH /api/v1/test/users` — same mechanism the
  playwright suite uses — so the API must be booted with
  `VIKUNJA_SERVICE_TESTINGTOKEN=<token>` and the same value passed in
  via `VEANS_E2E_TESTING_TOKEN`. Alternative path:
  `VEANS_E2E_ADMIN_TOKEN=<jwt>` skips the seed and uses the given
  token as-is, for driving a long-lived Vikunja the suite shouldn't
  mutate user rows on.
- Local e2e loop: from the parent repo root, build the API
  (`mage build:build`), run it with sqlite-memory + a known JWT
  secret + `VIKUNJA_SERVICE_TESTINGTOKEN`, then `mage test:e2e` from
  `veans/` with `VEANS_E2E_API_URL` + `VEANS_E2E_TESTING_TOKEN`. No
  manual seeding step — the test harness handles it.
- CI: the `test-veans-e2e` job in `.github/workflows/test.yml` consumes
  the existing `vikunja_bin` artifact from `api-build`; don't recompile
  the API in a parallel workflow. The `veans-test` job runs unit tests
  with `-short` for fast feedback, independent of `api-build`.

## Vikunja wire-format gotchas

veans targets the Huma-backed **`/api/v2`** exclusively (`apiBasePath` in
`internal/client/client.go`). v1 is frozen, and the kanban-bucket CRUD veans
relies on only exists on v2. Most failures surface when crossing the JSON
boundary. The list below is what's bitten me; if a new endpoint behaves
oddly, suspect one of these:

- **Lists come wrapped in the standard envelope.** Every v2 list returns
  `{"items":[...],"total":N,"page":N,"per_page":N,"total_pages":N}`, not a
  bare array, and there is no `x-pagination-total-pages` header anymore.
  Decode with the generic `Paginated[T]` helper. **Most lists are
  server-paginated** — their model's `ReadAll` applies a 50-item page limit:
  tasks, projects, labels, comments and bots. Page through those with
  `doListAll` until `page >= total_pages`; returning only page 1 silently
  truncates (>50 comments on a task is realistic). **Buckets and project
  views are the exception**: their `ReadAll` takes `_ int, _ int` and returns
  every row in one page, so fetch them with a single `doList` and unwrap
  `.items` — paging those would re-fetch the full set and duplicate it.
  Single-object responses (create/update/read of one entity) stay UNWRAPPED.
- **v2 flips the create/update verbs.** Creates are **POST** (v1 used PUT):
  projects, labels, tokens, bot users, project shares, task create,
  comments, relations, assignees, label-attach, bucket create. Task update
  is **PATCH** (see below). The bucket-task move is **PUT**.
- **Task update is `PATCH /tasks/{id}` with `application/merge-patch+json`**
  (`client.DoMerge` → `UpdateTask(*TaskPatch)`). Only the fields present in
  the body are written; absent fields are left intact. Build the body from
  `TaskPatch` (pointer fields, omitempty) — never a whole `client.Task`,
  whose no-omitempty `done`/`title` would clobber those columns on every
  call (this was issue #2962).
- **List search is `q`**, not v1's `s` (`ListParams.Q`). Task-list
  `filter`/`expand`/`page`/`per_page` keep their names.
- **`ProjectView.view_kind` and `bucket_configuration_mode` are
  strings**, not ints. The parent enums (`ProjectViewKind`,
  `BucketConfigurationModeKind`) have custom `MarshalJSON` that emits
  `"kanban"` / `"manual"` etc. Use the string constants in
  `internal/client/types.go`.
- **`Task.BucketID` is always 0** in `GET /tasks/:id`. The model has
  `xorm:"-"` on it — the actual bucket lives in a separate
  `task_buckets` table. Fetch with `?expand=buckets` and use
  `task.CurrentBucketID(viewID)` to read it.
- **Task updates do NOT move tasks between buckets.** The task↔bucket
  relation is row-shaped; use `client.MoveTaskToBucket()` which hits
  **`PUT /projects/{p}/views/{v}/buckets/{b}/tasks`** with a `{"task_id":N}`
  body (project/view/bucket all come from the URL). The Update path on the
  server only auto-moves on `done` flips.
- **Bot user creation is `POST /user/bots`**, not `/bots` — the routes
  are registered under the `/user` subgroup. Same prefix for
  `GET /user/bots`.
- **`APIToken.expires_at` is required.** The struct field has
  `valid:"required"` upstream; sending it omitted or zero fails
  validation. Use `client.FarFuture` (year 9999) when you mean "no
  expiry" — the frontend does the same.
- **Task descriptions and comments are HTML, not markdown.** The
  Vikunja web UI uses TipTap, which calls `getHTML()` on save. The
  stored field is therefore HTML. The agent prompt template
  (`internal/commands/prompt.tmpl`) teaches agents the canonical
  TipTap shapes — most importantly `<ul data-type="taskList">` +
  `<li data-type="taskItem" data-checked="false"><p>…</p></li>` for
  interactive checkboxes. We deliberately do **not** convert
  markdown↔HTML in the CLI; the agent writes HTML directly, which
  avoids lossy roundtrips on `--description-replace-old/new`. `veans
  show` displays the raw HTML; humans skim it fine.

## API token permissions

- Vikunja validates token `permissions` against `apiTokenRoutes`, a map
  built dynamically from registered routes. Group names are derived
  from the URL path (params stripped, joined by `_`). Examples:
  - `/projects/:project/views/:view/buckets/:bucket/tasks` →
    group `projects`, action `views_buckets_tasks`
  - `/tasks/:task/comments` → group `tasks_comments`, action `create`
- v1 and v2 deliberately share `(group, permission)` keys:
  `pkg/models/api_routes.go` normalizes the inverted verbs (v2 POST-create
  and v1 PUT-create both → `create`; v2 PUT/PATCH-update and v1 POST-update
  both → `update`), and `CanDoAPIRoute` consults both route tables, treating
  PATCH as an alias for the stored PUT. So `PermissionsForBot`'s scope map
  authorizes the v2 calls unchanged, including the PATCH task update.
- The bucket-task MOVE (`PUT …/buckets/:bucket/tasks`) and the
  buckets-with-tasks LIST (`GET …/buckets/tasks`) collide on subkey
  `views_buckets_tasks`; which one gets the bare key vs `views_buckets_tasks_put`
  depends on unspecified route-init order, so the bot requests **both**.
- `client.PermissionsForBot()` calls `GET /routes` at runtime and
  grants only the intersection of what we want and what the server
  exposes. **Don't hard-code permission group names** — they drift
  across Vikunja versions, and discovery keeps the bot's grant valid
  across upgrades.

## Bot ownership and token minting

- Creating a bot via `POST /user/bots` automatically sets the bot's
  `bot_owner_id` to the calling user. Only the owner can mint tokens
  for the bot via `POST /tokens` with `owner_id=<bot_id>`. The init
  flow does these as a single human-JWT-authenticated batch.
- Bots have no password and **cannot** authenticate via `POST /login`.
  After init, `veans login` re-authenticates as the human (not the
  bot) and mints a fresh bot token.

## OAuth flow

- Vikunja's authorization server requires PKCE/S256 and accepts either
  `vikunja-…://` custom schemes or RFC 8252 loopback URIs
  (`http://127.0.0.1:NNN/`, `http://localhost:NNN/`, `http://[::1]:NNN/`).
  No client registration needed — `client_id` can be any consistent
  string (we use `veans-cli`).
- `internal/auth/oauth.go` binds a free port on 127.0.0.1, opens the
  browser, and captures the callback. The `Shutdown` defer uses
  `context.WithoutCancel(ctx)` so cancellation at the outer scope
  still drains the loopback server cleanly.
- Token exchange goes out as **JSON**. v2's `/oauth/token` accepts both JSON
  and form-encoded bodies (Huma picks the decoder off the `Content-Type`
  header), but the standard `golang.org/x/oauth2` client hard-codes form
  encoding and its own response shape, so we keep the hand-rolled
  `client.ExchangeOAuthCode` that speaks JSON.

## Credential store

- Lookup chain: keychain → env (`VEANS_TOKEN`) → file
  (`~/.config/veans/credentials.yml`, mode 0600, atomic-write + flock
  serialization). `XDG_CONFIG_HOME` is deliberately not honored —
  agent-only audience runs in a known environment, and the env var
  was a path-traversal seam for no real benefit.
- `Chain.Set` falls through to the next backend on error so a missing
  dbus on a CI runner doesn't block writes — the file backend is the
  reliable last-resort.
- File writes go through a tmp file + `Rename`, with `Chmod 0o600`
  re-asserted on the destination inode so a pre-existing wider mode
  is narrowed. Concurrent writers (e.g. two `veans login` runs) are
  serialized via `flock` on `<path>.lock` (Unix only; Windows is a
  no-op stub since the audience is Linux/macOS).
- E2e tests override `HOME` per test and `filterEnv(..., "VEANS_")`
  strips any inherited `VEANS_TOKEN` so the developer's keyring
  stays untouched. Don't bypass the credentials package in tests —
  leaks between tests will surface as the wrong bot token.

## Project identifiers and bot usernames

- Project `Identifier` is `runelength(0|10)`, can be empty. When empty,
  `Config.FormatTaskID` renders `#NN`; otherwise `PROJ-NN`. Both are
  accepted by `runtime.resolveTaskID` along with bare integers.
- Bot username must start with `bot-`; the server enforces it. Hyphens,
  digits, lowercase letters allowed; no spaces, no commas, no
  `link-share-N` pattern. `config.SuggestedBotUsername` does the
  folding for repo names.
- E2e tests deriving identifiers from a unique suffix should use the
  trailing chars of `strconv.FormatInt(time.Now().UnixNano(), 36)`.
  The leading chars barely change between consecutive runs and will
  collide if you take `[:N]`.

## Audience split

The CLI is agent-only at runtime; humans never use it for day-to-day
work (they use Vikunja's web UI). Two commands serve a human running
one-off setup:

- **`init`** — bootstrap a repo: pick project + view, create bot,
  share, mint token, write `.veans.yml`, install hooks.
- **`login`** — rotate the bot's token.

Everything else (`list`, `show`, `create`, `update`, `claim`, `api`,
`prime`, `version`) is **agent-only**:

- **Emits JSON on stdout unconditionally.** No `--json` flag, no
  human-formatted variant. `list` is a raw array; `show` / `create` /
  `update` / `claim` return a single task object.
- **Errors are JSON on stderr** with non-zero exit — same envelope
  everywhere (`{"code": "...", "error": "..."}`), regardless of which
  command ran. Stable codes in `internal/output/errors.go`:
  `NOT_FOUND`, `CONFLICT`, `VALIDATION_ERROR`, `AUTH_ERROR`,
  `RATE_LIMITED`, `BOT_USERS_UNAVAILABLE`, `NOT_CONFIGURED`,
  `UNKNOWN`. Don't add ad-hoc strings — wrap with `output.New` /
  `output.Wrap`.
- **No `globals.JSON`, no dual rendering paths.** If you find yourself
  reaching for "if interactive, do X" on an agent-facing command,
  stop — it's not interactive, an agent is on the other end.

## Cobra surface conventions

- `RunE` handlers that don't use `args []string` should rename it to
  `_` to satisfy revive's `unused-parameter` rule.
- The bucket-move dance (`MoveTaskToBucket`) runs **after** the field
  update on `update`, so a status transition can't clobber freshly
  attached labels. Comments for `--status scrapped` post **before**
  the bucket move so the audit trail reads in chronological order.
- Agent-facing commands return the task via `json.NewEncoder(...).Encode(task)`.
  Adding new top-level keys to `client.Task` is an implicit API
  change — bump `prime`'s "useful fields" note alongside.

## Things to *not* do

- **Don't add an `os/exec.Command`** without ctx — `noctx` is enabled.
  Use `exec.CommandContext(ctx, …)` and thread the context through.
- **Don't commit the built binary.** `veans/.gitignore` covers
  `./veans` and `./veans.exe`.
- **Don't write to stdout from `prime` when no `.veans.yml` is found.**
  The hook contract is silent + exit 0 so the snippet is safe to install
  globally in `~/.claude/settings.json`.
- **Don't rename canonical bucket titles** without updating
  `BucketTitleAliases[s][0]` in `internal/status/status.go`, the
  prompt template (`internal/commands/prompt.tmpl`), and the e2e
  assertions in lockstep — agents and humans both treat them as
  fixed strings.