# AGENTS.md — internal/cmd **The command tree: flags, receipts, exit codes.** The only package that may import every layer below it, and the only one that prints. `cmd/kettle` is four lines around `cmd.Main(os.Args[1:])` — everything a `main` usually accumulates lives here instead, because a `main` package cannot be imported and therefore cannot be tested. ## Commands are values Each command is one `register(&Command{…})` in an `init()`, carrying the metadata a human needs — `Short`, `Long`, `Examples`, `Args`, `Group` — **in the same struct that carries the code**. That is what lets the plugin's SKILL.md files be generated from this list: a command whose flags changed cannot ship with documentation that says otherwise. ```go func init() { register(&Command{ Name: "tree", Group: GroupIssue, Args: "[…]", Short: "draw the dependency graph of the local store", Long: `…`, Examples: []Example{{"kettle tree", "every root (nothing depends on it)"}}, Setup: func(fs *flag.FlagSet) func([]string) error { out := storeFlag(fs) depth := fs.Int("depth", 6, "maximum depth") return func(args []string) error { … } }, }) } ``` **`Setup` registers flags and returns the runner**, closing over them. Splitting it that way is what lets `Command.Flags()` walk a command's flags without running anything — which is how the doc generator reads them. **The tree is flat.** `kettle new`, not `kettle issue new`: an agent pays for every token of every invocation, and the grouping that matters for reading is carried in `Group` and only shows up in the docs. Four groups, in presentation order: `project`, `issue`, `sync`, `api`. | file | what is in it | |---|---| | `command.go` | `Command`, the registry, `Main`, help rendering, `SilentError`, `Fail`, and `permute` | | `flags.go` | `storeFlag`/`storeRoot`, `wasSet`, the repeatable `stringList` | | `sync.go` | `syncStart`/`syncStartExisting`, `commentsSidecarPath` — the shared opening of every tracker command | | `gen.go` | `kettle gen skills`: the generated region in the plugin's SKILL.md files | | `init.go` `auth.go` `config.go` `version.go` | group `project`. `version.go` also holds `Version`, the string a release build stamps in with `-ldflags -X` | | `new.go` `check.go` `ac.go` `tree.go` `index.go` `evict.go` | group `issue` — no network in any of them | | `pull.go` `push.go` `remote.go` `comment.go` `close.go` `labels.go` `evict_sync.go` | group `sync` | | `api.go` | group `api`, alone in it: one request to an endpoint nothing here wraps | | `cli_test.go` | builds the binary in `TestMain`, runs it as a subprocess | | `sync_pull_test.go` `sync_write_test.go` `api_test.go` | the tracker halves, against fake servers | | `gen_test.go` | the generator: determinism, the region splice, the missing-marker refusal | The fourth group is one command and was still worth naming, because a group is a skill directory over in the plugin: `api` is a subject somebody loads on its own — which endpoint, and does it paginate — and folding it into `sync` would have put "how do I cut a release" behind a skill about the issue round trip. ## Three conventions every command follows **Flags may come after positionals.** The standard `flag` package stops parsing at the first non-flag argument, so `kettle ac --check 3` would hand `--check` to the command as a positional and tick nothing. `permute` moves flags forward, using the `FlagSet` to know whether a flag swallows the next argument; `--` ends the permutation. Every other CLI an operator uses interleaves the two, and a tool that silently ignores a flag because of where it was typed is worse than one that rejects it. **Exit codes are three.** `0` fine, `2` for a usage problem (unknown command, unparseable flags), `1` for an ordinary failure — printed as `kettle : ` by `Main`, which is why no command prefixes its own errors. `SilentError{Code: 1}` is for a command that has already said everything it has to say: `check` and `gen --check` use it, because findings went to stdout and a second copy on stderr would be noise. **The store is resolved before a socket is opened.** `syncStart` does that in one place: a command that dialled first would report a network problem for a project that was never initialized, and an operator would go looking at the wrong thing. `syncStartExisting` adds `RequireStore` for the commands that read the store rather than create it — `push`, `comment`, `close`, `sync-evict` — because a missing store is a mistake to report, not a directory to conjure. **There is no `--login` and no `--repo`** on any sync command bar `labels`. Which login a project runs under is a fact about the project, stated once by `kettle init`. That the two could disagree is what the Python version needed a `PreToolUse` hook to police. `api` keeps that rule and needs no flag to: a cross-repository address is an address, so `repos/other-owner/other-repo/releases` is simply a path with nothing to substitute — `{owner}` and `{repo}` are filled in only where they are spelled. Another **instance** is `KETTLE_URL`/`KETTLE_TOKEN`, and a full URL pointing at a host that is not this project's is refused by the transport rather than sent with the token attached. It also resolves the store it never reads, exactly as `labels` does, so "there is no project here" fails the same way for every command that talks to a tracker. **`-X DELETE` needs `--yes`.** The only gate of its kind in the tree, and it is here because this is the only command that can delete something that is not an issue — a release, a tag, a branch — from an argument. A flag typed on purpose is an operator's decision; everything else about the request goes out as spelled. `--out` is the one flag almost every command has, and an explicit one is used **exactly as typed**: a relative `--out` stays relative to the working directory, because that is what the operator asked for. ## Usage ```bash kettle help # the tree, grouped kettle help push # one command in full: flags, defaults, examples kettle init --login noodles --repo owner/name kettle new --type task --title "Wire sqlc into the appclick repo layer" kettle ac wire-sqlc-appclick --check 3 kettle check --strict # exit 1 on any error; --strict counts warnings too kettle pull 42 # the issue and everything blocking it, any state kettle push --update wire-sqlc-appclick kettle sync-evict --dry-run ``` Every command's own `Long` text is the reference — it is what `kettle help ` prints and what the generator writes into the plugin. **Do not restate a flag table here**; it would be a third copy of something already in two places, one of them mechanically checked. ## push and pull, the two halves of one rule The rule is that **the store holds what has not left this machine.** Both halves are worth reading in full before either file is touched. `push` (`push.go`) deletes `.md` and every sidecar under that slug — on create and on `--update` alike, one rule with no exception, because a `PATCH` is a push and two rules would put back exactly the question this removes ("is my copy the fresh one?"). The deletion is the **last** thing that happens, and only after all three of: 1. the call came back without an error and with a 2xx, 2. the answer carries a plausible number — on `--update`, the very number that was `PATCH`ed, 3. the number → slug ledger has been written. Network down, non-2xx, an answer that does not confirm the write: the file stays and the run stops. Get the ordering wrong and a slug is lost at exactly the moment the local copy stops being the record, which is why the ledger is written *before* anything is deleted. A never-pushed `origin: local` issue is never touched by any of it. Dependencies go first, in topological order, so a blocker has its number before the issue that names it. An `--update` can take one extra request with it, because Gitea's edit endpoint carries no labels — when the answer's label set and the issue's disagree the whole set goes up in a `PUT`, and a warning on stderr says which names moved. `pull` (`pull.go`) is how a pushed issue comes back. Three sources answer "what is this issue called here", in this order: the ledger (the only one that knows what is on disk *right now*, so it wins), the `` marker in the tracker-side body, then the slugified title. A marker is taken at its word only when the slug is free; a name already in use is a collision, not an identity, and is uniquified. Two ways to name what to pull, and they are **not the same operation**: a key is an *address* and fetches an issue in any state, while a filter is a *query* and leaves closed issues out. `--limit` is on the **write**, not the selection — it counts what lands in the store, which is why a filtered pull can enumerate far more than it keeps and says so. Blockers come down too, recursively to `--depth`, and are outside the limit: a blocker is followed because a stored issue named it. A pull **overwrites the body** — it is a fetch, not a merge — with checkbox state the one exception. ## The generator `gen.go` writes the plugin's SKILL.md command reference from this registry. **It owns a region, not a file.** Everything between `` and `` is replaced on every run; every byte outside comes back exactly as it was, which matters most for `description:`, the prose that decides whether an agent loads the skill at all and the one thing here no generator can write. A file with **no** markers is reported and left alone, never overwritten — clobbering somebody's prose because they forgot a marker is the failure this design exists to prevent. The output is deterministic to the byte — no timestamps, no map iteration — so regenerating something unchanged produces no diff. `--check` is that property made useful: it writes nothing and exits 1 when anything on disk differs, which is what a pre-commit hook or a CI step calls, and it wins over `--dry-run`. One file per **group**, so adding a group here adds a skill directory over there; name one only when it is a subject somebody would load on its own. `api` was added exactly that way, and the first `gen skills` run after it wrote a stub whose `description:` said TODO — a stub is not shippable, and filling that line in by hand is the last step of adding a group, not an optional one. A command with no `Group` is in no skill and the run says so. A `Long` or `Example` that spells a region marker out in full is a hard error — the generated block would end inside itself. ## Keeping this file true - **Scope:** the shape of the command tree — the registry, the shared helpers, the three conventions, the round trip, the generator. The file table names every source file in this directory. - **Update it when** a command file is added or removed, a group is added, a shared helper in `flags.go`/`sync.go` changes, an exit code gains a meaning, a command gains a confirmation gate, or the push/pull ordering guarantees change. - **Do not** copy a flag list or a command's `Long` text here. `kettle help ` and the generated SKILL.md blocks are the two places that exist for it, and a third would be the one that drifts.