Files

T

naudachu f18a633185 feat: reach the rest of Gitea with kettle api, and drop tea

The plugin required `tea`, Gitea's own CLI, for everything that is not an
issue: releases, pull requests, milestones, branches, actions, webhooks. That
put a second binary, a second set of logins nothing here could see, and 400
lines documenting somebody else's flags outside anything this repository can
test. One command over the transport that already existed removes all three.

Transport: `post` — the hand-rolled request the SDK cannot express, written for
the dependency endpoint — is generalized to an exported `Do`, and `post` is
three lines on top of it. Same http.Client, so the same RoundTripper files the
body under .kettle/payload/, the same `token …` header authenticates it, and a
non-2xx is the same *APIError. It does not paginate, does not reformat the
answer, and names no domain concept, so the layering test is untouched.

The endpoint rule is `tea api`'s, so an endpoint table written for that tool
still works — with one restriction it did not have: a full URL must be on this
instance. Every request carries the project's token in a header, and a URL on
another host would hand the token to whatever was typed.

Command: `kettle api <endpoint>` in a new `api` group, so the generator writes
plugins/kettle/skills/api/SKILL.md — group, directory and /kettle:api are one
word. No --repo and no --login, for the reason no sync command has them: a
cross-repository address is an address, and another instance is KETTLE_URL.
`-X DELETE` needs `--yes`; a flag typed on purpose is an operator's decision.

Scopes: a token minted for issues carries write:issue and answers 403 on the
first request outside issues, naming no scope. Gitea cannot be asked what a
token may do — its own token listing needs a password — so `auth add --scopes`
records it, `auth list` and `config` show it, and a 403 says which category it
is likely to be. Documentation only; nothing is checked against it.

skills/use — the tea reference, 239 lines of it — becomes skills/api: what to
ask for, which endpoints paginate, and how to write a body. Every mention of
`tea` as a requirement is gone from the manifests, the READMEs, the runner and
the four other skills; what survives is the back-compat with the old plugin,
which is a decision and not a debt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-12 14:25:20 +05:00

9.9 KiB

Raw Blame History

AGENTS.md — the kettle plugin

This plugin is a thin wrapper over the kettle binary, which lives in this same repository at cli/ and is documented in cli/AGENTS.md. The binary owns everything mechanical: what an issue is, where the store lives, who this machine is, and how issues move to and from Gitea. Its layering, its walk, its round-trip guarantees and its tests are described there and are not repeated here — one design, one place.

What a plugin can carry that a binary cannot is the reason this directory still exists:

The rules an operator states. A binary can refuse to evict an origin: local issue; it cannot refuse to be run in the wrong directory, or decide that a migration clash is not a model's to resolve.
Routing. A description: in a SKILL.md frontmatter is the only thing that decides whether an agent loads a skill at all, and no generator can write it.
Procedures. How to turn a one-line request into a properly filled template, what to ask the user and what to never invent.

Installing the binary

kettle is not on anybody's PATH by default. Nothing in this plugin ships it, and a skill that assumes it exists fails with command not found: kettle — which is the clearest failure available, and every skill says what to do about it rather than falling back to something else.

cd cli && go build -o ~/.local/bin/kettle ./cmd/kettle    # from this repository
go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest

cli/go.mod says go 1.26 — the Gitea SDK requires it, so that is the minimum for anybody building this. vendor/ is committed, so what compiles is what is in this repository's history; what that does and does not buy is in cli/AGENTS.md.

An operator who sees command not found: kettle installs it and re-runs; there is nothing to configure in this plugin either way. kettle config is the command that explains where a run resolved to once it does exist.

The generated command reference

Every command line in skills/{project,issue,sync}/SKILL.md between

<!-- kettle:gen -->   …   <!-- /kettle:gen -->

is written by kettle gen skills from the command registry the binary is built from, and must not be edited by hand — the next run replaces it. Everything outside the markers is prose and comes back byte for byte, which is why the frontmatter is safe.

cd cli && go build -o /tmp/kettle ./cmd/kettle
/tmp/kettle gen skills --out plugins/kettle/skills            # rewrite the blocks
/tmp/kettle gen skills --out plugins/kettle/skills --check    # exit 1 if stale

--check is what a pre-commit hook or a CI step calls; it writes nothing. A file the run reports as without a region is one where somebody dropped the markers — it is left alone, never overwritten, and the fix is to put them back.

Groups and skills are not the same set, and that is the one seam. The binary groups its commands project, issue, sync, api; the plugin's skills are init, auth, project, issue, sync, api. The generator writes one <group>/SKILL.md, so:

skill	generated region	why
`issue`, `sync`, `api`	yes — the group of the same name	the skill and the group are the same subject
`project`	yes — `init`, `auth`, `config`, `gen`	the flag table `init` and `auth` point at
`init`	no	it is a procedure around one command, and it is operator-only
`auth`	no	it is a procedure around two, and it must not tempt a model into typing a token

