feat: drop the kettle plugin; the binary writes its own skills
The plugin and the binary shipped on two release cadences and nothing on an operator's machine ever checked that the one they installed described the other. The generated flag block existed precisely so a renamed flag could not ship with documentation recommending the old one — and then shipped one version behind the registry it came from, which is the same bug one hop downstream. So the prose moved into the binary. `internal/scaffold` embeds every document; `kettle init` and `kettle gen scaffold` write them into a project's own `.claude/`. The two cannot disagree because there is one artefact. The namespace survived the move. A project's skills are flat, so the prefix is spelled into the directory name (`kettle-issue`); a project's *commands* take their namespace from a subdirectory, so `commands/kettle/init.md` is still `/kettle:init`. Four of the six command files are thin pointers at a skill, and that is what kept ~1,600 lines of `/kettle:…` cross-references true without a rewrite. `init` and `auth` lost `disable-model-invocation: true` — being a command is that property — and `auth` now restricts `allowed-tools` so a model cannot reach `kettle auth add` at all. `gen scaffold` writes files whole rather than splicing a region. The old refusal protected somebody's hand-written prose around the block; that prose is embedded now, so there is none to protect, and preserving local edits would freeze a project's documentation at whatever version first initialized it. `--check` warns before an upgrade discards one. The plugin's `agents-sync.sh` — 141 lines of Python behind a filename that said `.sh` — became `internal/mirror` and `kettle mirror`. Same seven branches, same refusal to merge two real files that differ, now with a table test per branch and a check that a repair converges in one pass. `--hook` is the PreToolUse form and exits 0 on every path including a panic. It is opt-in per project, which is strictly narrower than the plugin hook that was on for everybody who installed it. `kettle init --interactive` walks a person through the login, the token (read with the echo off, so it lands in no history and no file), the repository, the `.claude/` tree and the mirror hook. It refuses a stdin that is not a terminal and names the flags instead: every question it asks has one, and it performs nothing itself, so an interactive run and a flag run are one code path. Two rules that used to be prose are now the binary's: init refuses a linked worktree and names the main checkout, and writing into an existing `.claude/settings.json` is refused with the snippet printed rather than reformatting a file the operator commits. The scaffold version stamp went to its own `.kettle/scaffold.yaml` rather than into `config.yaml`, because unknown keys there are a hard error and that file may be committed and read by whatever build each machine has. golang.org/x/term becomes a direct dependency; it was already in the tree indirectly, so no module was added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
naudachu
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: kettle-runner
|
||||
description: Runs `kettle` commands and hands back a compact receipt. Use for the mechanical half of issue work — a bulk pull, pushing a set the caller already named, posting a comment from a file, bootstrapping labels, rebuilding the index or the tree. It runs commands; it never decides what an issue should say. Delegate a batch, not a single call.
|
||||
tools: Bash, Read, Grep, Glob, Skill
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# kettle-runner — the execution layer
|
||||
|
||||
You run `kettle` commands and hand back a short receipt. The binary holds the
|
||||
mechanics; the skills hold the meaning; you hold neither.
|
||||
|
||||
**You have no opinion about content.** Titles, bodies, types, labels,
|
||||
dependencies, what is worth filing and what is worth closing — all of that was
|
||||
decided before you were called, and if it was not, the answer is to say so, not
|
||||
to fill the gap yourself.
|
||||
|
||||
## Where the commands come from
|
||||
|
||||
Load the skill, do not remember the flags:
|
||||
|
||||
- `/kettle:sync` — `pull`, `push`, `remote`, `comment`, `close`, `labels`,
|
||||
`sync-evict`
|
||||
- `/kettle:issue` — `new`, `check`, `ac`, `tree`, `index`, `evict`
|
||||
- `/kettle:project` — `config`, `auth list`
|
||||
- `/kettle:api` — `api`, for the Gitea entities that have no command of their own
|
||||
|
||||
Invoke `Skill` with the one that owns the task at the start and use the generated
|
||||
command reference it carries verbatim. That block is written from the binary's
|
||||
own command registry, so it cannot disagree with the binary; a flag you recall
|
||||
from another session can. If the reference does not document a flag, it does not
|
||||
exist — report that instead of trying it. `kettle help <command>` is the same
|
||||
truth if you need it in a hurry.
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. **`kettle` only.** No curl at a tracker, no other CLI, no request you composed
|
||||
yourself. The binary carries the project's credentials; there is no login for
|
||||
you to name and none for you to choose. `kettle api` is a kettle command and
|
||||
is yours to run **as the caller spelled it** — endpoint, method and body come
|
||||
from the task, and a `-X DELETE` is never something you add. An entity nobody
|
||||
named an endpoint for is a finding for the caller, not a request for you to
|
||||
improvise.
|
||||
2. **No writing to issue files.** You have no `Edit` and no `Write`. Commands
|
||||
write files; you do not. If a task needs a body edited or a metadata field
|
||||
changed by hand, stop and say which file and which field. `kettle ac` is the
|
||||
one command that touches a body and it changes a single character: tick only
|
||||
the items the caller named, by the number or the substring the caller gave.
|
||||
Whether a criterion is actually met is a judgement about content, and content
|
||||
is never yours.
|
||||
3. **Push only what you were told to push.** `kettle push` publishes to a tracker
|
||||
other people read, **and it deletes the local file on success** — so a widened
|
||||
set is not an over-share, it is somebody else's working copy gone. Run it with
|
||||
the ids or filter the caller named. Never widen the set, never run a bare
|
||||
`kettle push` because it looked like the obvious next step, and **never pass
|
||||
`--force`** — a validation failure is a result to report, not an obstacle to
|
||||
route around. Report the number and URL it printed; that is now the only
|
||||
address the issue has.
|
||||
4. **Close only the ids the caller named.** Same discipline as push. Never infer
|
||||
that an issue is finished because its checkboxes are ticked or its branch is
|
||||
merged. `--reopen` is the same rule backwards. Retitling is not yours, and
|
||||
deleting anything on a tracker is never yours.
|
||||
|
||||
Two local deletions are allowed, both only when the caller asked for them:
|
||||
push's own, on the issues you were told to push, and eviction (`kettle evict`
|
||||
/ `kettle sync-evict`) of closed issues. Run eviction with `--dry-run` first
|
||||
and report what it named. It refuses to touch an `origin: local` issue by
|
||||
itself — that is the binary's guarantee, not your judgement, and it is not a
|
||||
reason to point it at a store nobody asked you to clean.
|
||||
5. **One retry, maximum.** A command that fails twice is a finding. Do not
|
||||
permute flags looking for one that works.
|
||||
6. **No payload dumps.** Never `cat` a pulled issue body back into your report.
|
||||
`kettle` prints compact output by design; the caller reads the files it needs
|
||||
from disk.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Load the skill you need.
|
||||
2. Run the commands. Prefer one filtered call over a loop — `kettle pull
|
||||
--milestone 6` pages the list endpoint, `kettle pull 41 42 43 …` is a request
|
||||
per issue and per blocker.
|
||||
3. If a command exits non-zero, capture the last lines of stderr and stop that
|
||||
branch. Keep going on independent branches.
|
||||
4. Report.
|
||||
|
||||
## Report format
|
||||
|
||||
Your final message is the return value. Keep it under ~20 lines. No preamble, no
|
||||
restatement of the request, no advice about what to do next.
|
||||
|
||||
```
|
||||
ran:
|
||||
kettle pull --milestone 6 --state all ok 7 issues, 3 threads
|
||||
kettle index ok INDEX.md rebuilt
|
||||
kettle push wire-sqlc-appclick FAIL exit 1
|
||||
|
||||
touched: .kettle/issues/{a,b,c}.md, .kettle/issues/INDEX.md
|
||||
|
||||
failed: kettle push wire-sqlc-appclick
|
||||
ERROR wire-sqlc-appclick: missing section '## Acceptance criteria'
|
||||
|
||||
blocked: none
|
||||
```
|
||||
|
||||
- `ran` — one line per command: what, ok/FAIL, and the one number that matters.
|
||||
- `touched` — paths only. Never contents.
|
||||
- `failed` — the command, then stderr verbatim, trimmed to the lines that name
|
||||
the cause. Quote it exactly; do not paraphrase an error.
|
||||
- `blocked` — what you refused to decide, phrased as the question the caller has
|
||||
to answer. `none` when there is nothing.
|
||||
|
||||
## Known stops
|
||||
|
||||
Report these and halt; none of them is yours to resolve.
|
||||
|
||||
| Condition | Report |
|
||||
|---|---|
|
||||
| `command not found: kettle` | `blocked: kettle is not installed — operator builds it from cli/ or go install`s it |
|
||||
| `no .kettle/ found — searched up from …` | `blocked: not a project — operator must run /kettle:init here` |
|
||||
| no login pinned, an unknown login name, 401/403 | `blocked: credential — operator runs /kettle:auth`, with the binary's own line |
|
||||
| `kettle check` errors before a push | the validator's own lines, verbatim |
|
||||
| a dependency is still `origin: local` | name the id; the caller decides whether to push it |
|
||||
| a milestone or label does not exist in the repo | the command prints the real ones — pass that list through |
|
||||
| a command asks for a decision (type, label, `--force`) | `blocked:` with the question |
|
||||
| the tracker refuses a close because the issue is still blocked | the tracker's own line and the blocker's number; the caller decides |
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
description: Reach everything Gitea has that is not an issue — pull requests, releases, tags, milestones, branches, commits, actions, webhooks — with `kettle api`.
|
||||
argument-hint: "[the endpoint, or what you want from the tracker]"
|
||||
---
|
||||
|
||||
Load the **`kettle-api`** skill and follow it. Which endpoint answers which
|
||||
question, which of them paginate, and what `-X DELETE` requires are all mapped
|
||||
there.
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
One request, under the login this project already pins — no second tool and no
|
||||
second credential. Issues are not handled here: `/kettle:issue` works on them
|
||||
offline and `/kettle:sync` moves them.
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
description: Give `kettle` a Gitea credential and choose which login this project runs under — `kettle auth list/add/remove` manages the machine-wide token file, `kettle init --login <name>` pins one of those names into `.kettle/config.yaml`. Invoke when a sync command reports no login, a 401, or an unknown login name, or to switch the account this project's issues are pushed under. The OPERATOR picks the login; you never type a token.
|
||||
allowed-tools: Bash(kettle auth list:*), Bash(kettle config:*)
|
||||
---
|
||||
|
||||
# /kettle:auth — the credential a project runs under
|
||||
|
||||
Two files, and the split is the whole design.
|
||||
|
||||
| where | what is in it | who writes it |
|
||||
|---|---|---|
|
||||
| `~/.config/kettle/logins.yaml` | the tokens, one file per machine, mode 0600, outside every working tree | `kettle auth add` |
|
||||
| `<project>/.kettle/config.yaml` | the **name** of one of those logins, and the tracker repo | `kettle init --login … --repo …` |
|
||||
|
||||
A name is worth nothing on its own, which is what makes it safe to keep in a
|
||||
file inside a repository. A token in a working tree ends up in a commit
|
||||
eventually, and a secret that has ever been pushed has to be rotated.
|
||||
`$KETTLE_CONFIG_HOME` or `$XDG_CONFIG_HOME` move the machine file;
|
||||
`KETTLE_LOGIN`, `KETTLE_URL` and `KETTLE_TOKEN` override it outright, which is
|
||||
how CI runs with no token on disk.
|
||||
|
||||
**No credential is pinned in `.claude/` anywhere, and no hook rewrites a
|
||||
`--login` argument.** That mechanism is gone with the Python scripts. If you find
|
||||
a `GITEA_LOGIN` in a settings file, it is dead weight from the old plugin — the
|
||||
only thing `kettle` ever writes into `.claude/settings.json` is the optional
|
||||
`AGENTS.md` mirror hook, which holds no identity of any kind.
|
||||
|
||||
## The one hard rule: the operator chooses, and holds the token
|
||||
|
||||
- **Never pick a login.** Not from memory, not from the repo URL, not from a
|
||||
previous session. Present the choice with `AskUserQuestion` — name, url and
|
||||
user out of `kettle auth list` — and let the operator answer. Exactly one login
|
||||
on the machine is the only case where you may propose, and you still confirm.
|
||||
- **Never type, echo, paste or read a token.** `kettle auth add` takes it on
|
||||
stdin precisely so it does not land in shell history; a token that goes through
|
||||
a model's context is a token in a transcript. Adding a login is the operator's
|
||||
own terminal, not a Bash call you make for them.
|
||||
|
||||
## Steps
|
||||
|
||||
1. See what this machine holds. It never prints a token, and there is no flag to
|
||||
make it:
|
||||
|
||||
```bash
|
||||
kettle auth list
|
||||
```
|
||||
|
||||
2. **Nothing there** — stop and hand the operator the command to run themselves:
|
||||
|
||||
```bash
|
||||
kettle init --interactive # prompts for it, echo off
|
||||
kettle auth add --name noodles --url https://git.example.com --user naudachu < token.txt
|
||||
pass show gitea/token | kettle auth add --name noodles --url https://git.example.com
|
||||
```
|
||||
|
||||
The first is the one to suggest to a person at a terminal: it reads the token
|
||||
with the echo turned off, so it is in no history, no file and no scrollback.
|
||||
**It is not a command for you to run** — it refuses a stdin that is not a
|
||||
terminal, and that refusal is correct. `--user` is documentation only, and
|
||||
`kettle auth remove <name>` forgets one.
|
||||
|
||||
3. **Pin the choice into the project.** Ask `kettle config` first and only
|
||||
proceed if it answers with a project — `kettle init` in a directory that is
|
||||
not one would *create* a project there, which is the one statement that is
|
||||
never yours to make (`/kettle:init`):
|
||||
|
||||
```bash
|
||||
kettle config
|
||||
kettle init --login noodles
|
||||
```
|
||||
|
||||
`init` on an initialized project prints `already initialized — nothing to do`
|
||||
and rewrites only the settings it was given, so the repo pinned earlier stays.
|
||||
|
||||
4. Confirm with `kettle config`. Tell the operator which login is pinned and
|
||||
which file it went in. It is live immediately — nothing caches it, no restart.
|
||||
|
||||
```
|
||||
login noodles
|
||||
url https://git.example.com
|
||||
token (set)
|
||||
repo claude-skills/marketplace
|
||||
```
|
||||
|
||||
## When it goes wrong
|
||||
|
||||
| what you see | what it means |
|
||||
|---|---|
|
||||
| `no login "X" in …/logins.yaml — known: …` | the project pins a name this machine does not hold. Either add it (step 2) or pin one that is there |
|
||||
| `no .kettle/ found — searched up from …` | not a project. `/kettle:init`, and it is the operator's to run |
|
||||
| `401` / `403` from a sync command | report it verbatim. Do **not** try another login, and do not edit or remove one to route around it — that is somebody's identity, not a setting |
|
||||
| `token none` in `kettle config` | a name is pinned but no credential answers to it |
|
||||
|
||||
## Scopes: what the token is allowed to do
|
||||
|
||||
Gitea mints a token with scopes, spelled `<read|write>:<category>`. A token made
|
||||
for issues carries `write:issue` — and that is enough for everything
|
||||
`/kettle:issue` and `/kettle:sync` do, and **not** enough for anything
|
||||
`/kettle:api` reaches: releases, pull requests, branches, tags and actions all
|
||||
sit under `repository`.
|
||||
|
||||
| doing | needs |
|
||||
|---|---|
|
||||
| pull, push, comment, close, evict | `write:issue` |
|
||||
| `kettle labels` | `write:issue` |
|
||||
| `kettle api` on releases, PRs, tags, branches, actions | `write:repository` too |
|
||||
| reading any of those without writing | the `read:` half is enough |
|
||||
|
||||
`kettle auth add --scopes write:issue,write:repository` writes that down beside
|
||||
the login. **It is a note and nothing else** — nothing is checked against it and
|
||||
nothing is refused because of it. It is worth writing down because the instance
|
||||
will not answer the question: Gitea's own token listing needs a password rather
|
||||
than a token, so a token cannot be asked what it may do. `kettle auth list` and
|
||||
`kettle config` show what was recorded; `(not recorded)` means nobody wrote it
|
||||
down, never "none".
|
||||
|
||||
A **403** from a sync command or from `kettle api` is usually this and says so.
|
||||
Minting a new token is the operator's job in the web UI — the same flow as step
|
||||
2 above, with both scopes ticked this time. Never remove or re-point a login to
|
||||
route around a 403.
|
||||
|
||||
**No `kettle` on PATH?** `command not found: kettle` is the whole story — and it
|
||||
means the binary that wrote this file has since moved or been removed, because
|
||||
nothing else could have put it here. Stop and tell the operator to reinstall it:
|
||||
`go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest`, or
|
||||
`cd cli && make install` in a checkout of that repository (go.mod requires
|
||||
**go 1.26**).
|
||||
|
||||
The full flag table for `auth`, `config` and `init` is the generated block in
|
||||
`/kettle:project`.
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
description: Make THIS directory a project that tracks issues — run `kettle init`, which creates the `.kettle/` marker every other command resolves the store from, migrates an older store in, gitignores it, and writes this command file and its skills. Carries the rules the binary cannot enforce — never an `--at` nobody named, never a migration clash resolved for them.
|
||||
argument-hint: "[--at DIR] [--interactive] [--login NAME] [--repo owner/name] [--dry-run]"
|
||||
allowed-tools: Bash(kettle init:*), Bash(kettle config:*), Bash(git rev-parse:*)
|
||||
---
|
||||
|
||||
# /kettle:init — make this directory a project
|
||||
|
||||
Initializing is a statement, and the operator makes it: *this* directory is the
|
||||
project whose issues live in it. Nothing infers it — `.git` is in every clone,
|
||||
and a tool that inferred its root from one wrote other projects' issues into its
|
||||
own versioned cache. It is answered once, by a person, and every command
|
||||
downstream reads the answer instead of guessing.
|
||||
|
||||
**This is a command, not a skill, and that is the point.** It is invoked by an
|
||||
operator who typed it. There is no `description:` here for a model to match on,
|
||||
because "which directory is the project" is not a question a model gets to answer
|
||||
on its own.
|
||||
|
||||
The binary does the work and is idempotent. What this file carries is what it
|
||||
cannot decide.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Run it, passing the operator's arguments through unchanged:
|
||||
|
||||
```bash
|
||||
kettle init $ARGUMENTS
|
||||
```
|
||||
|
||||
With no `--at` it initializes the current directory. **Never supply an `--at`
|
||||
the operator did not name.** Which directory is the project is the one
|
||||
question this command exists to have a person answer; picking a plausible one
|
||||
is the failure the marker replaces.
|
||||
|
||||
2. Report what it printed, verbatim. `already initialized — nothing to do` is a
|
||||
success, not something to work around.
|
||||
|
||||
`--login` pins a login by name and `--repo` names the tracker repository; both
|
||||
are optional and both can be added later by running `init` again — it writes the
|
||||
config without disturbing settings it was not given. Neither is a credential:
|
||||
the tokens live in one file per machine, `/kettle:auth`.
|
||||
|
||||
## `--interactive` is for a person at a terminal
|
||||
|
||||
It walks the operator through the login, the repository, this `.claude/` tree and
|
||||
the `AGENTS.md` mirror hook, one question at a time.
|
||||
|
||||
**Do not run it.** It refuses a stdin that is not a terminal and says so, which is
|
||||
the right failure — but the right move is not to reach for it in the first place.
|
||||
Every question it asks has a flag: `--login`, `--repo`, `--scaffold`,
|
||||
`--mirror-hook`. Pass the flags the operator named and let the binary answer the
|
||||
rest.
|
||||
|
||||
## When it stops
|
||||
|
||||
- **A linked worktree.** The binary refuses, and it is right to: `.kettle/` is
|
||||
gitignored, so a worktree has no marker by design and reaches the main
|
||||
checkout's store on its own — the walk crosses to it through the `gitdir:` in
|
||||
the `.git` *file*. A marker here would give one project two stores, and the
|
||||
second is deleted with the branch. What needs initializing, if anything, is the
|
||||
main checkout, and the refusal names it.
|
||||
- **A name clash on the migration** — the same file name on both sides. It exits
|
||||
having changed nothing and names the files. Report that. Do **not** move,
|
||||
delete, or merge either side: one of them may be an `origin: local` issue,
|
||||
which *is* the issue and the only copy of that work. The operator decides
|
||||
which survives.
|
||||
- **A marker already exists above this directory.** A second one gives that
|
||||
project a second store and the nearer one wins. Confirm with the operator
|
||||
before going ahead; usually they are standing in a subdirectory and there is
|
||||
nothing to do.
|
||||
|
||||
**No `kettle` on PATH?** `command not found: kettle` is the whole story — and it
|
||||
means the binary that wrote this file has since moved or been removed, because
|
||||
nothing else could have put it here. Stop and tell the operator to reinstall it:
|
||||
`go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest`, or
|
||||
`cd cli && make install` in a checkout of that repository (go.mod requires
|
||||
**go 1.26**).
|
||||
|
||||
## After
|
||||
|
||||
- `/kettle:issue` works now — offline, no login, no network.
|
||||
- `/kettle:auth` puts a token on this machine and pins the login this project
|
||||
runs under; needed only for the tracker side, `/kettle:sync`.
|
||||
- `kettle config` prints every path and setting this directory resolved to, and
|
||||
is the first thing to run when something looks like it landed in the wrong
|
||||
place. It also reports when this `.claude/` tree was written by an older
|
||||
`kettle` than the one now installed.
|
||||
|
||||
The full flag table for `init` is the generated block in `/kettle:project`.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
description: Work on this project's issues offline — create, read, grep, validate, tick checkboxes, evict, and walk the dependency graph.
|
||||
argument-hint: "[what you want to do with an issue]"
|
||||
---
|
||||
|
||||
Load the **`kettle-issue`** skill and follow it. Everything about what an issue is
|
||||
— the format, the taxonomy, validation, checkboxes, the dependency graph — lives
|
||||
there, along with the canonical format reference it points at.
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
This half is entirely offline: issues are markdown files under
|
||||
`<project>/.kettle/issues/` and need no login and no network. Moving them to or
|
||||
from the tracker is `/kettle:sync`.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Look up the exact flags and defaults of the project-level kettle commands — init, auth, config, gen, mirror.
|
||||
argument-hint: "[the command whose flags you want]"
|
||||
---
|
||||
|
||||
Load the **`kettle-project`** skill and follow it. It carries the generated flag
|
||||
table for every project-level command, written from the registry the binary was
|
||||
built from.
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
`kettle help <command>` prints the same thing in a terminal, and is the faster
|
||||
answer when the operator is already in one.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Move issues between this project's local store and its Gitea tracker — pull, push, list, comment, close, evict.
|
||||
argument-hint: "[what to pull, push, comment on or close]"
|
||||
---
|
||||
|
||||
Load the **`kettle-sync`** skill and follow it. The round trip and the rule that
|
||||
holds it — the store keeps what has not left this machine, so a successful push
|
||||
deletes the local file — are stated there in full.
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
What an issue *is* belongs to `/kettle:issue` and needs no network. Everything
|
||||
Gitea has that is not an issue is `/kettle:api`.
|
||||
@@ -0,0 +1,246 @@
|
||||
---
|
||||
name: kettle-api
|
||||
description: Everything Gitea has that is not an issue — pull requests, releases, tags, branches, milestones, labels, commits, actions, webhooks, notifications, tracked times, users, repositories — reached with `kettle api`, one endpoint per request, under the login the project already pins. Load when the user asks to open or review a PR, cut or edit a release, make a milestone or a tag, look at branches or commits, read notifications or actions, or hit any Gitea endpoint by hand. Issues are NOT handled here: /kettle:issue works on them offline and /kettle:sync moves them to and from the tracker.
|
||||
---
|
||||
|
||||
# /kettle:api — Gitea beyond issues
|
||||
|
||||
`kettle api <endpoint>` is one authenticated request to the Gitea this project is
|
||||
pinned to. No second tool, no second login: the URL, the token and the repository
|
||||
are the ones `/kettle:auth` and `kettle init` already resolved, and the request
|
||||
body is filed under `.kettle/payload/` like every other request kettle makes.
|
||||
|
||||
This skill is the map of what to ask for. `kettle help api` is the flag
|
||||
reference, and it is generated from the binary — the block at the bottom of this
|
||||
file is the same text.
|
||||
|
||||
## Issues are somewhere else
|
||||
|
||||
`kettle api` can reach an issue and must not be used to. An issue read this way
|
||||
comes back as a full JSON payload — every label object, every URL, the whole
|
||||
comment thread — which is precisely what the other two skills exist to keep out
|
||||
of the context window.
|
||||
|
||||
| Skill | Scope |
|
||||
|---|---|
|
||||
| `/kettle:issue` | issues as units of work — create, read, grep, validate, tick, dependency graph. Offline. |
|
||||
| `/kettle:sync` | moving issues between the local store and the tracker — pull, push, comment, close, evict. |
|
||||
|
||||
The one exception is an issue endpoint that is not about the issue's content:
|
||||
`issues/{n}/comments` is also **a pull request's** comment thread, and
|
||||
`PATCH issues/{n}` is also how a pull request's title and body are edited. Gitea
|
||||
numbers issues and pull requests in one sequence and serves both under
|
||||
`/issues/`.
|
||||
|
||||
## What is a command and what is a request
|
||||
|
||||
Reach for the command where there is one: it knows the format, the store and the
|
||||
round trip. Everything else is an endpoint.
|
||||
|
||||
| Subject | How to reach it | Pages? |
|
||||
|---|---|---|
|
||||
| issues (create, read, tick, validate) | `/kettle:issue` — offline, no request at all | — |
|
||||
| issues (pull, push, comment, close, evict) | `/kettle:sync` | handled |
|
||||
| the canonical `type/*` and `severity/*` labels | `kettle labels` | handled |
|
||||
| this repository's own releases, with binaries | `cd cli && make release TAG=v1.2.3` | — |
|
||||
| everything below | `kettle api` | see the column |
|
||||
|
||||
| Entity | Endpoint | Pages? |
|
||||
|---|---|---|
|
||||
| pull requests | `repos/{owner}/{repo}/pulls` | **yes** |
|
||||
| one pull request | `repos/{owner}/{repo}/pulls/{n}` | no |
|
||||
| create a pull request | `POST repos/{owner}/{repo}/pulls` | no |
|
||||
| edit a PR's title or body | `PATCH repos/{owner}/{repo}/issues/{n}` | no |
|
||||
| a PR's or issue's comments | `repos/{owner}/{repo}/issues/{n}/comments` | **yes** |
|
||||
| edit one comment | `PATCH repos/{owner}/{repo}/issues/comments/{id}` | no |
|
||||
| reviews on a PR | `repos/{owner}/{repo}/pulls/{n}/reviews` | **yes** |
|
||||
| merge a PR | `POST repos/{owner}/{repo}/pulls/{n}/merge` | no |
|
||||
| releases | `repos/{owner}/{repo}/releases` | **yes** |
|
||||
| one release by tag | `repos/{owner}/{repo}/releases/tags/{tag}` | no |
|
||||
| tags | `repos/{owner}/{repo}/tags` | **yes** |
|
||||
| branches | `repos/{owner}/{repo}/branches` | **yes** |
|
||||
| commits | `repos/{owner}/{repo}/commits` | **yes** |
|
||||
| milestones | `repos/{owner}/{repo}/milestones` | **yes** |
|
||||
| labels (all of them, not just canonical) | `repos/{owner}/{repo}/labels` | **yes** |
|
||||
| webhooks | `repos/{owner}/{repo}/hooks` | **yes** |
|
||||
| action tasks | `repos/{owner}/{repo}/actions/tasks` | **yes** |
|
||||
| tracked times | `repos/{owner}/{repo}/times` | **yes** |
|
||||
| the repository itself | `repos/{owner}/{repo}` | no |
|
||||
| notifications | `notifications` | **yes** |
|
||||
| who this token is | `user` | no |
|
||||
| an organization's repositories | `orgs/{org}/repos` | **yes** |
|
||||
|
||||
`{owner}` and `{repo}` are filled in from the project's configuration. A path
|
||||
that names a repository in full is left alone — `repos/other-owner/other/releases`
|
||||
reads another repository on the same instance, which is why there is no `--repo`
|
||||
flag. Another **instance** is `KETTLE_URL` and `KETTLE_TOKEN`, not a flag.
|
||||
|
||||
What the instance actually serves is its own version's business; its API docs at
|
||||
`<instance-url>/api/swagger` are the authority when an endpoint answers 404.
|
||||
|
||||
## Pagination is yours
|
||||
|
||||
**One invocation is one HTTP request.** `kettle api` never follows a list to its
|
||||
end, because a passthrough that silently stitched pages together would report as
|
||||
one answer something that was several.
|
||||
|
||||
So for every row marked **yes** above:
|
||||
|
||||
```bash
|
||||
kettle api 'repos/{owner}/{repo}/pulls?state=open&limit=50' # first page, 50 rows
|
||||
kettle api 'repos/{owner}/{repo}/pulls?state=open&limit=50&page=2'
|
||||
```
|
||||
|
||||
- `limit` is capped by the instance (`MAX_RESPONSE_ITEMS`, 50 by default); the
|
||||
default page size is 30.
|
||||
- **A short page is the last one.** Ask for 50, count what came back: fewer than
|
||||
50 means there is no page 3. That is the same rule the binary's own listings
|
||||
use, and it needs no response headers.
|
||||
- Quote any endpoint holding `?` or `&`, or the shell takes it apart.
|
||||
- Walking many pages of anything into your own context is a mistake before it is
|
||||
a request. Narrow the query (`state=`, `since=`, `q=`), or pipe through `jq`
|
||||
and keep the two fields you needed.
|
||||
|
||||
## Writing a body
|
||||
|
||||
Two ways, and the choice is about the body, not the endpoint:
|
||||
|
||||
```bash
|
||||
# small and flat: every value is a string
|
||||
kettle api --field body=lgtm repos/{owner}/{repo}/issues/7/comments
|
||||
|
||||
# anything real — multi-line, markdown, booleans, numbers, nesting
|
||||
mkdir -p tmp/release
|
||||
cat > tmp/release/v0-2-0.json <<'EOF'
|
||||
{"tag_name": "v0.2.0", "name": "v0.2.0", "draft": false,
|
||||
"body": "## Changes\n\nMulti-line markdown with `code`."}
|
||||
EOF
|
||||
kettle api --data @tmp/release/v0-2-0.json repos/{owner}/{repo}/releases
|
||||
```
|
||||
|
||||
- A body implies `POST`; anything else is `-X PUT`, `-X PATCH`, `-X DELETE`.
|
||||
- Newlines inside a JSON string are `\n`. Composing from a file:
|
||||
`jq -Rs '{body: .}' < body.md > tmp/pull/x.json`.
|
||||
- `--field` values are **always strings**. A `draft: false` or a number is a
|
||||
`--data` body — guessing types is how a `tag_name` of `1.0` goes up as a
|
||||
number.
|
||||
- Keep `tmp/` gitignored and keep the file: a `PATCH` is usually the same body
|
||||
with one line changed. `kettle` files its own copy under `.kettle/payload/`
|
||||
automatically; that directory is the transport's and nothing hand-made goes in
|
||||
it.
|
||||
- Attachments are `multipart/form-data` and this command sends JSON. Upload
|
||||
release binaries with the release tooling (`make release`), or the web UI.
|
||||
|
||||
## Deleting
|
||||
|
||||
`-X DELETE` needs `--yes` in the same invocation, and the refusal happens before
|
||||
anything is sent:
|
||||
|
||||
```bash
|
||||
kettle api -X DELETE --yes repos/{owner}/{repo}/releases/12
|
||||
```
|
||||
|
||||
That flag is the whole gate. **Whether a thing should be deleted is the
|
||||
operator's call, not a step in a plan** — ask, do not assume, and never widen a
|
||||
deletion past what was named.
|
||||
|
||||
## When it says 403
|
||||
|
||||
Gitea scopes a token as `<read|write>:<category>`, and a token minted to file
|
||||
issues carries `write:issue` and nothing else. Releases, pull requests, branches,
|
||||
tags and actions are all `repository`, so that token answers **403 on the first
|
||||
`kettle api` outside issues** — and the 403 names no scope.
|
||||
|
||||
`kettle auth list` shows what each login on this machine recorded; `kettle config`
|
||||
shows what this project resolved. Nothing can be read back off the instance
|
||||
(Gitea's own token listing needs a password, not a token), so a scope that was
|
||||
never written down is a scope nobody knows. Minting a new token is the operator's
|
||||
job, in the web UI — `/kettle:auth` has the procedure.
|
||||
|
||||
## What is not an API call at all
|
||||
|
||||
| Want | Do |
|
||||
|---|---|
|
||||
| check out a PR branch, clone, push | `git`. This is git's job and always was |
|
||||
| who am I | `kettle api user` |
|
||||
| open something in a browser | nothing here; hand the user the URL |
|
||||
| add a login, list logins, ssh keys | `/kettle:auth`, and adding one is the operator's |
|
||||
| administer users or the instance | nothing here. Not an agent's work |
|
||||
|
||||
The canonical issue format lives in
|
||||
[`../issue/references/format.md`](../issue/references/format.md) — it describes
|
||||
local files, not requests.
|
||||
|
||||
<!-- kettle:gen -->
|
||||
**Generated from the kettle command registry by `kettle gen scaffold`.** Everything between the two markers is replaced on the next run — the prose around it is embedded in the binary and replaced with it.
|
||||
|
||||
## `kettle api <endpoint>`
|
||||
|
||||
one request to this project's Gitea, for everything that is not an issue
|
||||
|
||||
Releases, pull requests, milestones, branches, tags, actions, webhooks,
|
||||
notifications: everything Gitea has that this binary has no command for. One
|
||||
invocation is ONE request — the credentials, the repository and the payload
|
||||
scratchpad are the ones this project already resolved, so there is nothing to
|
||||
configure and no second tool to log in.
|
||||
|
||||
THE ENDPOINT IS SPELLED THE WAY GITEA'S OWN DOCUMENTATION SPELLS IT. A bare path
|
||||
is taken as relative to `/api/v1/`; a path that already begins `/api/` is sent as it
|
||||
stands, which is how anything outside v1 is reached; a full URL is allowed only
|
||||
on the instance this project points at, because every request here carries the
|
||||
project's token in a header and a URL somewhere else would hand that token over.
|
||||
`{owner}` and `{repo}` are filled in from the project's configuration. Quote an
|
||||
endpoint that contains ? or & or the shell will take it apart.
|
||||
|
||||
ANOTHER REPOSITORY NEEDS NO FLAG — write its address into the path
|
||||
(`repos/other-owner/other-repo/releases`) and nothing is substituted. There is no
|
||||
--repo and no --login here for the same reason there is none on push or pull:
|
||||
which login a project runs under is a fact about the project. Another INSTANCE
|
||||
is KETTLE_URL and KETTLE_TOKEN, which is also what a CI run uses.
|
||||
|
||||
THE ANSWER IS THE SERVER'S BYTES ON STDOUT, unparsed and unreformatted — pipe it
|
||||
to jq, redirect it to a file. There is no flag that names an output file: in
|
||||
this tree --out is the issue store, and one word meaning two things is exactly
|
||||
the trap the tool this replaces set with an -o that wrote a file called "json".
|
||||
|
||||
IT DOES NOT PAGINATE. One call is one request, so a listing answers with one
|
||||
page: ask for the next with ?page=2, and for a bigger one with ?limit=50 (the
|
||||
server's own default is 30, its maximum is usually 50). A passthrough that
|
||||
stitched pages together silently would report as one answer something that was
|
||||
several.
|
||||
|
||||
ISSUES ARE NOT THIS COMMAND'S JOB even though it can reach them. An issue read
|
||||
this way arrives as a full JSON payload — every comment, every label object,
|
||||
every URL — which is what /kettle:issue and /kettle:sync exist to keep out of a
|
||||
context window. Use pull, push, comment and close.
|
||||
|
||||
A 403 here is usually the token rather than the request: a token minted for
|
||||
issues carries write:issue, and releases, pull requests, branches and tags are
|
||||
all under repository. `kettle auth list` shows what each login records.
|
||||
|
||||
-X DELETE NEEDS --yes. Everything else goes through as typed; a deletion does
|
||||
not, because a flag typed on purpose is an operator's decision and the URL of a
|
||||
release is one character away from the URL of the wrong release.
|
||||
|
||||
What it cannot do: an upload. Release attachments are multipart/form-data and
|
||||
this sends JSON — the release tooling in cmd/release does those.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--X` | — | the same flag as --method, spelled the way curl and the tool this replaces spell it |
|
||||
| `--data` | — | the request body: @file, @- for standard input, or the JSON itself |
|
||||
| `--field` | — | key=value, added to a JSON body as a string; repeatable |
|
||||
| `--method` | — | GET, POST, PUT, PATCH or DELETE (default GET, or POST when there is a body) |
|
||||
| `--status` | `false` | print the status line on standard error |
|
||||
| `--yes` | `false` | confirm a DELETE |
|
||||
|
||||
```bash
|
||||
kettle api repos/{owner}/{repo}/releases # the latest page of releases, as JSON
|
||||
kettle api user # who this project's token belongs to
|
||||
kettle api 'repos/{owner}/{repo}/pulls?state=open&limit=50' # quote anything with ? or & in it
|
||||
kettle api --data @tmp/release/v0-2-0.json repos/{owner}/{repo}/releases # a body from a file; POST is implied
|
||||
kettle api --field body=lgtm repos/{owner}/{repo}/issues/7/comments # a small body without a file
|
||||
kettle api -X DELETE --yes repos/{owner}/{repo}/releases/12 # a deletion, said out loud
|
||||
kettle api repos/{owner}/{repo}/milestones | jq '.[].title' # the bytes are the server's; jq is yours
|
||||
```
|
||||
<!-- /kettle:gen -->
|
||||
@@ -0,0 +1,433 @@
|
||||
---
|
||||
name: kettle-issue
|
||||
description: Work with this project's issues as units of work — create, read, grep, validate, tick checkboxes, evict closed ones, and walk their dependency graph, with the `kettle` binary's offline commands (new, check, ac, tree, index, evict). Entirely offline; issues are local markdown files in `.kettle/issues/` and need no tracker, no login and no network. Load when the user asks to file or create an issue, read or find issues, check one against the format, or see what depends on what. Pushing to or pulling from Gitea is /kettle:sync.
|
||||
---
|
||||
|
||||
# /kettle:issue — issues as units of work
|
||||
|
||||
An issue is a markdown file in `<project>/.kettle/issues/`. This skill covers
|
||||
everything you do **with** an issue: writing one, reading one, checking it
|
||||
against the canonical format, ticking its boxes, and walking the dependency
|
||||
graph.
|
||||
|
||||
**Nothing here touches the network.** No tracker, no login, no token. An issue
|
||||
that lives only on this machine is a first-class issue, not a draft waiting to
|
||||
be uploaded. Synchronizing with a tracker is a separate, optional layer —
|
||||
`/kettle:sync`.
|
||||
|
||||
Read [`references/format.md`](references/format.md) before creating or editing
|
||||
an issue. It is the single source of truth for identity, metadata, types,
|
||||
labels, templates, and language rules.
|
||||
|
||||
**No `kettle` on PATH?** `command not found: kettle` is the whole story — the
|
||||
Python scripts this plugin used to ship are gone and no other CLI is a
|
||||
substitute.
|
||||
Stop and tell the operator to install it: `cd cli && go build -o
|
||||
~/.local/bin/kettle ./cmd/kettle` in the marketplace repository (go.mod requires
|
||||
**go 1.26**), or `go install
|
||||
git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest`.
|
||||
|
||||
## Identity: the slug
|
||||
|
||||
The file name is the id and the id is a slug —
|
||||
`.kettle/issues/wire-sqlc-appclick.md`. It never changes: not when the title
|
||||
changes, not when the issue is pushed somewhere. Tracker numbers live in a
|
||||
metadata field (`gitea: owner/repo#42`), never in a file name and never in
|
||||
`depends:`.
|
||||
|
||||
Consequence worth internalizing: **`#42` means nothing in this layer.** Refer to
|
||||
issues by id.
|
||||
|
||||
```
|
||||
.kettle/issues/INDEX.md table of every issue — read this first
|
||||
.kettle/issues/wire-sqlc-appclick.md metadata block + `# Title` + body
|
||||
.kettle/issues/wire-sqlc.comments.md comment thread (written by /kettle:sync only)
|
||||
.kettle/issues/tree-<id>.md saved graph (kettle tree --write)
|
||||
```
|
||||
|
||||
## Where the store is
|
||||
|
||||
`<project root>/.kettle/issues` — **not** `.kettle/issues` relative to wherever
|
||||
you are standing. The project root is the nearest directory up from where you
|
||||
are that holds a `.kettle/` marker: the binary walks up from
|
||||
`$CLAUDE_PROJECT_DIR`, then from the working directory, and out of a linked
|
||||
worktree to its main checkout. Every command sees one store no matter which
|
||||
subdirectory it runs in, and a `cd` into a *different* project correctly answers
|
||||
with that project's issues.
|
||||
|
||||
**A project has a store because an operator ran `/kettle:init` in it.** The
|
||||
marker is never inferred from the tree — `.git` is in every clone. **With no
|
||||
marker anywhere, every command stops and names the directories it searched.** It
|
||||
does not fall back to a plausible directory. If you see that, either you are not
|
||||
in the project you think you are, or nobody has initialized it: tell the operator
|
||||
to run `/kettle:init`. It is theirs to run, and it carries the worktree and
|
||||
migration-clash rules a bare `kettle init` does not.
|
||||
|
||||
`--out` overrides all of it and is taken **literally**: an absolute path as
|
||||
given, a relative one relative to the working directory. `kettle config` prints
|
||||
every path this directory resolved to and is the fastest way to explain a run
|
||||
that went somewhere unexpected.
|
||||
|
||||
Two things follow, both deliberate: a store that is not there reports `does not
|
||||
exist` while a store with nothing in it reports `is empty` — different problems —
|
||||
and nothing conjures a store as a side effect of a write.
|
||||
|
||||
## Reading: grep, don't parse
|
||||
|
||||
Metadata is one field per line with inline lists precisely so plain `grep`
|
||||
works. `INDEX.md` first, then the files:
|
||||
|
||||
```bash
|
||||
grep -l 'labels:.*type/bug' .kettle/issues/*.md # all bugs
|
||||
grep -l 'origin: local' .kettle/issues/*.md # never pushed anywhere
|
||||
grep -ln 'depends:.*migrate-schema' .kettle/issues/*.md # who depends on it
|
||||
grep -A3 '## Acceptance criteria' .kettle/issues/wire-*.md
|
||||
grep -c '^- \[ \]' .kettle/issues/wire-sqlc-appclick.md # open checkboxes
|
||||
```
|
||||
|
||||
Read whole files only for the issues the task actually needs.
|
||||
|
||||
## Creating an issue
|
||||
|
||||
1. **Read the format**: [`references/format.md`](references/format.md).
|
||||
2. **Pick the type** — `bug`, `task`, `refactor`, `test`, `feature` (a container
|
||||
for several issues with one business value), or `draft` (an idea not ready
|
||||
for work). If it is not obvious from the request, ask the user; one question.
|
||||
3. **Scaffold it** with `kettle new` — English imperative title, no type prefix,
|
||||
`--depends` takes ids.
|
||||
4. **Fill the sections** with Edit — every section of the template present and
|
||||
in order, **headers English, prose Russian**. `## Spec` gets a repo path, a
|
||||
URL, or the literal `none`; ask the user if you cannot determine which.
|
||||
5. **Check it** with `kettle check <id>`.
|
||||
|
||||
One file = one issue. Several related issues = several files, linked through
|
||||
`depends:`.
|
||||
|
||||
The issue is real and complete the moment the file exists. `origin: local` is a
|
||||
finished state, not a draft — and while it says local, **that file is the only
|
||||
copy of the work.** Publishing it to Gitea is a separate decision
|
||||
(`/kettle:sync`) and it ends that state: a push hands the issue over and deletes
|
||||
the file.
|
||||
|
||||
## Editing an issue
|
||||
|
||||
Edit the file. Change `state:` to close it, edit `labels:`, add ids to
|
||||
`depends:`. Re-run `kettle check` afterwards, and `kettle index` to refresh the
|
||||
table. Checkboxes are the exception — use `kettle ac`.
|
||||
|
||||
If the issue is synced (`origin:` names a tracker), the file is a working copy:
|
||||
your edit is local until `kettle push --update`, and that push **deletes the
|
||||
file** once the tracker has it. Closing one of those is `kettle close` — it moves
|
||||
the state on both sides in one run, where editing `state:` here alone would only
|
||||
ever tell this machine. Get the file back with `kettle pull <n>`; the slug does
|
||||
not change.
|
||||
|
||||
## Ticking checkboxes
|
||||
|
||||
A checkbox is the one part of a body that is **state** and not prose, so it has
|
||||
a command of its own. Never rewrite a body to tick a box: the rewrite re-flows
|
||||
lines and re-words sentences, and the issue's diff swells around a change that
|
||||
means one character. `kettle ac <id>` lists them numbered with their state,
|
||||
`--check` / `--uncheck` take a number or a substring.
|
||||
|
||||
- **Every checkbox in the body counts, not just `## Acceptance criteria`.** A
|
||||
`type/feature` keeps its children as checkboxes under `## Issues` and they are
|
||||
in the same numbering.
|
||||
- **A substring must match exactly one item.** Two matches is an error listing
|
||||
both; pick by number. It never guesses.
|
||||
- **Exactly one character of the file changes.** Wording, wrapping and trailing
|
||||
whitespace come back byte for byte, so both `git diff` and the tracker's diff
|
||||
show the tick and nothing else.
|
||||
- Examples inside a ``` fence are markup, not state — they are skipped.
|
||||
- Whether a criterion is actually *met* is a judgement about content. Tick what
|
||||
the caller named, never what looks done.
|
||||
|
||||
Getting the tick to the tracker is a separate step — `kettle push --update`.
|
||||
|
||||
## Writing a proper description
|
||||
|
||||
Issues get filed on the run — "comments aren't pulled", "the guard broke". That
|
||||
is a request, not a statement of work: no reproduction steps, no
|
||||
`path/file:line`, acceptance criteria nobody can check. Rewriting one into the
|
||||
canonical format is a procedure, not improvisation.
|
||||
|
||||
1. **Read the issue whole**, and everything it points at — the ids in
|
||||
`depends:`, the `## Spec` target, the files it names.
|
||||
2. **Determine the type and its template.** The `type/*` label selects one of
|
||||
the templates in [`references/format.md`](references/format.md), and that
|
||||
template's section list is the shape you are aiming at. If the label is
|
||||
missing or wrong, decide it now and fix `labels:`; promoting a `type/draft`
|
||||
to a concrete type is this same step.
|
||||
3. **Locate the anchor points in the code.** Grep the repo for every file,
|
||||
symbol, command and error string the issue mentions, until you can name
|
||||
lines. Work that does not exist yet still has anchor points — the files the
|
||||
change will land in, and the ones that will call it.
|
||||
4. **Gather the missing context.** What has to be there when you are done:
|
||||
- code references in the `path/file.ext:line` form, for every place the
|
||||
change lands;
|
||||
- reproduction steps — exact commands and their real output (`type/bug`
|
||||
splits them across `## Steps to reproduce` / `## Expected` / `## Actual`);
|
||||
- acceptance criteria that are objectively checkable: a command that exits 0,
|
||||
a file that exists, a section that is present — not aspirations;
|
||||
- a real value for `## Spec` — a repo path, a URL, or the literal `none`.
|
||||
|
||||
**A missing fact is either found in the repository or becomes a question to
|
||||
the user. Inventing one is forbidden.** Ask in one batch, and keep `none` in
|
||||
`## Spec` as the legitimate answer it is — never a plausible-looking link.
|
||||
5. **Rewrite the sections** with Edit: every section of the template, in the
|
||||
template's order, English headers and Russian prose. Replace the body; do not
|
||||
append a second telling of the same issue below the old one.
|
||||
6. **Check it** with `kettle check <id>`. Errors mean malformed, warnings mean
|
||||
the type's template is not fully filled in. Re-run `kettle index` if the
|
||||
labels changed.
|
||||
|
||||
The procedure is identical for a local issue and a synced one — it works on
|
||||
`.kettle/issues/<id>.md` and this layer does not know the difference. Getting the
|
||||
rewritten body into the tracker is `kettle push --update` and is no part of this.
|
||||
|
||||
## Evicting closed issues
|
||||
|
||||
The store is a working set, not an archive. A closed issue is not a unit of work
|
||||
any more, and `kettle evict` takes it out — no `rm`, no rebuilding `INDEX.md` by
|
||||
hand. Two conditions, both read off the file, and the second is the whole safety
|
||||
argument:
|
||||
|
||||
| `state:` | `origin:` | what eviction does |
|
||||
|---|---|---|
|
||||
| `closed` | a tracker | removes `<id>.md` and every sidecar under that slug |
|
||||
| `closed` | `local` | **keeps it, always**, and says why |
|
||||
| `open` | anything | keeps it |
|
||||
|
||||
**`origin: local` is never evicted, in any state, not even when you name it on
|
||||
the command line.** That file *is* the issue; there is no copy to fetch back.
|
||||
Only a file whose own metadata says the work lives somewhere else may go — the
|
||||
same trade a push makes when it drops a file the tracker just confirmed.
|
||||
|
||||
`.remote.json` is deliberately **not** pruned: it is the number → slug ledger and
|
||||
its entries are supposed to outlive the files they name, which is what makes a
|
||||
later `kettle pull <n>` land on the same slug. And eviction is **not a one-off
|
||||
migration** — a pull by number fetches an issue in any state, so a closed issue
|
||||
pulled after an eviction lands on disk again. Evict it again when you are done.
|
||||
|
||||
This command decides from `state:` in the file, which is only as fresh as the
|
||||
last pull. To have the tracker's answer instead — an issue closed in the web UI
|
||||
five minutes ago — use `kettle sync-evict` from `/kettle:sync`, which refreshes
|
||||
`state:` first and then makes exactly this decision.
|
||||
|
||||
## Dependency graph
|
||||
|
||||
`depends:` is the authoritative edge list; the body's `## Depends on` section is
|
||||
prose for humans, and `kettle check` warns when they disagree. `kettle tree`
|
||||
draws downwards — what an issue depends on. The other direction is a grep, not a
|
||||
flag:
|
||||
|
||||
```bash
|
||||
grep -ln 'depends:.*migrate-schema' .kettle/issues/*.md
|
||||
```
|
||||
|
||||
A `type/feature` plus its children read as one document: draw the tree once for
|
||||
the shape, then grep the files.
|
||||
|
||||
## Layering rule
|
||||
|
||||
Everything below is offline. No command in this skill opens a socket, reads a
|
||||
token, or knows what an issue number is — that is `/kettle:sync`, and the domain
|
||||
would not notice if the tracker did not exist. If you find yourself wanting a
|
||||
tracker concept here — a number, a login, an HTTP call, a label colour — it
|
||||
belongs on the other side of that line.
|
||||
|
||||
The commands themselves follow. Their usage lines, flags, defaults and examples
|
||||
are generated from the binary's own command registry, so they cannot disagree
|
||||
with the binary; `kettle help <command>` prints the same text. Editing them here
|
||||
changes nothing.
|
||||
|
||||
<!-- kettle:gen -->
|
||||
**Generated from the kettle command registry by `kettle gen scaffold`.** Everything between the two markers is replaced on the next run — the prose around it is embedded in the binary and replaced with it.
|
||||
|
||||
## `kettle ac <id>`
|
||||
|
||||
list and tick an issue's checkboxes
|
||||
|
||||
A checkbox is the one part of a body that is *state* and not prose. Everything
|
||||
else is written once; boxes get ticked as the work goes, and the only other ways
|
||||
to tick one are a human with an editor or a model rewriting the whole body — the
|
||||
second worse than the first, because the rewrite re-flows the text and the
|
||||
issue's diff swells around a change of one character. This changes that one
|
||||
character and nothing else.
|
||||
|
||||
Named after `## Acceptance criteria`, where most boxes live, but every checkbox in
|
||||
the body is listed and tickable: a type/feature keeps its children under
|
||||
`## Issues`, and binding this to one heading would silently lose half of them.
|
||||
|
||||
A substring picks an item only when it picks exactly one. Two matches is an
|
||||
error listing both — a coin flip would tick the wrong box and look like it
|
||||
worked.
|
||||
|
||||
Delivering the changed body to a tracker is not part of this; that is
|
||||
`kettle push --update`.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--check` | — | tick one item: number or substring |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--uncheck` | — | untick one item: number or substring |
|
||||
|
||||
```bash
|
||||
kettle ac wire-sqlc-appclick # numbered list with state
|
||||
kettle ac wire-sqlc-appclick --check 3 # tick by number
|
||||
kettle ac wire-sqlc-appclick --check регресс # tick by substring
|
||||
kettle ac wire-sqlc-appclick --uncheck 3 # untick it again
|
||||
```
|
||||
|
||||
## `kettle check [<id>…]`
|
||||
|
||||
validate issues against the canonical format
|
||||
|
||||
The same check the sync layer runs before it pushes anything, available on its
|
||||
own so a local-only issue can be held to the format without a tracker being
|
||||
involved.
|
||||
|
||||
Errors mean malformed; warnings mean it deviates from its type's template or its
|
||||
graph looks suspect. An unticked checkbox is neither: work not done yet is the
|
||||
normal state of a perfectly well-formed issue.
|
||||
|
||||
Exit status is 1 when anything has errors, which is what makes this usable in a
|
||||
hook or a CI step.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--quiet` | `false` | exit status only, print nothing |
|
||||
| `--strict` | `false` | treat warnings as errors |
|
||||
|
||||
```bash
|
||||
kettle check # every issue in the store
|
||||
kettle check wire-sqlc-appclick # one issue
|
||||
kettle check --quiet # exit status only
|
||||
kettle check --strict # treat warnings as errors
|
||||
```
|
||||
|
||||
## `kettle evict [<id>…]`
|
||||
|
||||
remove closed issues from the local store
|
||||
|
||||
The store is a working set, not an archive. What is evicted is two conditions,
|
||||
both read off the file:
|
||||
|
||||
state: closed the work is done
|
||||
origin: <tracker> the work is somewhere else too
|
||||
|
||||
THE SECOND CONDITION IS THE WHOLE SAFETY ARGUMENT. `origin: local` means this
|
||||
file IS the issue — there is no other copy and deleting it deletes the work. It
|
||||
is never evicted, in any state, not even when named explicitly on the command
|
||||
line: a closed local issue is reported and kept.
|
||||
|
||||
Eviction asks the file rather than the tracker, because state and origin are
|
||||
domain fields and the answer is already in the store — which is why this needs
|
||||
no network and no login. `kettle sync-evict` is the variant that refreshes state
|
||||
from the tracker first and then makes the same decision.
|
||||
|
||||
Not a one-off migration: a pull by number fetches an issue in any state, so a
|
||||
closed issue pulled after an eviction lands on disk again. Evict it again when
|
||||
you are done with it.
|
||||
|
||||
INDEX.md is rebuilt, because it IS a view of the directory. The number -> slug
|
||||
ledger is deliberately not pruned: its entries outlive the files they name, and
|
||||
that is what makes a pull land on the same slug afterwards.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--dry-run` | `false` | print what would be removed; touch nothing |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
|
||||
```bash
|
||||
kettle evict # every closed issue that is not origin: local
|
||||
kettle evict old-thing another-thing # only these
|
||||
kettle evict --dry-run # print what would go; touch nothing
|
||||
```
|
||||
|
||||
## `kettle index`
|
||||
|
||||
rebuild INDEX.md from what is on disk
|
||||
|
||||
A map of the local store, nothing else. The `origin` column is the only place
|
||||
the index acknowledges that a tracker exists: `local` means the issue has never
|
||||
left this machine, anything else names the tracker it also lives in. Both are
|
||||
ordinary issues here.
|
||||
|
||||
`progress` counts the body's checkboxes, ticked over total, and is read off the
|
||||
body at build time rather than stored — a second copy of that state in a
|
||||
metadata field would be wrong by the next edit.
|
||||
|
||||
An existing store with nothing in it is a legitimate thing to index and gets an
|
||||
"_empty_" table. A store that is not there is an error, not a directory to
|
||||
create.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
|
||||
```bash
|
||||
kettle index # rebuild the index for this project
|
||||
```
|
||||
|
||||
## `kettle new`
|
||||
|
||||
create a local issue from its type template
|
||||
|
||||
The issue is real the moment this writes the file. Nothing is pending, nothing
|
||||
is a draft awaiting a tracker: `origin: local` is a complete state and pushing it
|
||||
later is optional.
|
||||
|
||||
While it says local, this file is the ONLY copy of the work — the store, not a
|
||||
cache of anything. That is what a push changes: it hands the issue to the
|
||||
tracker and removes the file.
|
||||
|
||||
Writes .kettle/issues/<slug>.md prefilled with the type's template, prints the
|
||||
path, and rebuilds INDEX.md. Fill the sections in an editor, then run
|
||||
`kettle check <id>`.
|
||||
|
||||
Body prose is Russian, section headers and the title are English.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--assignee` | — | assignee login; repeat |
|
||||
| `--depends` | — | id this issue depends on; repeat |
|
||||
| `--id` | — | slug (default: derived from the title) |
|
||||
| `--label` | — | extra label, e.g. tech/sql; repeat |
|
||||
| `--milestone` | — | milestone title |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--severity` | — | severity/* label, one of: low, medium, high, showstopper, critical |
|
||||
| `--title` | — | English, imperative, no type prefix |
|
||||
| `--type` | — | issue type, one of: bug, task, refactor, test, feature, draft (becomes the exclusive type/* label) |
|
||||
|
||||
```bash
|
||||
kettle new --type task --title "Wire sqlc into the appclick repo layer" --label tech/sql --label comp/appclick # a task with two free-form labels
|
||||
kettle new --type bug --title "Fix the index rebuild on an empty store" --depends wire-sqlc-appclick --milestone v0.2 # a bug that is blocked by another issue
|
||||
```
|
||||
|
||||
## `kettle tree [<id>…]`
|
||||
|
||||
draw the dependency graph of the local store
|
||||
|
||||
Edges come from the `depends:` metadata, which is the authoritative edge list;
|
||||
prose in the body is never walked. Because the graph is slugs all the way down,
|
||||
this works identically for issues that were never pushed anywhere.
|
||||
|
||||
Downwards is what this draws — what an issue depends on. The other direction is
|
||||
a grep, not a flag:
|
||||
|
||||
grep -ln 'depends:.*migrate-schema' .kettle/issues/*.md
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--depth` | `6` | maximum depth |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--write` | `false` | also write <store>/tree-<slug>.md |
|
||||
|
||||
```bash
|
||||
kettle tree # every root (nothing depends on it)
|
||||
kettle tree wire-sqlc-appclick # one subtree
|
||||
kettle tree --depth 2 --write # shallow, and saved beside the issues
|
||||
```
|
||||
<!-- /kettle:gen -->
|
||||
@@ -0,0 +1,372 @@
|
||||
# Issue format
|
||||
|
||||
Canonical format for every issue in this project, whether it ever reaches a
|
||||
tracker or not. Designed to be unambiguous for both humans and LLMs: fixed
|
||||
English section headers in a fixed order, verifiable acceptance criteria, one
|
||||
issue = one deliverable.
|
||||
|
||||
Nothing here depends on Gitea. How these files are mapped onto a tracker is the
|
||||
sync layer's business — see `/kettle:sync`.
|
||||
|
||||
## Identity
|
||||
|
||||
An issue is one file, `.kettle/issues/<id>.md`, and `id` is a slug: lowercase
|
||||
ASCII, digits, single dashes, derived from the title. **The slug is the
|
||||
identity.** It is stable for the life of the issue — a retitled issue keeps its
|
||||
slug; an issue pushed to a tracker, deleted locally and fetched back a month
|
||||
later keeps it too. Tracker numbers are a foreign key stored in a field, never
|
||||
the name of anything.
|
||||
|
||||
```
|
||||
.kettle/issues/wire-sqlc-appclick.md
|
||||
```
|
||||
|
||||
A slug never contains a dot, which is how the store tells an issue from the
|
||||
files parked beside it (`<id>.comments.md`).
|
||||
|
||||
Stability is a promise the format makes, so something has to keep it once the
|
||||
file is gone. That is the sync layer's problem and its answer is a marker in the
|
||||
body — see `/kettle:sync`; the domain neither writes nor reads it, and it never
|
||||
appears in the file on disk.
|
||||
|
||||
## Metadata block
|
||||
|
||||
One field per line, lists inline, so plain `grep` works without a parser:
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: wire-sqlc-appclick
|
||||
state: open
|
||||
labels: [type/task, tech/sql]
|
||||
assignees: [naudachu]
|
||||
milestone: v0.2
|
||||
depends: [migrate-schema]
|
||||
origin: gitea
|
||||
branch: feat/wire-sqlc
|
||||
gitea: claude-skills/marketplace#42
|
||||
remote-updated: 2026-08-09T18:24:01Z
|
||||
synced: 2026-08-09T18:40:00Z
|
||||
url: https://git.noodles.cam/claude-skills/marketplace/issues/42
|
||||
---
|
||||
# Wire sqlc into the appclick repo layer
|
||||
|
||||
## Summary
|
||||
…
|
||||
```
|
||||
|
||||
| Field | Owner | Meaning |
|
||||
|---|---|---|
|
||||
| `id` | domain | slug; equals the file name |
|
||||
| `state` | domain | `open` or `closed` |
|
||||
| `labels` | domain | see namespaces below; exactly one `type/*` |
|
||||
| `assignees` | domain | logins; may be empty |
|
||||
| `milestone` | domain | title, or `none` |
|
||||
| `depends` | domain | ids this issue depends on — **the authoritative graph** |
|
||||
| `origin` | domain | `local`, or the name of a tracker this also lives in |
|
||||
| `gitea` | sync | the handle in that tracker: `owner/repo#N` |
|
||||
| `branch` | sync | the tracker's branch link (Gitea `ref`); push fills an empty one with the current git branch, and never overwrites a filled one |
|
||||
| `url`, `synced`, `remote-updated`, `comments` | sync | bookkeeping |
|
||||
|
||||
Domain fields render first, in the order above; sync fields follow, sorted.
|
||||
|
||||
`origin` is domain-owned on purpose: *whether* a piece of work exists anywhere
|
||||
but here is a fact about the work. *Where* that is, and how to reach it, is the
|
||||
sync layer's business — the domain carries `gitea:` and the rest through
|
||||
load/save verbatim and never reads them. That passthrough is why one file can
|
||||
represent a local issue and a synced one without a second format.
|
||||
|
||||
`origin: local` is a **complete state, not a pending one.** An issue that never
|
||||
leaves this machine is valid and finished work; pushing it is optional and
|
||||
nothing here treats it as a draft.
|
||||
|
||||
It is not a *permanent* state, and it is what the file's fate depends on:
|
||||
|
||||
| `origin:` | what the file is | what a push does to it | what eviction does to it |
|
||||
|---|---|---|---|
|
||||
| `local` | the issue itself — the only copy there is | creates it in the tracker, then deletes the file | **nothing, ever** — in any state, named or not |
|
||||
| a tracker | a working copy of something the tracker already has | updates the tracker, then deletes the file | removes it once `state: closed` |
|
||||
|
||||
**A successful push deletes `.kettle/issues/<id>.md`** (and `<id>.comments.md`), on
|
||||
create and on `--update` alike. What is in the store is what has not left this
|
||||
machine; everything else is fetched again when it is needed. The rule, its
|
||||
safety conditions, and how the slug survives are `/kettle:sync`'s to state.
|
||||
|
||||
**A closed issue is evicted from the store** by `kettle evict` — same trade,
|
||||
one condition more: the work is done *and* it exists somewhere else. An
|
||||
`origin: local` issue is never evicted, because there is nowhere to fetch it
|
||||
back from. The store is a working set, not an archive; `kettle pull <n>` fetches a
|
||||
closed issue again whenever it is wanted.
|
||||
|
||||
The `id` never changes across that round trip, which is why `depends:` in other
|
||||
issues keeps working. That is the format's promise; the mechanism is not.
|
||||
|
||||
## Language rules
|
||||
|
||||
- **Issue title**: English, imperative mood, no type prefix — the type lives in
|
||||
the label, not the title. Good: `Fix the index rebuild on an empty store`.
|
||||
Bad: `fix: crash`, `[bug] crash`, `Крашится гвард`.
|
||||
- **Section headers**: the exact English literals below, as `##` headings, in
|
||||
the given order. Do not translate, rename, or reorder them.
|
||||
- **Body prose** (text inside sections): Russian.
|
||||
|
||||
## Label namespaces
|
||||
|
||||
Four namespaces classify an issue. Two are exclusive (at most one label from
|
||||
the namespace), two are free-form:
|
||||
|
||||
| Namespace | Exclusive | Purpose |
|
||||
|---|---|---|
|
||||
| `type/*` | yes | What kind of work; primarily its business value. Mandatory, exactly one. |
|
||||
| `severity/*` | yes | Business impact. At most one; apply when the impact is known. |
|
||||
| `tech/*` | no | Technology the issue is bound to. Any number. |
|
||||
| `comp/*` | no | System component of this repo. Any number; no preset — project-specific. |
|
||||
|
||||
### `type/*` — mandatory, exactly one
|
||||
|
||||
| Label | Meaning |
|
||||
|---|---|
|
||||
| `type/bug` | Something behaves incorrectly in existing code |
|
||||
| `type/task` | Implementation of new functionality |
|
||||
| `type/refactor` | Internal restructuring: file moves, architecture; behavior must not change |
|
||||
| `type/test` | Writing or fixing tests |
|
||||
| `type/feature` | Container: several issues delivering one unit of business value |
|
||||
| `type/draft` | Idea captured for later; not ready for work |
|
||||
|
||||
### `severity/*` — at most one
|
||||
|
||||
`severity/low`, `severity/medium`, `severity/high`, `severity/showstopper`,
|
||||
`severity/critical`.
|
||||
|
||||
### `tech/*` — any number
|
||||
|
||||
Technology-bound labels, e.g. `tech/sql` (pgx, sqlc, sql-migrate — persistent
|
||||
storage), `tech/obs` (grafana, loki, prometheus, alloy — observability),
|
||||
`tech/postgres`.
|
||||
|
||||
### `comp/*` — any number
|
||||
|
||||
Components of this repo's system, e.g. `comp/appclick`. No preset list —
|
||||
derive from the project.
|
||||
|
||||
> Label **colors** are not part of the format: a hex code is how a tracker
|
||||
> paints a chip, not what an issue is. They live in the binary's mapping layer
|
||||
> (`cli/internal/mapping`) and are applied on push.
|
||||
|
||||
## Dependencies
|
||||
|
||||
`depends:` in the metadata block is the graph, and it holds **ids**:
|
||||
|
||||
```markdown
|
||||
depends: [migrate-schema, add-pool-cfg]
|
||||
```
|
||||
|
||||
An optional `## Depends on` section, placed right after `## Spec`, carries the
|
||||
human explanation — one reference per line, with a reason where it helps:
|
||||
|
||||
```markdown
|
||||
## Depends on
|
||||
- migrate-schema — нужна схема БД из этого issue
|
||||
- add-pool-cfg
|
||||
```
|
||||
|
||||
The section is prose and is passed to and from a tracker unchanged; only
|
||||
`depends:` is walked when the graph is computed. Keeping them consistent is on
|
||||
you — `kettle check` warns when the section names an id that `depends:` does
|
||||
not list. Omit the section when there are no dependencies; never write an empty
|
||||
one.
|
||||
|
||||
A `type/feature` container writes the same relation under `## Issues` instead
|
||||
(see the template below). Same direction, same rule: every id named there also
|
||||
belongs in that issue's `depends:`. The warning names whichever of the two
|
||||
sections the reference actually came from.
|
||||
|
||||
Draw the graph with `kettle tree`. The reverse direction is a grep:
|
||||
|
||||
```bash
|
||||
grep -ln 'depends:.*migrate-schema' .kettle/issues/*.md
|
||||
```
|
||||
|
||||
## Shared rules
|
||||
|
||||
- `## Summary` is always the first section; `## Acceptance criteria` is always
|
||||
present (exception: `type/draft`). These two are the anchors every reader
|
||||
(human or LLM) relies on.
|
||||
- `## Spec` is **mandatory in every type**. Its value is a repo path
|
||||
(`docs/specs/auth.md`), a URL, or the literal `none` when no spec exists.
|
||||
Never omit the section and never invent a link — `none` is an explicit,
|
||||
valid answer.
|
||||
- Acceptance criteria are `- [ ]` checkboxes; each item is an objectively
|
||||
checkable condition, not an aspiration.
|
||||
- A checkbox is **item markup, not a property of one section**: `- [ ]`
|
||||
unticked, `- [x]` ticked, and it means the same under `## Issues` as under
|
||||
`## Acceptance criteria`. An item that wraps continues on an indented line
|
||||
and is still one item. A `- [ ]` inside a ``` code fence is an example of the
|
||||
markup, not state. Tick them with `kettle ac`, which reads the whole body
|
||||
on exactly these rules and rewrites one character; progress (`3/7`) is
|
||||
counted off the body and is never a metadata field.
|
||||
- Code references use the `path/file.ext:line` form; related issues by id.
|
||||
- Screenshots are allowed but their content must be duplicated as text — an
|
||||
LLM reading these files cannot see images.
|
||||
- If acceptance criteria grow past ~5 unrelated items, split the issue (or
|
||||
promote it to a `type/feature` container with child issues).
|
||||
|
||||
## Template: `type/bug`
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Что сломано и где проявляется, одно-два предложения.
|
||||
|
||||
## Spec
|
||||
`docs/specs/auth.md`, URL — или `none`.
|
||||
|
||||
## Steps to reproduce
|
||||
1. …
|
||||
2. …
|
||||
|
||||
## Expected
|
||||
Что должно было произойти.
|
||||
|
||||
## Actual
|
||||
Что происходит на самом деле: вывод команды, лог.
|
||||
|
||||
## Environment
|
||||
Только релевантное: версии, ОС, конфигурация.
|
||||
|
||||
## Acceptance criteria
|
||||
- [ ] баг не воспроизводится по шагам выше
|
||||
- [ ] добавлена проверка на регрессию (если применимо)
|
||||
```
|
||||
|
||||
## Template: `type/task`
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Что нужно сделать, одно-два предложения.
|
||||
|
||||
## Spec
|
||||
Ссылка или `none`.
|
||||
|
||||
## Motivation
|
||||
Какую проблему пользователя/системы это решает.
|
||||
|
||||
## Acceptance criteria
|
||||
- [ ] проверяемое условие
|
||||
- [ ] …
|
||||
|
||||
## Constraints
|
||||
Что НЕ входит в объём; технические рамки. (опционально)
|
||||
```
|
||||
|
||||
## Template: `type/refactor`
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Что перестраиваем и в каких файлах (`path/file:line`).
|
||||
|
||||
## Spec
|
||||
Ссылка или `none`.
|
||||
|
||||
## Motivation
|
||||
Чем плохо текущее состояние: дублирование, связность, читаемость.
|
||||
|
||||
## Invariants
|
||||
Что НЕ должно измениться: поведение, публичные API, форматы данных.
|
||||
|
||||
## Acceptance criteria
|
||||
- [ ] проверяемое условие (тесты зелёные, старый путь удалён, …)
|
||||
```
|
||||
|
||||
## Template: `type/test`
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Что покрываем тестами и где (`path/file:line`).
|
||||
|
||||
## Spec
|
||||
Ссылка или `none`.
|
||||
|
||||
## Motivation
|
||||
Зачем: регрессия после бага, пробел в покрытии, флаки-тест.
|
||||
|
||||
## Test cases
|
||||
- сценарий → ожидаемый результат
|
||||
- …
|
||||
|
||||
## Acceptance criteria
|
||||
- [ ] перечисленные кейсы покрыты и зелёные
|
||||
- [ ] тесты проходят в CI
|
||||
```
|
||||
|
||||
## Template: `type/feature`
|
||||
|
||||
A container: one unit of business value delivered by several child issues.
|
||||
Child issues carry their own `type/*` (`task`, `bug`, `test`, …) and know
|
||||
nothing about the container.
|
||||
|
||||
**The container depends on its children, never the reverse.** Every child id
|
||||
goes in the container's own `depends:` and, as prose, in its `## Issues`
|
||||
section; a child's `depends:` is for that child's real dependencies and must
|
||||
not point back at the container. Keep implementation detail in the children;
|
||||
the feature body stays at business level.
|
||||
|
||||
That direction is not a convention picked at random. "The container is closed
|
||||
when its children are closed" *is* a dependency relation. "This child belongs
|
||||
to that feature" is a membership relation, and membership has no place in a
|
||||
dependency graph. Pointed the other way the two rules contradict each other:
|
||||
the moment the container listed a child that already depended on it,
|
||||
`kettle check` would report `ERROR cycle`. With the edge going down, the
|
||||
graph reads as nesting — `kettle tree` draws the container as the root with
|
||||
its children beneath it — and the check is green.
|
||||
|
||||
So the container's metadata block carries the children:
|
||||
|
||||
```markdown
|
||||
depends: [wire-sqlc-appclick, add-pool-cfg]
|
||||
```
|
||||
|
||||
and its body repeats them for a human:
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Бизнес-ценность одним-двумя предложениями.
|
||||
|
||||
## Spec
|
||||
Ссылка или `none`.
|
||||
|
||||
## Motivation
|
||||
Какую проблему пользователя/системы это решает.
|
||||
|
||||
## Issues
|
||||
- [ ] wire-sqlc-appclick — краткое описание части
|
||||
- [ ] add-pool-cfg — краткое описание части
|
||||
|
||||
## Acceptance criteria
|
||||
- [ ] все дочерние issues закрыты
|
||||
- [ ] проверяемое условие уровня фичи (например, e2e-сценарий работает)
|
||||
```
|
||||
|
||||
## Template: `type/draft`
|
||||
|
||||
A parking spot for ideas that are not fleshed out yet. Minimal structure, no
|
||||
acceptance criteria required. Before implementation starts, a draft MUST be
|
||||
promoted: relabeled to a concrete type and rewritten into that type's template.
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Идея одним-двумя предложениями.
|
||||
|
||||
## Spec
|
||||
Ссылка или `none` (для драфтов обычно `none`).
|
||||
|
||||
## Notes
|
||||
Свободные заметки: что известно, открытые вопросы, варианты.
|
||||
```
|
||||
|
||||
## Containers beyond `type/feature`
|
||||
|
||||
- **Milestone** — a set of issues with an optional time bound. Locally it is
|
||||
just the `milestone:` field; a tracker-side milestone must already exist for
|
||||
a push to attach the issue to it.
|
||||
- **Project** — a set of issues tracked by status columns (Backlog, ToDo,
|
||||
InProgress, Ready, Done). Not represented in this format and not reachable
|
||||
through the Gitea API — web UI only.
|
||||
@@ -0,0 +1,273 @@
|
||||
---
|
||||
name: kettle-project
|
||||
description: Generated flag reference for the project-level `kettle` commands — `kettle init`, `kettle auth`, `kettle config`, `kettle gen`, `kettle mirror`. Load it to look up the exact flags and defaults of one of those, or when a command answers "no project" / "no login" and you need `kettle config` to say what this directory resolved to. The rules around initializing are /kettle:init and the credential workflow is /kettle:auth; this file is the flag table both of them point at.
|
||||
---
|
||||
|
||||
# kettle project — the project itself
|
||||
|
||||
`kettle` resolves everything from one marker. `<project>/.kettle/` is created by
|
||||
`kettle init` and never inferred: `.git` is in every clone, so a tool that
|
||||
guessed a root from one would write issues into whatever tree it happened to be
|
||||
standing in. With no marker anywhere the command stops and names the directories
|
||||
it searched — that is an answer, not a fallback.
|
||||
|
||||
Two configuration files, and the split is the point. `<project>/.kettle/config.yaml`
|
||||
holds the tracker repository and the **name** of a login; the name is worth
|
||||
nothing on its own, which is what makes it safe inside a working tree.
|
||||
`~/.config/kettle/logins.yaml` (0600, one per machine, `$KETTLE_CONFIG_HOME` or
|
||||
`$XDG_CONFIG_HOME` move it) holds the tokens. `KETTLE_LOGIN`, `KETTLE_REPO`,
|
||||
`KETTLE_URL` and `KETTLE_TOKEN` each override the file they shadow.
|
||||
|
||||
**No `kettle` on PATH?** `command not found: kettle` is the whole story — no
|
||||
script and no other CLI substitutes for it, and it means the binary that wrote
|
||||
this file has since moved or been removed, because nothing else could have put it
|
||||
here. Stop and tell the operator to reinstall it:
|
||||
`go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest`, or
|
||||
`cd cli && make install` in a checkout of that repository (go.mod requires
|
||||
**go 1.26**).
|
||||
|
||||
**This file is written by the binary and is replaced whole on the next
|
||||
`kettle gen scaffold`.** Every word of it — the prose as much as the flag table
|
||||
below — is embedded in the `kettle` that wrote it, which is why the two cannot
|
||||
disagree about a flag. Editing it here changes nothing durable; the fix for a
|
||||
wrong sentence is a newer `kettle`, and the fix for a stale one is
|
||||
`kettle gen scaffold`. `kettle config` says which version wrote this tree.
|
||||
|
||||
<!-- kettle:gen -->
|
||||
**Generated from the kettle command registry by `kettle gen scaffold`.** Everything between the two markers is replaced on the next run — the prose around it is embedded in the binary and replaced with it.
|
||||
|
||||
## `kettle auth list | add | remove <name>`
|
||||
|
||||
manage the tokens this machine holds
|
||||
|
||||
Credentials live in one file per machine, outside every working tree, mode
|
||||
0600. A project pins a login by NAME; the name is worth nothing on its own,
|
||||
which is what makes it safe to keep in a file inside the repository.
|
||||
|
||||
The token is read from standard input unless --token is given, because an
|
||||
argument is in the shell history the moment it is typed:
|
||||
|
||||
kettle auth add --name noodles --url https://git.example.com < token.txt
|
||||
pass show gitea/token | kettle auth add --name noodles --url https://git.example.com
|
||||
|
||||
`list` never prints a token. There is no flag to make it.
|
||||
|
||||
--scopes RECORDS WHAT THE TOKEN WAS MINTED WITH, and records is all it does:
|
||||
nothing is checked against it and nothing is refused because of it. It is worth
|
||||
writing down because the instance will not answer the question — Gitea's own
|
||||
token listing needs a password, not a token, so a token cannot be asked what it
|
||||
may do. Gitea spells them <read|write>:<category>; issues need `write:issue`,
|
||||
and everything `kettle api` reaches outside issues — releases, pull requests,
|
||||
branches, tags, actions — is `repository`. A token minted for issues alone
|
||||
answers 403 there, and the 403 names no scope.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--name` | — | login name (add) |
|
||||
| `--scopes` | — | what the token was minted with, comma separated, e.g. write:issue,write:repository; documentation only (add) |
|
||||
| `--token` | — | token, if you would rather not use stdin (add) |
|
||||
| `--url` | — | instance URL, e.g. https://git.example.com (add) |
|
||||
| `--user` | — | account this token belongs to; documentation only (add) |
|
||||
|
||||
```bash
|
||||
kettle auth list # what this machine holds
|
||||
pass show gitea | kettle auth add --name noodles --url https://git.example.com # add one, token on stdin
|
||||
kettle auth add --name noodles --url https://git.example.com --scopes write:issue,write:repository < t.txt # and write down what it can do
|
||||
kettle auth remove noodles # forget it
|
||||
```
|
||||
|
||||
## `kettle config`
|
||||
|
||||
show what this project resolved to
|
||||
|
||||
Every path and every setting, with the overrides already applied, so a run that
|
||||
went somewhere unexpected can be explained without guessing.
|
||||
|
||||
The token is never printed — only whether one was found.
|
||||
|
||||
This is the command to reach for when the store looks empty, when a push says
|
||||
401, or when two directories disagree about which project they are in.
|
||||
|
||||
```bash
|
||||
kettle config # resolved paths and settings
|
||||
```
|
||||
|
||||
## `kettle gen scaffold`
|
||||
|
||||
write this project's .claude/ commands, skills and subagent
|
||||
|
||||
A skill tells an agent how to invoke this binary, and a command is how an
|
||||
operator invokes one by hand. Both are written from here, whole, because both
|
||||
travel INSIDE the binary: the prose is embedded next to the code it describes
|
||||
and the flag tables are rendered from the command registry the binary is built
|
||||
from, so neither can be a version behind the other.
|
||||
|
||||
That is the whole reason these documents are not a plugin any more. A plugin
|
||||
ships on its own cadence, and nothing on an operator's machine ever checked that
|
||||
the one they installed described the binary they installed — so a renamed flag
|
||||
could still arrive with documentation recommending the old one, which is exactly
|
||||
the failure the generated block was invented to prevent, one hop further
|
||||
downstream.
|
||||
|
||||
EVERY FILE IS WRITTEN WHOLE, and that is a deliberate reversal. The old
|
||||
generator owned a region and left every byte outside it alone, because the prose
|
||||
around the block was somebody's hand-written file. It is not any more: it is
|
||||
embedded, so there is no hand-written half left to protect, and preserving local
|
||||
edits would mean freezing a project's documentation at whatever version first
|
||||
initialized it. The markers stay in the output so a reader can see which half
|
||||
came from the registry.
|
||||
|
||||
WHAT THIS MEANS FOR A LOCAL EDIT: it does not survive. Run --check before an
|
||||
upgrade if you have made one; the fix for a sentence that is wrong is a newer
|
||||
kettle, not a patch that the next run silently discards.
|
||||
|
||||
The output is deterministic to the byte — no timestamps, no map iteration — so
|
||||
regenerating something that has not changed produces no diff. --check is that
|
||||
property made useful: it writes nothing and exits 1 when any file on disk
|
||||
differs from what would be written, which is what a pre-commit hook or a CI step
|
||||
calls. It wins over --dry-run when both are given.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--check` | `false` | write nothing, exit 1 if anything is out of date |
|
||||
| `--dry-run` | `false` | print what would change; write nothing |
|
||||
| `--out` | — | directory to write into (default: <project>/.claude) |
|
||||
|
||||
```bash
|
||||
kettle gen scaffold # write .claude/ under this project
|
||||
kettle gen scaffold --out ~/code/x/.claude # write it somewhere else
|
||||
kettle gen scaffold --dry-run # print what would change; write nothing
|
||||
kettle gen scaffold --check # exit 1 if the documents are out of date
|
||||
```
|
||||
|
||||
## `kettle init`
|
||||
|
||||
make this directory a project that tracks issues
|
||||
|
||||
Creates `.kettle/` — the marker every other command resolves the store from,
|
||||
and `.kettle/config.yaml`, which says which tracker repository these issues
|
||||
belong to and which login to reach it under — and writes `.claude/`: the slash
|
||||
commands an operator invokes, the skills a model loads, and the runner subagent.
|
||||
|
||||
The marker is deliberately something an operator makes, not something inferred
|
||||
from the tree: `.git` is in every clone, so anything that inferred a root from
|
||||
one would write issues into whatever it happened to be installed in.
|
||||
|
||||
--login pins a name, never a credential. The tokens live in one file per
|
||||
machine, outside every working tree, managed with `kettle auth`.
|
||||
|
||||
All of it is idempotent: it creates .kettle/issues and .kettle/payload, migrates
|
||||
an older store in if it finds one (either layout the tea plugin used, oldest
|
||||
first), writes the config without disturbing settings it was not given, writes
|
||||
the .claude/ tree, and adds .kettle/ to .gitignore. Each migration is a move,
|
||||
not a copy — two stores is the state the marker exists to prevent — and it
|
||||
refuses to pick a winner when both sides hold a file of the same name.
|
||||
|
||||
IT REFUSES TO RUN IN A LINKED WORKTREE, and names the main checkout instead. A
|
||||
worktree is the same project on another branch and reaches the store by a hop
|
||||
out to the main checkout; a marker here would give one project two stores, and
|
||||
the directory holding the second one disappears with the branch.
|
||||
|
||||
--interactive walks a person through the whole thing — the login, the token with
|
||||
the echo turned off, the repository, the .claude/ tree and the AGENTS.md mirror
|
||||
hook. IT REQUIRES A TERMINAL and refuses a standard input that is not one, which
|
||||
is deliberate: every question it asks has a flag beside it, so nothing that is
|
||||
not a person ever needs to answer a prompt.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--at` | — | directory to initialize (default: the working directory) |
|
||||
| `--dry-run` | `false` | report what would happen; change nothing |
|
||||
| `--force-settings` | `false` | let the hook be merged into an existing settings.json, reformatting it |
|
||||
| `--interactive` | `false` | ask, one question at a time; requires a terminal |
|
||||
| `--login` | — | name of a login in the machine-wide file (see `kettle auth`) |
|
||||
| `--mirror-hook` | `false` | register `kettle mirror --hook` on PreToolUse(Bash) |
|
||||
| `--no-scaffold` | `false` | do not write the .claude/ commands, skills and subagent |
|
||||
| `--repo` | — | tracker repository, as owner/name |
|
||||
| `--scaffold-out` | — | where the .claude/ tree goes (default: <project>/.claude) |
|
||||
|
||||
```bash
|
||||
kettle init # initialize the current directory
|
||||
kettle init --interactive # be walked through it, at a terminal
|
||||
kettle init --login noodles --repo claude-skills/marketplace # and point it at a tracker
|
||||
kettle init --mirror-hook # register the AGENTS.md mirror on PreToolUse(Bash)
|
||||
kettle init --at ~/code/x # initialize somewhere else
|
||||
kettle init --dry-run # say what it would do, touch nothing
|
||||
```
|
||||
|
||||
## `kettle mirror [<dir>]`
|
||||
|
||||
keep CLAUDE.md a symlink to AGENTS.md in every directory below here
|
||||
|
||||
Two agent harnesses read two different filenames for the same document. A
|
||||
repository that keeps both as real files keeps TWO DOCUMENTS, and they drift —
|
||||
silently, until somebody reads the stale one and believes it. This walks a tree
|
||||
and leaves one arrangement behind everywhere:
|
||||
|
||||
AGENTS.md is the real file; CLAUDE.md is a symlink pointing at it.
|
||||
|
||||
The link is relative, so a tree that is moved, copied or cloned keeps working.
|
||||
AGENTS.md is the real one because the convention is not one vendor's: a
|
||||
repository that names its documents after a single tool has picked a side it did
|
||||
not need to pick.
|
||||
|
||||
NOTHING HERE DELETES CONTENT. Six of the seven states it can find are repaired
|
||||
losslessly — a missing link is created, a reversed layout is swapped round, a
|
||||
duplicate whose bytes match its original is replaced by the link. The seventh,
|
||||
two real files whose contents DIFFER, is reported and left exactly as it was:
|
||||
one of them is somebody's writing and no rule here knows which.
|
||||
|
||||
It walks the directory given, or the working directory. node_modules, vendor,
|
||||
venv, __pycache__ and every dot-directory are skipped, because somebody else's
|
||||
tree is somebody else's business.
|
||||
|
||||
--hook is the PreToolUse form: it reads the hook payload on standard input,
|
||||
writes any report back as additionalContext, and ALWAYS EXITS 0 — including when
|
||||
it fails. A tool that broke somebody's Bash call because its documentation
|
||||
helper crashed would be worse than no tool. --check is the opposite end: it
|
||||
writes nothing and exits 1 when the tree is not canonical, which is what a
|
||||
pre-commit hook or a make target calls.
|
||||
|
||||
`kettle init --interactive` offers to register the --hook form in
|
||||
.claude/settings.json. It is offered rather than assumed: this is one
|
||||
repository's documentation convention, and a project that does not keep AGENTS.md
|
||||
files wants nothing to do with it.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--check` | `false` | write nothing, exit 1 if the tree is not canonical |
|
||||
| `--hook` | `false` | PreToolUse form: payload on stdin, report as additionalContext, always exit 0 |
|
||||
| `--quiet` | `false` | repair without printing what was repaired |
|
||||
|
||||
```bash
|
||||
kettle mirror # repair the working directory and everything below it
|
||||
kettle mirror ~/code/x # repair somewhere else
|
||||
kettle mirror --check # exit 1 if anything is out of place; write nothing
|
||||
kettle mirror --hook # the PreToolUse form; reads a payload, always exits 0
|
||||
```
|
||||
|
||||
## `kettle version`
|
||||
|
||||
print the version this binary was built as
|
||||
|
||||
A binary that cannot say what it is, is a support problem: an operator with an
|
||||
old copy on PATH and a skill written against a newer one has no way to see the
|
||||
mismatch, and neither does anybody reading their transcript.
|
||||
|
||||
The version is stamped at link time. A build from source says "dev" and means
|
||||
it — that is not a placeholder to be edited, it is the answer for a binary that
|
||||
came out of somebody's working tree rather than off a tag.
|
||||
|
||||
The commit is reported when the build recorded one, which `go build` does from
|
||||
git and a build from an unpacked tarball cannot. A tree with uncommitted
|
||||
changes in it says so beside the commit.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--short` | `false` | print the version alone, with nothing around it |
|
||||
|
||||
```bash
|
||||
kettle version # the version, the toolchain and the commit
|
||||
kettle version --short # just the version, for a script
|
||||
```
|
||||
<!-- /kettle:gen -->
|
||||
@@ -0,0 +1,570 @@
|
||||
---
|
||||
name: kettle-sync
|
||||
description: Move issues between this project's local store and its Gitea tracker with the `kettle` binary — pull issues into `.kettle/issues/`, push local ones up (which deletes the local file), list what the tracker holds, post comments, close and reopen, and evict what the tracker says is closed. Load when the user asks to fetch or publish an issue, see what exists in the tracker, comment on one, or close one. Writing, grepping, validating and graphing an issue's content is /kettle:issue and needs no network.
|
||||
---
|
||||
|
||||
# /kettle:sync — the bridge between the local store and the tracker
|
||||
|
||||
One job: carry issues between `<project>/.kettle/issues/<id>.md` and Gitea.
|
||||
Everything about **what an issue is** — format, types, validation, the dependency
|
||||
graph — belongs to `/kettle:issue`, and this layer neither redefines nor
|
||||
second-guesses it. Knowledge flows one way: delete the tracker from the world and
|
||||
the issue domain does not notice.
|
||||
|
||||
**No `kettle` on PATH?** `command not found: kettle` is the whole story — the
|
||||
Python scripts this plugin used to ship are gone and no other CLI is a
|
||||
substitute. Stop and tell the operator to install it: `cd cli && go build -o
|
||||
~/.local/bin/kettle ./cmd/kettle` in the marketplace repository (go.mod requires
|
||||
**go 1.26**), or `go install
|
||||
git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest`.
|
||||
|
||||
## No `--login`, no `--repo`, no guard
|
||||
|
||||
Which login this project runs under and which repository its issues belong to
|
||||
are facts about the project, stated once by `kettle init` and kept in
|
||||
`.kettle/config.yaml`; the token lives in one file per machine that no working
|
||||
tree can see. There is nothing to pass and nothing to police — the old PreToolUse
|
||||
guard hook and its `--login "$GITEA_LOGIN"` placeholder are gone, along with the
|
||||
failure they existed to catch. `kettle labels --repo owner/name` is the
|
||||
single exception, because bootstrapping a repository's label set is the one
|
||||
operation whose target is not this project.
|
||||
|
||||
A cross-repository *address* is still an address: `kettle pull owner/repo#42`
|
||||
re-points the client for that one call and comes back with the same credentials
|
||||
and the same scratchpad. `42`, `#42`, `owner/repo#42` and a full issue URL are
|
||||
four spellings of one key.
|
||||
|
||||
No login, an unknown login name, a 401: report it and stop — `/kettle:auth`.
|
||||
|
||||
## Never read an issue through a raw API dump
|
||||
|
||||
`kettle api repos/{owner}/{repo}/issues/42` will answer, and answering is the
|
||||
problem: the whole payload — avatars, nested user objects, every comment body —
|
||||
lands in your context whether you need it or not. `kettle pull` writes flat
|
||||
markdown and prints a compact line per issue; `kettle remote` lists the tracker
|
||||
without writing anything at all. Use those. `/kettle:api` is for the entities
|
||||
that have no command, and it says the same thing from its side.
|
||||
|
||||
## The round trip is one rule
|
||||
|
||||
**The store holds what has not left this machine.**
|
||||
|
||||
A successful `kettle push` deletes `<id>.md` and every sidecar under that slug —
|
||||
on create and on `--update` alike, one rule with no exception — and prints the
|
||||
number and URL the issue now lives at. Once the tracker has the issue, the
|
||||
tracker *is* the issue.
|
||||
|
||||
The deletion is the last thing that happens, and only after all three of: the
|
||||
call came back 2xx, the answer carries the number that was written, and the
|
||||
number → slug ledger has been written. Network down, a 422, an answer about
|
||||
another issue — the file stays exactly where it is and the run stops.
|
||||
|
||||
**An `origin: local` issue that has never been pushed is never touched by any of
|
||||
this.** That file is the only copy of that work.
|
||||
|
||||
The slug survives the round trip two ways over, which is why the file can be
|
||||
deleted at all:
|
||||
|
||||
| where | survives |
|
||||
|---|---|
|
||||
| `<!-- kettle:id wire-sqlc-appclick -->`, first line of the **tracker-side** body | a rename in the web UI, a lost ledger, a fresh clone, another machine |
|
||||
| `.kettle/issues/.remote.json`, number → slug | the local file being deleted |
|
||||
|
||||
The marker never appears in the local file: one is put at the top on the way up
|
||||
and every one is stripped on the way down. A pull consults the ledger first (it
|
||||
is the one that knows what is on disk *now*), then the marker, then slugifies the
|
||||
title for an issue filed in the web UI that never had a local name — and a marker
|
||||
is taken at its word only when that slug is free, because a name already in use
|
||||
is a collision and not an identity.
|
||||
|
||||
Nothing prunes the ledger — not a push, not an eviction. Its entries are meant to
|
||||
outlive the files they name.
|
||||
|
||||
## Pulling is a fetch, not a merge
|
||||
|
||||
A pull overwrites the body. Unpushed local edits are lost, with exactly one
|
||||
exception: **checkbox state**. A tick is monotone, so for a checkbox line whose
|
||||
text matches on both sides `[x]` wins from either — tick it in the web UI, tick
|
||||
it locally, tick it in both, the tick survives. The price is real and stated:
|
||||
**a box unticked in the web UI comes back on the next pull.** Untick locally, then
|
||||
`kettle push --update`.
|
||||
|
||||
Two spellings, and they are different operations:
|
||||
|
||||
- **by key** — an address. It fetches the issue in **any** state, because a
|
||||
number is not a question about state.
|
||||
- **by filter** (`--milestone`, `--label`, `-q`) — a query. Closed issues are
|
||||
enumerated and left out, and `--limit` bounds what is **stored**, never what is
|
||||
read.
|
||||
|
||||
Do not loop over numbers to fetch a group; pass the filter. And a pull returns
|
||||
the **unit of work**, not one row of it: blockers come down with it recursively
|
||||
to `--depth`, which costs a request per issue and per outside blocker. That is
|
||||
what `--no-deps` buys back. A blocker the filter did not select still lands on
|
||||
disk, deliberately — it is there because a stored issue named it.
|
||||
|
||||
Comments ride along into `<id>.comments.md` with no flag, and cost nothing when
|
||||
the payload says the thread is empty. **They are pull-only in the store**: editing
|
||||
that file changes nothing in the tracker. `kettle comment` is the way, and it
|
||||
refetches the thread after writing so the local copy is not stale by the comment
|
||||
it just made.
|
||||
|
||||
## Closing, and evicting what the tracker says is closed
|
||||
|
||||
`kettle close` sends `{"state": …}` and nothing else — no title, no body, no
|
||||
labels. **Closing is not an edit**; editing is pull → change → `push --update`.
|
||||
Explicit ids only: there is no `--milestone` and no `--label`, because which
|
||||
issues are finished is a judgement about content and this command only carries
|
||||
one out. The local file is rewritten only after the tracker confirms that very
|
||||
write. A tracker that refuses to close an issue its own dependency graph still
|
||||
blocks says so in its own words — close the blockers first, or unlink them.
|
||||
|
||||
`kettle sync-evict` is `kettle evict` with one thing in front of it: a `state:`
|
||||
that is not stale. Every candidate is asked about **before anything is removed**,
|
||||
and one bad answer evicts nothing at all — not even the issues whose answers had
|
||||
already arrived. `origin: local` is never asked about and never evicted; a
|
||||
tracked issue whose handle is unreadable is reported and kept.
|
||||
|
||||
## Labels
|
||||
|
||||
Push creates the labels its issues happen to use, which means a repository grows
|
||||
the set in pieces and nobody can filter by `type/bug` in the web UI until
|
||||
somebody pushes a bug. `kettle labels` lays the canonical `type/*` and
|
||||
`severity/*` set down in one run instead. An exact name is left alone; a
|
||||
**lookalike** (`bug`, `Bug`, `kind/bug`, `type: bug`) is reported with its id and
|
||||
never touched, because renaming somebody else's label is a decision and not a
|
||||
step; colour or `exclusive` drift is corrected only under `--fix`. `tech/*` and
|
||||
`comp/*` stay open-ended and push-created. A milestone must already exist — push
|
||||
attaches, it never creates.
|
||||
|
||||
## What crosses the boundary, and what does not
|
||||
|
||||
| domain | tracker | note |
|
||||
|---|---|---|
|
||||
| `id` (slug) | `<!-- kettle:id … -->` | first line of the tracker-side body; stripped out of the local copy |
|
||||
| title, body | `title`, `body` | verbatim, both ways, except the marker and the checkbox union |
|
||||
| `state` | `state` | same vocabulary |
|
||||
| `labels` | `labels[]` | names both ways |
|
||||
| `assignees` | `assignees[]` | logins |
|
||||
| `milestone` | `milestone.title` | resolved to an id on write |
|
||||
| `depends` | native issue links | slugs here, `{index, owner, repo}` there; push writes them, a pull reads them back |
|
||||
| — | `ref` | lands in `branch:`; push fills an empty one with the current git branch |
|
||||
| — | `number`, `html_url` | land in `gitea:` / `url:` |
|
||||
|
||||
`depends:` is always slugs, and the body's `## Depends on` prose is passed
|
||||
through **unchanged** in both directions — a translator that edits prose churns
|
||||
the body on every round trip. The edge the tracker acts on is the native link,
|
||||
not the text, which is exactly why the text can be left alone. Push only ever
|
||||
**adds** links: a dependency deleted from `depends:` leaves its tracker link
|
||||
standing, and unlinking is a web UI job.
|
||||
|
||||
Dependencies go up in topological order so a blocker has its number before the
|
||||
issue that names it. One that is still local-only gets no link and is reported,
|
||||
never silently dropped.
|
||||
|
||||
## Drift
|
||||
|
||||
There is none tracked, and there is very little left to track: a published issue
|
||||
has **one** copy — the tracker's — except while somebody is working on it, and
|
||||
that window closes at the next push. Nothing watches the tracker, nothing
|
||||
reconciles, nothing warns that a synced issue changed upstream. `synced:` says how
|
||||
old your working copy is, `remote-updated:` what the server said at that moment.
|
||||
The old question — "I edited this locally, does the server have it, whose text is
|
||||
newer?" — is answered by the store's contents rather than by a mechanism: **a file
|
||||
that is here has not been pushed.**
|
||||
|
||||
The checkbox union is not an exception. It reads only the two bodies in front of
|
||||
it; there is no base version and no way for it to report that anything diverged.
|
||||
|
||||
## Payloads
|
||||
|
||||
Every request body goes to `<project>/.kettle/payload/` first and is kept there
|
||||
for a retry or a post-mortem. It is a **sibling** of the store and never a child:
|
||||
request bodies are debris of the transport, and a scratchpad inside a store makes
|
||||
`ls .kettle/issues` lie about what exists. Nothing in it is anybody's only copy —
|
||||
deleting it costs nothing. A run that sends nothing leaves no directory behind.
|
||||
|
||||
For Gitea entities `kettle` has no command for — releases, webhooks, actions,
|
||||
pull requests — `kettle api` sends the request under this same login, into this
|
||||
same scratchpad. `/kettle:api`.
|
||||
|
||||
The commands themselves follow. Their usage lines, flags, defaults and examples
|
||||
are generated from the binary's own command registry, so they cannot disagree
|
||||
with the binary; `kettle help <command>` prints the same text. Editing them here
|
||||
changes nothing.
|
||||
|
||||
<!-- kettle:gen -->
|
||||
**Generated from the kettle command registry by `kettle gen scaffold`.** Everything between the two markers is replaced on the next run — the prose around it is embedded in the binary and replaced with it.
|
||||
|
||||
## `kettle close <id|number> [<id|number>…]`
|
||||
|
||||
close or reopen issues in the tracker, and on disk with them
|
||||
|
||||
STATE ONLY. This sends `{"state": …}` and nothing else: no title, no body, no
|
||||
labels, no milestone. Editing an issue is `kettle pull` -> edit ->
|
||||
`kettle push --update`; closing it is not an edit.
|
||||
|
||||
EXPLICIT IDS ONLY. No --milestone, no --label, no "close everything that looks
|
||||
done". Which issues are finished is a judgement about content; this carries that
|
||||
judgement out, one named id at a time. Nothing here deletes an issue either —
|
||||
the tracker can, and it is not an operation of this workflow.
|
||||
|
||||
WHAT MAY BE NAMED: a local slug, or a tracker key (42, #42, owner/repo#42, an
|
||||
issue URL). Both, and for the same reason: a push deletes the local file, so
|
||||
most issues in the tracker have no slug on disk to name them by. A slug is
|
||||
resolved through the file's `gitea:` handle when the file is there, and through
|
||||
the ledger (`.remote.json`) when push has already dropped it. A bare number is
|
||||
this project's repository; a qualified key names its own, so a foreign #42 can
|
||||
never be closed against the repository that happens to be configured here.
|
||||
|
||||
An `origin: local` issue cannot be closed. It is not in the tracker, so there is
|
||||
no state there to change, and the run stops naming the id rather than quietly
|
||||
editing one field of a local file. Push it first, or delete it.
|
||||
|
||||
THE LOCAL FILE IS WRITTEN ONLY AFTER THE TRACKER CONFIRMS: the answer has to be
|
||||
the very issue that was patched, in the state that was asked for. Anything else
|
||||
and the file is left exactly as it was. An issue whose local copy is gone
|
||||
(pushed and dropped) is closed in the tracker and nothing is written; the state
|
||||
comes down with the next pull.
|
||||
|
||||
A tracker that refuses to close an issue its own dependency graph still blocks
|
||||
says so in the answer, and the run stops with its words: close the blockers
|
||||
first, or unlink them.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--dry-run` | `false` | print what would change; makes no request |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--reopen` | `false` | set the state back to open instead of closed |
|
||||
|
||||
```bash
|
||||
kettle close wire-sqlc-appclick # one issue, by slug
|
||||
kettle close wire-sqlc-appclick 42 #43 # several, by slug or number
|
||||
kettle close --reopen 42 # the same thing backwards
|
||||
kettle close --dry-run 42 43 # what would change; no request at all
|
||||
```
|
||||
|
||||
## `kettle comment <id>`
|
||||
|
||||
post or edit a comment on a synced issue
|
||||
|
||||
The target is a LOCAL ID, not a number. Which issue this is, is a fact about the
|
||||
work; where it lives in the tracker is bookkeeping, and the `gitea:` handle on the
|
||||
file is what turns one into the other. An `origin: local` issue cannot be
|
||||
commented on at all — it is not in the tracker, so there is nothing there to
|
||||
comment on; push it first.
|
||||
|
||||
The body comes from a file or from --body, and multi-line prose is what --file
|
||||
is for. This is why comments go through the API rather than through a tracker
|
||||
CLI: an entity command with an empty-looking positional opens $EDITOR, and on a
|
||||
TTY that does not exist it hangs forever.
|
||||
|
||||
After the write the whole thread is refetched into `<id>.comments.md`, so the
|
||||
local copy is not stale by one comment — the one this run just made.
|
||||
|
||||
COMMENTS ARE PULL-ONLY IN THE STORE. Nothing round-trips them back: editing
|
||||
`<id>.comments.md` by hand changes nothing in the tracker. Use --edit with a
|
||||
comment id for that.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--body` | — | comment body inline (short, single-line) |
|
||||
| `--edit` | `0` | comment id to rewrite, instead of posting a new one |
|
||||
| `--file` | — | markdown file holding the comment body |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
|
||||
```bash
|
||||
kettle comment wire-sqlc-appclick --file notes.md # post the contents of a file
|
||||
kettle comment wire-sqlc-appclick --body "готово, задеплоено" # post one line
|
||||
kettle comment wire-sqlc-appclick --file fix.md --edit 1234 # rewrite comment 1234 instead
|
||||
```
|
||||
|
||||
## `kettle labels`
|
||||
|
||||
put the canonical type/* and severity/* labels into a repository
|
||||
|
||||
Every `type/*` and every `severity/*` the domain taxonomy defines, created up
|
||||
front instead of trickling in as a side effect of whichever push first happens
|
||||
to use one. Until a name exists in the repository nobody can filter by it in the
|
||||
web UI, so somebody makes their own — foreign colour, no `exclusive` — and the
|
||||
set arrives in pieces over months.
|
||||
|
||||
NO LABEL NAME IS SPELLED OUT HERE. The names come from the domain taxonomy and
|
||||
are painted by the mapping layer, because a hex code is how a tracker paints a
|
||||
chip and not what an issue is. Add a type over in the domain and the next run
|
||||
creates it.
|
||||
|
||||
THE REPOSITORY'S OWN LABELS ARE READ BEFORE ANYTHING IS WRITTEN, and read from
|
||||
the repository, never from a cache — a cache answers "what did we create last
|
||||
time" and the question here is "what does this repository have right now". A
|
||||
name that matches exactly is left alone; a colour or `exclusive` that disagrees
|
||||
with the spec is reported, and corrected only under --fix. A name that merely
|
||||
RESEMBLES a canonical one (the same tail, up to case, separator and whatever
|
||||
namespace is in front: `x`, `X`, `kind/x`, `type: x` against `type/x`) is
|
||||
reported with its id and never touched — renaming somebody else's label is a
|
||||
decision, not a step.
|
||||
|
||||
Out of scope by design: `tech/*` and `comp/*`, which are open-ended and are
|
||||
created by push as they come up, and deleting or renaming anything at all. Only
|
||||
repository labels are read; an organization's own labels sit behind a different
|
||||
endpoint and are neither read nor written.
|
||||
|
||||
The issue store is out of scope too, and not incidentally: a label belongs to
|
||||
the repository and not to any issue, so this neither reads the store nor creates
|
||||
it. Request bodies go to the transport's own scratchpad, which is a sibling of
|
||||
the store and never a child.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--dry-run` | `false` | print the plan; not one writing request |
|
||||
| `--fix` | `false` | also patch colour/exclusive on labels that already exist |
|
||||
| `--repo` | — | repository to bootstrap, as owner/name (default: this project's) |
|
||||
|
||||
```bash
|
||||
kettle labels --dry-run # print the plan; not one writing request
|
||||
kettle labels # create whatever is missing
|
||||
kettle labels --fix # also patch colour / exclusive drift
|
||||
kettle labels --repo owner/name # bootstrap another repository
|
||||
```
|
||||
|
||||
## `kettle pull [<key>…]`
|
||||
|
||||
fetch issues from the tracker into the local store
|
||||
|
||||
THIS IS HOW A PUSHED ISSUE COMES BACK. `kettle push` deletes the local file the
|
||||
moment the tracker confirms the write, so a pull is not a refresh of a copy you
|
||||
kept — it is how the copy comes to exist at all.
|
||||
|
||||
It lands under the SAME slug it had before, after a rename in the web UI and on
|
||||
a machine that has never seen the issue. Three sources answer "what is this
|
||||
issue called here", in this order:
|
||||
|
||||
.remote.json the number -> slug ledger; the only one that knows what
|
||||
is on disk right now, so it wins
|
||||
<!-- kettle:id … --> the marker in the tracker-side body; it survives a lost
|
||||
ledger, a fresh clone, another machine, and a retitling
|
||||
the title slugified — where an issue filed in the web UI gets its
|
||||
first local name
|
||||
|
||||
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 rather than allowed to
|
||||
overwrite somebody else's issue. The marker itself is stripped out of what lands
|
||||
on disk.
|
||||
|
||||
TWO WAYS TO NAME WHAT TO PULL, and they are not the same operation:
|
||||
|
||||
kettle pull 42 #43 owner/repo#44 by key — an ADDRESS
|
||||
kettle pull --milestone v0.2 by filter — a QUERY
|
||||
|
||||
A key fetches an issue in ANY state, because a number is an address and not a
|
||||
question about state. Only filter mode leaves closed issues out — a closed issue
|
||||
is not a unit of work — and only `--state closed` puts one in the store. An issue
|
||||
already on disk is refreshed either way, so a local copy learns it was closed
|
||||
instead of staying open forever, and the count that stayed out goes to stderr.
|
||||
|
||||
`--limit` IS ON THE WRITE, NOT ON THE SELECTION. It counts the issues this run puts
|
||||
in the store and never the closed ones it enumerated and threw away, so pages
|
||||
keep coming until the budget is full — and stop the moment it is. A filter that
|
||||
matches almost only closed issues ends in a warning and a short answer rather
|
||||
than a walk of the whole tracker.
|
||||
|
||||
A PULL RETURNS THE UNIT OF WORK, NOT ONE ROW OF IT. `depends:` is filled from the
|
||||
tracker's own dependency graph and every blocker comes down with it, recursively,
|
||||
to --depth. What that costs, stated rather than hidden: one request per issue
|
||||
that lands in the store, plus one per blocker the selection did not already
|
||||
carry. `--no-deps` is the way back to one request, and narrows the answer to the
|
||||
one issue you asked for. Dependencies are outside --limit: a blocker is followed
|
||||
because a stored issue named it, not because the filter selected it, so a
|
||||
filtered pull can leave more files behind than its limit — including one from
|
||||
another milestone. The one blocker that does not land is a closed one.
|
||||
|
||||
PULLING OVERWRITES THE BODY: a fetch, not a merge. Local edits you have not
|
||||
pushed are lost, with exactly one exception — checkbox state. A tick is monotone,
|
||||
so a `[x]` on either side wins for any item whose text matches; unticking is not,
|
||||
so untick locally and push. `--cached` skips an issue before any of that.
|
||||
|
||||
Comments ride along: the thread lands beside the issue in <id>.comments.md. It
|
||||
costs no request when the payload says there are none, and a file left over from
|
||||
an earlier pull is deleted — so no file means "no comments", never "not asked
|
||||
for". The thread is pull-only; post with `kettle comment`.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--cached` | `false` | skip issues already on disk instead of refetching |
|
||||
| `--depth` | `3` | how deep to follow blockers |
|
||||
| `--label` | — | filter by label; repeat for AND |
|
||||
| `--limit` | `100` | filter mode: how many issues to STORE, not to enumerate |
|
||||
| `--milestone` | — | pull a whole milestone (id or title) |
|
||||
| `--no-deps` | `false` | do not fill depends: and do not follow blockers |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--q` | — | search text in title and body |
|
||||
| `--query` | — | the long spelling of -q |
|
||||
| `--state` | `open` | filter mode only: open, closed or all |
|
||||
|
||||
```bash
|
||||
kettle pull 42 # the issue and everything blocking it, in any state
|
||||
kettle pull 42 --no-deps # just that one issue — one request
|
||||
kettle pull owner/repo#42 # an issue in another repository
|
||||
kettle pull --milestone v0.2 --limit 20 # 20 open issues from a milestone, blockers included
|
||||
kettle pull --label type/bug --state all # every bug; the closed ones are enumerated, not stored
|
||||
```
|
||||
|
||||
## `kettle push [<id>…]`
|
||||
|
||||
send local issues to the tracker; the local copy goes with them
|
||||
|
||||
A SUCCESSFUL PUSH DELETES THE LOCAL FILE — <id>.md and every sidecar under that
|
||||
slug — and prints the number and the URL the issue now lives at. Once the tracker
|
||||
has the issue, the tracker IS the issue: what is left in the store is what has
|
||||
not left this machine. Get it back with `kettle pull <n>`, which returns it under
|
||||
the same slug, because the slug travelled up in the body as <!-- kettle:id … -->
|
||||
and was recorded in the number -> slug ledger.
|
||||
|
||||
ONE RULE, NO EXCEPTION: --update deletes as well. A PATCH is a push, and an issue
|
||||
that has just been sent is no more local than one that was just created. Two
|
||||
rules would put back exactly the question this removes — "is my copy the fresh
|
||||
one?".
|
||||
|
||||
THE DELETION IS THE LAST THING THAT HAPPENS TO AN ISSUE, 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 PATCHed, and
|
||||
3. the ledger has been written with number -> slug.
|
||||
|
||||
Network down, non-2xx, an answer that does not confirm the write: the file stays
|
||||
and the run stops. Nothing removes a file it has not just watched the tracker
|
||||
accept, and nothing removes a file for an issue it did not send — `origin: local`
|
||||
work that has never been pushed is never touched by any of this. 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 and not
|
||||
after.
|
||||
|
||||
Every issue is validated against the canonical format first, offline and before
|
||||
a socket is opened. --force posts anyway; say why when you use it.
|
||||
|
||||
DEPENDENCIES GO FIRST, in topological order, so a blocker has its number before
|
||||
the issue that names it. Every `depends:` entry that has a number becomes a NATIVE
|
||||
tracker link — the same /dependencies a pull reads back, so the tracker shows the
|
||||
blocking panel and refuses to close a blocked issue first. A link that is already
|
||||
there is skipped, not re-POSTed, which is what makes a repeat push a no-op. A
|
||||
dependency that is still local-only has no number and becomes no link: it is
|
||||
reported, never silently dropped.
|
||||
|
||||
REMOVING a link is out of scope — push only ever adds. A dependency deleted from
|
||||
`depends:` leaves its tracker link standing; unlink it in the web UI.
|
||||
|
||||
The `## Depends on` prose is never touched: slugs stay slugs and are not rewritten
|
||||
to #N, so a pull -> push round trip is byte for byte.
|
||||
|
||||
Labels the repository is missing are created with the canonical colour and, for
|
||||
type/* and severity/*, exclusive: true. `branch:` carries the tracker's `ref`: an
|
||||
empty one is filled with the current git branch and an already-set one is sent as
|
||||
written. Detached HEAD or no repository at all is not an error — no ref is sent
|
||||
and a warning says so.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--dry-run` | `false` | validate and print the plan; no network, nothing deleted |
|
||||
| `--force` | `false` | push despite format violations |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--update` | `false` | PATCH issues that already carry a gitea: field |
|
||||
|
||||
```bash
|
||||
kettle push # every issue the tracker does not have yet, blockers first
|
||||
kettle push wire-sqlc-appclick # one issue
|
||||
kettle push --update wire-sqlc-appclick # PATCH one that is already there — the file still goes
|
||||
kettle push --dry-run # validate and print the plan; no network, nothing deleted
|
||||
```
|
||||
|
||||
## `kettle remote`
|
||||
|
||||
list what exists in the tracker, one line each
|
||||
|
||||
Discovery only: this prints and WRITES NOTHING. The local store is a store, not a
|
||||
search-results folder, and a listing that landed in it would leave files nobody
|
||||
asked for beside the issues somebody did. Pick the numbers here, then pull them.
|
||||
|
||||
#42 open type/task, tech/sql Wire sqlc into the repo layer
|
||||
└─ local: wire-sqlc-appclick
|
||||
|
||||
The second line appears when the number is already in the local ledger, so it is
|
||||
obvious what a pull would refresh and what it would add.
|
||||
|
||||
--limit here caps the LISTING: N lines out, closed ones among them. That is not
|
||||
what the same flag means to `kettle pull`, and the difference is not an oversight —
|
||||
pull bounds what it WRITES, this command writes nothing, and enumeration is the
|
||||
whole job.
|
||||
|
||||
Projects are not filterable: the projects API is not exposed by Gitea. Use
|
||||
milestones or labels, or the web UI.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--label` | — | filter by label; repeat for AND |
|
||||
| `--limit` | `30` | how many lines to print |
|
||||
| `--milestone` | — | milestone id or title |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
| `--q` | — | search text in title and body |
|
||||
| `--query` | — | the long spelling of -q |
|
||||
| `--state` | `open` | open, closed or all |
|
||||
|
||||
```bash
|
||||
kettle remote # the open issues, 30 of them
|
||||
kettle remote --state all --label type/bug --limit 50 # every bug, open and closed
|
||||
kettle remote --milestone v0.2 # what is in a milestone
|
||||
kettle remote -q sqlc # keyword search over title and body
|
||||
```
|
||||
|
||||
## `kettle sync-evict [<id>…]`
|
||||
|
||||
refresh state from the tracker, then evict what is closed
|
||||
|
||||
`kettle evict` is the command that decides and deletes. This adds exactly one
|
||||
thing in front of it: a `state:` that is not stale. A local `state:` is only as
|
||||
fresh as the last pull, so an issue closed in the web UI an hour ago still reads
|
||||
`open` here and the offline command will — correctly — leave it alone. That is
|
||||
the gap this closes, and before it existed the operator had to pull the five
|
||||
closed issues back onto disk before anything could remove them.
|
||||
|
||||
ORDER OF OPERATIONS, AND IT IS THE WHOLE SAFETY ARGUMENT:
|
||||
|
||||
1. every candidate's state is fetched — ALL of them, before anything is
|
||||
removed;
|
||||
2. each answer must be the issue that was asked about, in a state the domain
|
||||
recognizes;
|
||||
3. only then is the eviction run, by handing the refreshed issues to the
|
||||
domain — the same decision, the same deletion, the same protection of
|
||||
`origin: local`, in one place.
|
||||
|
||||
A dead connection, a non-2xx, an answer about another issue, a state nobody
|
||||
recognizes: the run stops at step 2 and NOTHING is deleted, not even the issues
|
||||
whose answers had already arrived. That is stricter than push, which deletes as
|
||||
it goes, and it costs nothing here — there is no ordering constraint between
|
||||
evictions, so there is no reason to start before every answer is in.
|
||||
|
||||
A candidate is an issue carrying a `gitea:` handle. `origin: local` work has
|
||||
none, is never asked about, and is never evicted — it is not in the tracker to
|
||||
be closed. A tracked issue whose handle is missing or unreadable cannot be
|
||||
verified, so it is reported and kept rather than guessed at.
|
||||
|
||||
Cost: one request per candidate. The store is a working set that push keeps
|
||||
small, and a wrong answer here deletes a file, so each issue is asked about by
|
||||
its own address rather than inferred from a list a limit could have truncated.
|
||||
|
||||
The refreshed state is written back even for the issues that stay: the answer is
|
||||
already paid for, and a store that keeps a state the tracker has disowned is the
|
||||
thing this command exists to fix.
|
||||
|
||||
| flag | default | what it does |
|
||||
| --- | --- | --- |
|
||||
| `--dry-run` | `false` | ask the tracker and report; write and delete nothing |
|
||||
| `--out` | — | store root (default: <project>/.kettle/issues) |
|
||||
|
||||
```bash
|
||||
kettle sync-evict # ask about every synced issue; evict the closed ones
|
||||
kettle sync-evict old-thing another-thing # only these
|
||||
kettle sync-evict --dry-run # ask, report, write and delete nothing
|
||||
```
|
||||
<!-- /kettle:gen -->
|
||||
Reference in New Issue
Block a user