claude-skills/marketplace
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects 1 Releases 2 Wiki Activity

feat: drop the kettle plugin; the binary writes its own skills

Browse Source 
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
2026-08-12 16:17:24 +05:00
parent f18a633185
commit 8b1b11001a
445 changed files with 231172 additions and 1339 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli/internal/cmd/gen_test.go
+118 -114
View File
@@ -1,9 +1,9 @@
package cmd_test
// `kettle gen` writes documentation an agent reads to invoke this binary, into
// files a human also writes prose in. Both halves of that are tested here: what
// it produces has to be the same twice over, and what it does NOT own has to
// come back byte for byte.
// `kettle gen scaffold` writes the documents an operator invokes and a model
// loads. They are embedded in the binary, so this file tests the two properties
// that follow from that: what it produces is the same twice over, and it is the
// binary's answer rather than whatever happens to be on disk.
import (
"os"
@@ -17,39 +17,66 @@ const (
genClose = "<!-- /kettle:gen -->"
)
func TestGenWritesOneFilePerGroupAndIsIdempotent(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "skills")
// everything the tree is made of. Named here rather than derived, because a file
// that silently stopped being written is exactly the failure this catches.
var scaffoldFiles = []string{
"agents/kettle-runner.md",
"commands/kettle/api.md",
"commands/kettle/auth.md",
"commands/kettle/init.md",
"commands/kettle/issue.md",
"commands/kettle/project.md",
"commands/kettle/sync.md",
"skills/kettle-api/SKILL.md",
"skills/kettle-issue/SKILL.md",
"skills/kettle-issue/references/format.md",
"skills/kettle-project/SKILL.md",
"skills/kettle-sync/SKILL.md",
}
first := mustRun(t, dir, "gen", "skills", "--out", out)
for _, group := range []string{"project", "issue", "sync"} {
path := filepath.Join(out, group, "SKILL.md")
raw, err := os.ReadFile(path)
if err != nil {
t.Fatalf("%s was not created: %v\n%s", path, err, first.out())
func TestGenWritesTheWholeTreeAndIsIdempotent(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "out")
first := mustRun(t, dir, "gen", "scaffold", "--out", out)
for _, rel := range scaffoldFiles {
path := filepath.Join(out, filepath.FromSlash(rel))
if _, err := os.Stat(path); err != nil {
t.Fatalf("%s was not created: %v\n%s", rel, err, first.out())
}
body := string(raw)
// The frontmatter is what makes it a skill at all, and the description
// is prose a human tunes — the stub says so and generates nothing.
if !strings.HasPrefix(body, "---\nname: "+group+"\n") {
t.Errorf("%s has no frontmatter naming the group:\n%s", path, firstLines(body, 5))
}
// The four skills that carry a flag table carry the markers around it, so a
// reader can see which half came from the registry.
for _, group := range []string{"project", "issue", "sync", "api"} {
path := filepath.Join(out, "skills", "kettle-"+group, "SKILL.md")
body := readFile(t, path)
if !strings.HasPrefix(body, "---\nname: kettle-"+group+"\n") {
t.Errorf("%s does not name itself after its directory:\n%s", path, firstLines(body, 4))
}
if !strings.Contains(body, genOpen) || !strings.Contains(body, genClose) {
t.Errorf("%s was created without the region markers:\n%s", path, body)
t.Errorf("%s has no region markers", path)
}
// The block has to say what wrote it: the first thing anybody who finds
// it will want to do is edit it in place.
if !strings.Contains(body, "kettle gen skills") {
t.Errorf("%s does not name the command that regenerates it:\n%s", path, body)
if !strings.Contains(body, "kettle gen scaffold") {
t.Errorf("%s does not name the command that regenerates it", path)
}
}
// A command is invoked by a person who typed it, and takes its name from its
// filename — a `name:` here would be a second spelling free to drift.
initBody := readFile(t, filepath.Join(out, "commands", "kettle", "init.md"))
if strings.Contains(firstLines(initBody, 6), "\nname:") {
t.Errorf("the init command carries a name: of its own:\n%s", firstLines(initBody, 6))
}
if !strings.Contains(initBody, "description:") {
t.Errorf("the init command has no description for the command list:\n%s", firstLines(initBody, 6))
}
// One command's documentation, end to end: usage line, short, a flag out of
// the flag set, and a worked example with its explanation beside it.
issues, err := os.ReadFile(filepath.Join(out, "issue", "SKILL.md"))
if err != nil {
t.Fatal(err)
}
issues := readFile(t, filepath.Join(out, "skills", "kettle-issue", "SKILL.md"))
for _, want := range []string{
"## `kettle evict [<id>…]`",
"remove closed issues from the local store",
@@ -57,8 +84,8 @@ func TestGenWritesOneFilePerGroupAndIsIdempotent(t *testing.T) {
"kettle evict --dry-run",
"# print what would go; touch nothing",
} {
if !strings.Contains(string(issues), want) {
t.Errorf("the issue group is missing %q:\n%s", want, issues)
if !strings.Contains(issues, want) {
t.Errorf("the issue skill is missing %q", want)
}
}
@@ -66,7 +93,7 @@ func TestGenWritesOneFilePerGroupAndIsIdempotent(t *testing.T) {
// changed must produce no diff at all, or every run of a CI step is a
// spurious one.
before := readAll(t, out)
second := mustRun(t, dir, "gen", "skills", "--out", out)
second := mustRun(t, dir, "gen", "scaffold", "--out", out)
if strings.Contains(second.stdout, "updated") {
t.Errorf("a second run rewrote a file:\n%s", second.out())
}
@@ -76,105 +103,56 @@ func TestGenWritesOneFilePerGroupAndIsIdempotent(t *testing.T) {
}
}
if r := run(t, dir, "gen", "skills", "--out", out, "--check"); r.code != 0 {
if r := run(t, dir, "gen", "scaffold", "--out", out, "--check"); r.code != 0 {
t.Errorf("--check exited %d on files that were just written:\n%s", r.code, r.out())
}
}
// The generator owns a region, not a file. Everything outside the markers is
// somebody's prose and comes back exactly as it was.
func TestGenLeavesHandWrittenProseAlone(t *testing.T) {
// The reversal, and the one behaviour worth stating out loud: these files are
// the binary's, whole. The old generator owned a region and left the prose
// around it alone, because that prose was somebody's hand-written file. It is
// embedded now — there is no hand-written half left to protect, and preserving
// local edits would freeze a project's documentation at whatever version first
// initialized it.
func TestGenReplacesLocalEditsRatherThanPreservingThem(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "skills")
mustRun(t, dir, "gen", "skills", "--out", out)
out := filepath.Join(dir, "out")
mustRun(t, dir, "gen", "scaffold", "--out", out)
path := filepath.Join(out, "issue", "SKILL.md")
raw := readFile(t, path)
start := strings.Index(raw, genOpen)
end := strings.Index(raw, genClose) + len(genClose)
if start < 0 || end < len(genClose) {
t.Fatalf("no region in the generated file:\n%s", raw)
path := filepath.Join(out, "skills", "kettle-issue", "SKILL.md")
pristine := readFile(t, path)
edited := strings.Replace(pristine, "# /kettle:issue", "# my own heading", 1)
edited = strings.Replace(edited, genClose, "hand-added line\n"+genClose, 1)
if edited == pristine {
t.Fatal("the fixture did not actually edit anything")
}
const above = "\n## Identity: the slug\n\nThe file name is the id, and it never changes.\n\n"
const below = "\n\n## Layering rule\n\nThis skill must keep working with the sync skill deleted.\n"
// A description a human tuned, in the frontmatter the generator must not
// touch: it is the only thing that decides whether the skill loads at all.
edited := strings.Replace(raw[:start], "description: TODO", "description: Work with this project's issues as units of work", 1)
edited += above + raw[start:end] + below
if err := os.WriteFile(path, []byte(edited), 0o644); err != nil {
t.Fatal(err)
}
mustRun(t, dir, "gen", "skills", "--out", out)
after := readFile(t, path)
if after != edited {
t.Errorf("a no-op regeneration did not return the file byte for byte:\n--- want ---\n%s\n--- got ---\n%s", edited, after)
// --check is the warning, and it comes before the loss rather than after.
if r := run(t, dir, "gen", "scaffold", "--out", out, "--check"); r.code != 1 {
t.Errorf("--check exited %d on an edited file, want 1:\n%s", r.code, r.out())
}
// And the prose survives a regeneration that actually rewrites the block.
shortened := strings.Replace(after, genClose, "the block was gutted by hand\n"+genClose, 1)
if err := os.WriteFile(path, []byte(shortened), 0o644); err != nil {
t.Fatal(err)
}
mustRun(t, dir, "gen", "skills", "--out", out)
restored := readFile(t, path)
if restored != edited {
t.Error("regenerating the block did not restore it, or did not preserve the prose around it")
}
if !strings.Contains(restored, "description: Work with this project's issues") {
t.Errorf("the hand-tuned description was overwritten:\n%s", firstLines(restored, 5))
}
if !strings.Contains(restored, above) || !strings.Contains(restored, below) {
t.Errorf("hand-written prose outside the markers was lost:\n%s", restored)
}
}
// Clobbering somebody's prose because they forgot a marker is the failure this
// whole design exists to prevent.
func TestGenNeverOverwritesAFileWithoutMarkers(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "skills")
path := filepath.Join(out, "issue", "SKILL.md")
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatal(err)
}
const prose = "---\nname: issue\ndescription: hand written, every word of it\n---\n\n# Everything here is somebody's work\n"
if err := os.WriteFile(path, []byte(prose), 0o644); err != nil {
t.Fatal(err)
}
r := mustRun(t, dir, "gen", "skills", "--out", out)
if got := readFile(t, path); got != prose {
t.Fatalf("a file with no markers was rewritten:\n%s", got)
}
// Left alone silently is how it drifts unnoticed, so it is reported — and
// on stderr, where a warning belongs.
if !strings.Contains(r.stderr, path) {
t.Errorf("the skipped file was not named on stderr:\n%s", r.out())
}
if !strings.Contains(r.stdout, "without a region") {
t.Errorf("the receipt did not account for it:\n%s", r.stdout)
}
// The other groups still got written — one unmanaged file stops nothing.
if _, err := os.Stat(filepath.Join(out, "sync", "SKILL.md")); err != nil {
t.Error("one file without markers stopped the whole run")
mustRun(t, dir, "gen", "scaffold", "--out", out)
if got := readFile(t, path); got != pristine {
t.Errorf("regenerating did not restore the binary's own copy:\n%s", firstLines(got, 8))
}
}
func TestGenCheckFailsOnAStaleFileAndNamesIt(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "skills")
mustRun(t, dir, "gen", "skills", "--out", out)
out := filepath.Join(dir, "out")
mustRun(t, dir, "gen", "scaffold", "--out", out)
stale := filepath.Join(out, "sync", "SKILL.md")
raw := readFile(t, stale)
edited := strings.Replace(raw, genClose, "kettle push --thoroughly-renamed-flag\n"+genClose, 1)
stale := filepath.Join(out, "skills", "kettle-sync", "SKILL.md")
edited := strings.Replace(readFile(t, stale), genClose, "kettle push --thoroughly-renamed-flag\n"+genClose, 1)
if err := os.WriteFile(stale, []byte(edited), 0o644); err != nil {
t.Fatal(err)
}
r := run(t, dir, "gen", "skills", "--out", out, "--check")
r := run(t, dir, "gen", "scaffold", "--out", out, "--check")
if r.code != 1 {
t.Fatalf("--check exited %d, want 1 — this is what a hook or a CI step calls:\n%s", r.code, r.out())
}
@@ -190,7 +168,7 @@ func TestGenCheckFailsOnAStaleFileAndNamesIt(t *testing.T) {
if err := os.Remove(stale); err != nil {
t.Fatal(err)
}
if r := run(t, dir, "gen", "skills", "--out", out, "--check"); r.code != 1 {
if r := run(t, dir, "gen", "scaffold", "--out", out, "--check"); r.code != 1 {
t.Errorf("--check exited %d for a missing file, want 1:\n%s", r.code, r.out())
}
if _, err := os.Stat(stale); err == nil {
@@ -200,9 +178,9 @@ func TestGenCheckFailsOnAStaleFileAndNamesIt(t *testing.T) {
func TestGenDryRunWritesNothingAtAll(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "skills")
out := filepath.Join(dir, "out")
fresh := mustRun(t, dir, "gen", "skills", "--out", out, "--dry-run")
fresh := mustRun(t, dir, "gen", "scaffold", "--out", out, "--dry-run")
if !strings.Contains(fresh.stdout, "would create") {
t.Errorf("a dry run said nothing about what it would do:\n%s", fresh.out())
}
@@ -211,14 +189,14 @@ func TestGenDryRunWritesNothingAtAll(t *testing.T) {
}
// And on an existing tree: the file is described, never touched.
mustRun(t, dir, "gen", "skills", "--out", out)
path := filepath.Join(out, "issue", "SKILL.md")
mustRun(t, dir, "gen", "scaffold", "--out", out)
path := filepath.Join(out, "skills", "kettle-issue", "SKILL.md")
edited := strings.Replace(readFile(t, path), genClose, "gutted\n"+genClose, 1)
if err := os.WriteFile(path, []byte(edited), 0o644); err != nil {
t.Fatal(err)
}
r := mustRun(t, dir, "gen", "skills", "--out", out, "--dry-run")
r := mustRun(t, dir, "gen", "scaffold", "--out", out, "--dry-run")
if !strings.Contains(r.stdout, "would update") || !strings.Contains(r.stdout, "nothing was written") {
t.Errorf("the dry run did not report the pending change:\n%s", r.out())
}
@@ -227,12 +205,38 @@ func TestGenDryRunWritesNothingAtAll(t *testing.T) {
}
}
func TestGenRefusesAnUnknownTargetAndAMissingOut(t *testing.T) {
// Without --out the tree goes under the project marker, resolved by the same
// walk every other command uses. No marker is an answer, not a fallback: a
// `.claude/` written into a plausible-looking directory is the failure the
// marker exists to replace.
func TestGenWithoutOutResolvesTheProject(t *testing.T) {
dir := newProject(t)
sub := filepath.Join(dir, "cli", "internal")
if err := os.MkdirAll(sub, 0o755); err != nil {
t.Fatal(err)
}
mustRun(t, sub, "gen", "scaffold")
if _, err := os.Stat(filepath.Join(dir, ".claude", "skills", "kettle-issue", "SKILL.md")); err != nil {
t.Errorf("run from %s, the tree did not land at the project root: %v", sub, err)
}
orphan := t.TempDir()
r := run(t, orphan, "gen", "scaffold")
if r.code == 0 {
t.Fatalf("gen outside a project must stop:\n%s", r.out())
}
if !strings.Contains(r.stderr, ".kettle") {
t.Errorf("the refusal does not name what is missing:\n%s", r.out())
}
if _, err := os.Stat(filepath.Join(orphan, ".claude")); err == nil {
t.Error("the refused run created a tree anyway")
}
}
func TestGenRefusesAnUnknownTarget(t *testing.T) {
dir := t.TempDir()
if r := run(t, dir, "gen", "skills"); r.code == 0 || !strings.Contains(r.stderr, "--out") {
t.Errorf("gen without --out must stop and say so:\n%s", r.out())
}
if r := run(t, dir, "gen", "agents", "--out", filepath.Join(dir, "x")); r.code == 0 {
t.Errorf("an unknown target must be refused:\n%s", r.out())
}