api is the newest of those and the one that shows what the seam is for: the group exists because kettle api is not an issue command, and the skill exists because "which endpoint, and does it paginate" is a map somebody loads on its own. The group was named api rather than left as use precisely so that the three spellings — group, directory, /kettle:api — are one word.

The two skills with no region hold no flag tables of their own. They name a command and send the reader to /kettle:project, which is the point: a file that hand-copies a flag list is a file that will disagree with the binary in a month. If the generator ever cannot express what a skill needs, the answer is to change the generator, not to paste a block that will rot.

Layout

.claude-plugin/plugin.json   the manifest (the marketplace catalog is one level
                             up, in the repo root's .claude-plugin/)
agents/
  kettle-runner.md           subagent (Haiku): runs kettle commands, reports a
                             receipt. Batches only, and no opinions about content
hooks/
  hooks.json                 registers the one hook: PreToolUse(Bash)
  agents-sync.sh             keeps every directory canonical: AGENTS.md a real
                             file, CLAUDE.md a symlink to it
skills/
  init/    SKILL.md          /kettle:init — operator-only; the rules around
                             `kettle init`
  auth/    SKILL.md          /kettle:auth — the credential workflow around
                             `kettle auth` and `kettle init --login`
  project/ SKILL.md          generated flag reference: init, auth, config, gen
  issue/   SKILL.md          /kettle:issue — the offline commands
           references/format.md   THE canonical issue format; source of truth
  sync/    SKILL.md          /kettle:sync — the tracker commands
  api/     SKILL.md          /kettle:api — every Gitea entity with no command of
                             its own: pull requests, releases, tags, milestones,
                             branches, actions, webhooks. The map of endpoints,
                             and which of them paginate

references/format.md is the one document here that the binary does not generate and does not own a copy of. It is the format's statement of intent — identity, metadata, label namespaces, the per-type templates, the language rule — and it stays hand-written.

The rules that must survive, because a binary cannot state them

An origin: local issue is the only copy of that work. A push deletes the local file only after the tracker confirms the write and the number → slug ledger is written; nothing else deletes it, ever.
A closed issue is evicted, not archived — and a local one is never evicted, in any state, not even when it is named on the command line.
Body prose is Russian; the title and the section headers are English.
Do not run init inside a linked worktree. .kettle/ is gitignored, a worktree reaches the main checkout's store on its own, and a marker there gives one project two stores — the second of which disappears with the branch.
Which directory is the project is a statement a person makes. /kettle:init keeps disable-model-invocation: true for that reason, and never invents an --at.
A migration clash is the operator's to resolve. The binary stops and names both files; one of them may be somebody's only copy.

What this plugin no longer ships, and why

gone	replaced by
every Python script under `skills/*/scripts/` — the whole domain, bridge and transport	the `kettle` binary; see `cli/AGENTS.md` for the three runtime failures that motivated it
`tests/` — the stdlib `unittest` suite	`cd cli && go test ./...`
the guard hook and its entry in `hooks/hooks.json`	nothing. It existed to stop a `tea` command running under a login the model picked; the binary holds its own credentials and reads the login out of the project's config, so the failure is not expressible any more
`.claude/settings.local.json` → `env.GITEA_LOGIN`, the login pin	`<project>/.kettle/config.yaml` (a login name) plus `~/.config/kettle/logins.yaml` (the tokens, 0600, outside every working tree)
the tea plugin's own store marker	`.kettle/`; `kettle init` migrates an older layout in, and each migration is a move
`tea`, Gitea's own CLI, as an external requirement — a skill of reference docs for somebody else's flags, and a second set of logins nothing here could see	`kettle api`, one request through the transport the binary already had. What was 400 lines documenting another tool is now a map of endpoints; what was two credential stores is one

hooks/agents-sync.sh is unrelated to any of that and stays. It maintains the AGENTS.md convention by repairing the filesystem layout — a real file, with CLAUDE.md a symlink to it — and the convention itself is documented once, in the repository root's AGENTS.md. It cannot fail a tool call: it exits 0 on every path, including its own bugs — documentation maintenance is not permitted to break a build.

All of it is in git history. git log --diff-filter=D finds it if a decision needs to be re-read rather than re-derived.

Tests

The plugin has no test suite of its own; the binary's is the suite.

cd cli && go test ./...
/tmp/kettle gen skills --out plugins/kettle/skills --check

The second line is the plugin's only mechanical invariant: the documentation an agent reads agrees with the binary it is documenting.

Keeping this file true

Scope: everything under plugins/kettle/ — the skills, the runner subagent, the two hooks, and the group ⇄ skill seam. skills/ and agents/ carry no AGENTS.md of their own on purpose: a SKILL.md already states its own procedure, and a second document beside it would be the copy that goes stale.
Update it when a skill is added or removed (the layout and the generated-region table both name every one), a hook is added or its event changes, a rule in the rules that must survive changes, or the binary takes over something this plugin used to state.
Do not restate the binary's design. cli/AGENTS.md and the eight package files under it own that; if the two ever disagree, the binary is right and the prose is stale.

9.9 KiB Raw Blame History