@slowcook-ai/cli 0.19.5 → 0.19.6

package/dist/commands.manifest.js

@@ -0,0 +1,289 @@
+/**
+ * `packages/cli/src/commands.manifest.ts`
+ *
+ * Single source of truth for slowcook's user-facing command surface.
+ * Drives BOTH `slowcook help` output AND the auto-generated command
+ * catalog in `packages/cli/README.md`.
+ *
+ * Adding a command: append an entry below. Update both `slowcook help`
+ * AND README sync at the same time via the CI gate in
+ * `.github/workflows/readme-help-sync.yml`.
+ *
+ * Removing a command: don't. Mark `status: "deprecated"` + keep the
+ * entry for one release with a deprecation warning, then remove.
+ * Backward compat is a public commitment.
+ */
+export const COMMANDS = [
+    // --- Pipeline ---
+    {
+        name: "refine",
+        usage: "slowcook refine --issue <number> [--cwd <path>] [--owner <login>] [--repo <name>]",
+        description: "Drive a GitHub issue through a clarifying-question loop until a frozen spec PR is emitted.",
+        group: "pipeline",
+    },
+    {
+        name: "recipe",
+        usage: "slowcook recipe [--spec <id>] [--all] [--cwd <path>]",
+        description: "Generate Vitest tests from merged specs — the test contract brew follows.",
+        group: "pipeline",
+        aliases: ["testgen"],
+    },
+    {
+        name: "vibe",
+        usage: "slowcook vibe --spec <id> [--cwd <path>] [--owner <login>] [--repo <name>] [--dry-run]",
+        description: "Design-first mockup generator. Emits a runnable React mockup PR from spec + brownfield context.",
+        group: "pipeline",
+    },
+    {
+        name: "plate",
+        usage: "slowcook plate --pr <number> [--cwd <path>] [--owner <login>] [--repo <name>] [--review-comment-id <id>]",
+        description: "Mockup amendment agent. Triggered by /plate PR comments on slowcook-mockup PRs; force-pushes amendments.",
+        group: "pipeline",
+    },
+    {
+        name: "brew",
+        usage: "slowcook brew --story <id> [--budget-usd <n>] [--max-iterations <n>] [--model <id>]",
+        description: "Ratcheted implementation loop: iterate src/ until all of one story's tests are green.",
+        group: "pipeline",
+    },
+    {
+        name: "chef",
+        usage: "slowcook chef --pr <number> [--cwd <path>]",
+        description: "PR-CI failure classifier — dispatches retry / escalate based on check status.",
+        group: "pipeline",
+    },
+    {
+        name: "chef-drift",
+        usage: "slowcook chef-drift [--pr <number>] [--story <id>] [--cwd <path>]",
+        description: "Surgical drift-fixer. Triggered by mock-isolation / recon / brew / navigator halts.",
+        group: "pipeline",
+    },
+    {
+        name: "chef-orchestrate",
+        usage: "slowcook chef-orchestrate --pr <number> --story <id> [--cwd <path>]",
+        description: "Pipeline orchestrator. Decides redispatch_brew / rebase / escalate / close on a halted PR.",
+        group: "pipeline",
+    },
+    // --- Plumbing ---
+    {
+        name: "init",
+        usage: "slowcook init [--owner <handle>] [--force] [--dry-run] [--cwd <path>]",
+        description: "Scaffold .brewing/, .github/workflows/slowcook-*, and CODEOWNERS in a consumer project.",
+        group: "plumbing",
+    },
+    {
+        name: "refresh-knowledge",
+        usage: "slowcook refresh-knowledge [--cwd <path>] [--auto-only] [--curated-only]",
+        description: "Rebuild .brewing/repo-knowledge/{auto,curated}/ — code-shape digests + git-history mining.",
+        group: "plumbing",
+    },
+    {
+        name: "upsert-agent-docs",
+        usage: "slowcook upsert-agent-docs [--cwd <path>] [--dry-run]",
+        description: "Write the managed slowcook block in the consumer's AGENTS.md (or create one).",
+        group: "plumbing",
+    },
+    {
+        name: "knowledge",
+        usage: "slowcook knowledge add <topic> \"<entry>\" [--evidence-pr <n>] [--evidence-file <path>]",
+        description: "Add a curated entry to .brewing/repo-knowledge/curated/.",
+        group: "knowledge",
+    },
+    {
+        name: "cost",
+        usage: "slowcook cost log --story <id> --usd <n> --agent <name> [--apply-to-spec]",
+        description: "Stamp a cost marker on a story for non-Actions agents (Claude Code, Cursor, manual runs).",
+        group: "knowledge",
+    },
+    {
+        name: "stories",
+        usage: "slowcook stories status [--cwd <path>] [--owner <login>] [--repo <name>] [--json]",
+        description: "Per-story pipeline-stage table (refine / testgen / vibe / brew / chef) from specs/_index.yaml + GitHub state.",
+        group: "knowledge",
+        status: "alpha",
+    },
+    // --- Checks ---
+    {
+        name: "guard",
+        usage: "slowcook guard --base <ref> --head <ref> [--override] [--config <path>]",
+        description: "Check for frozen-path violations between two git refs. CI step.",
+        group: "checks",
+    },
+    {
+        name: "manifest",
+        usage: "slowcook manifest (record|verify) [--stack-config <path>] [--manifest <path>] [--story <id>]",
+        description: "Record or verify the set of discoverable tests so agents can't silently exclude them.",
+        group: "checks",
+    },
+    {
+        name: "check",
+        usage: "slowcook check (mock-isolation|spec) [file...] [--cwd <path>]",
+        description: "Static structural checks. `check spec` re-runs spec validators on PR amendments; `check mock-isolation` enforces the mock-vs-prod boundary.",
+        group: "checks",
+    },
+    {
+        name: "recon",
+        usage: "slowcook recon [--story <id>] [--cwd <path>] [--reuse-scan] [--stub-scan] [--exclude <glob>]",
+        description: "Pre-brew structural divergence check. Surfaces missing components / testid gaps / brownfield rename hazards.",
+        group: "checks",
+    },
+    {
+        name: "map",
+        usage: "slowcook map (generate|check) [--cwd <path>] [--out <path>] [--md <path>]",
+        description: "Generate / check the repo-wide code map (APIs, pages, components, helpers, types).",
+        group: "checks",
+    },
+    // --- Ops ---
+    {
+        name: "serve",
+        usage: "slowcook serve <profile> (up|sync|down|logs|reset) [--branch <name>] [--scenario <name>] [--service <name>] [--follow] [--prune]",
+        description: "Multi-mode dev / mock / staging on a shared box. `dev` bind-mounts source; `mock` runs vite-dev (auto-skip if no scripts.dev); `staging` is built-image with named-scenario seed reset.",
+        group: "ops",
+        status: "alpha",
+    },
+    {
+        name: "dev-env",
+        usage: "slowcook dev-env (push|switch|up|sync|reset) [--story <id>] [--branch <name>]",
+        description: "Legacy alias for `slowcook serve dev`. Bind-mount source push + per-story preview switch. Kept for backward compat.",
+        group: "ops",
+        status: "deprecated",
+    },
+    {
+        name: "preview",
+        usage: "slowcook preview (deploy|teardown) --pr <number> [--ssh-key <path>] [--cwd <path>]",
+        description: "SSH preview deploy. `deploy --pr N`: build + run the mock app on the consumer's box; post URL to PR.",
+        group: "ops",
+    },
+    {
+        name: "run-mock",
+        usage: "slowcook run-mock <story-id> [--no-poll] [--poll-seconds <n>] [--branch <ref>]",
+        description: "One-command mock launch + auto-pull. Polls origin + git pull --ff-only on plate amendments.",
+        group: "ops",
+    },
+    {
+        name: "dispatch",
+        usage: "slowcook dispatch <step> [inputs...]",
+        description: "Trigger a slowcook GitHub Actions workflow remotely (brew / testgen / refine).",
+        group: "ops",
+    },
+    {
+        name: "port",
+        usage: "slowcook port --story <id> [--cwd <path>] [--dry-run] [--force]",
+        description: "Deterministic mock/ → src/ copy. Pre-brew CI step; applies the useScenarioFixture → useDataDomain rewrite.",
+        group: "ops",
+    },
+    // --- Lifecycle hooks (workflow-driven, not usually invoked by humans) ---
+    {
+        name: "on-spec-merged",
+        usage: "slowcook on-spec-merged --pr <number> [--cwd <path>]",
+        description: "Transition source-issue labels + post audit-trail comment after a spec PR merges.",
+        group: "plumbing",
+    },
+    {
+        name: "on-tests-merged",
+        usage: "slowcook on-tests-merged --pr <number> [--cwd <path>]",
+        description: "Post audit-trail comment after a tests PR merges.",
+        group: "plumbing",
+    },
+    {
+        name: "on-brew-merged",
+        usage: "slowcook on-brew-merged --pr <number> [--cwd <path>]",
+        description: "Post final \"shipped\" audit-trail comment after a brew PR merges. Warns when merge target isn't main.",
+        group: "plumbing",
+    },
+    {
+        name: "on-mockup-approved",
+        usage: "slowcook on-mockup-approved --pr <number> [--cwd <path>]",
+        description: "Hook fired when a mockup PR gets the slowcook-mockup-approved label.",
+        group: "plumbing",
+    },
+    // --- Bug flow ---
+    {
+        name: "investigate",
+        usage: "slowcook investigate --issue <number> [--cwd <path>]",
+        description: "Diagnose a bug from a GitHub issue and emit a bug-profile.",
+        group: "experimental",
+        status: "alpha",
+    },
+    {
+        name: "sift",
+        usage: "slowcook sift --bug-profile <path> [--cwd <path>]",
+        description: "Narrow red→green ratchet for a bug fix; bounded by bug-profile fix_scope.",
+        group: "experimental",
+        status: "alpha",
+    },
+    // --- Misc + experimental ---
+    {
+        name: "extract",
+        usage: "slowcook extract [--schema] [--tokens] [--cwd <path>]",
+        description: "Brownfield extracts (schema.mmd, tokens.md) for refine/investigate context. Fast, no node_modules.",
+        group: "knowledge",
+    },
+    {
+        name: "catchup",
+        usage: "slowcook catchup [--dry-run] [--cwd <path>]",
+        description: "Detect + run pipeline steps that should have triggered but didn't.",
+        group: "plumbing",
+    },
+    {
+        name: "refactor",
+        usage: "slowcook refactor [--scope <name>] [--cwd <path>]",
+        description: "Rank refactor proposals from .brewing/refactor/proposals.json by benefit/cost.",
+        group: "experimental",
+    },
+    {
+        name: "garnish",
+        usage: "slowcook garnish [--cwd <path>]",
+        description: "Local commit-gate for human tweaks on agent work. Runs tests, commits with learning-signal trailers.",
+        group: "experimental",
+    },
+    {
+        name: "budget",
+        usage: "slowcook budget [show|set|rm] [--monthly <usd>] [--start-day <1-31>] [--story <usd>] [--cwd <path>]",
+        description: "Manage the project monthly budget for the fuel gauge.",
+        group: "plumbing",
+    },
+    {
+        name: "brand",
+        usage: "slowcook brand [--brief <prose>] [--refresh] [--dry-run] [--model <id>] [--cwd <path>]",
+        description: "Design-system foundation agent. Emits mock/src/design-system/{tokens.ts, css.ts} from a brand brief.",
+        group: "pipeline",
+    },
+    {
+        name: "fixtures",
+        usage: "slowcook fixtures check [--max-age-days <n>] [--story <id>]",
+        description: "Sanity-check the test-fixture set against the spec.",
+        group: "checks",
+    },
+    {
+        name: "eval",
+        usage: "slowcook eval (--all | --fixture <id> | --list) [--fixtures-dir <path>]",
+        description: "Run the agent eval suite against committed fixtures.",
+        group: "checks",
+    },
+    {
+        name: "docs",
+        usage: "slowcook docs [--cwd <path>]",
+        description: "Docs generation helper.",
+        group: "plumbing",
+    },
+    // --- Hidden built-ins ---
+    { name: "version", usage: "slowcook version", description: "Print the CLI version.", group: "plumbing", hidden: true },
+    { name: "help", usage: "slowcook help [<command>]", description: "Show this help (or per-command usage).", group: "plumbing", hidden: true },
+];
+const NAME_OR_ALIAS_INDEX = (() => {
+    const m = new Map();
+    for (const cmd of COMMANDS) {
+        m.set(cmd.name, cmd);
+        for (const alias of cmd.aliases ?? [])
+            m.set(alias, cmd);
+    }
+    return m;
+})();
+export function findCommand(nameOrAlias) {
+    return NAME_OR_ALIAS_INDEX.get(nameOrAlias);
+}
+export function visibleCommands() {
+    return COMMANDS.filter((c) => !c.hidden);
+}
+//# sourceMappingURL=commands.manifest.js.map

package/dist/commands.manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.manifest.js","sourceRoot":"","sources":["../src/commands.manifest.ts"],"names":[],"mappings":"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"}

package/dist/help.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `packages/cli/src/help.ts` — render the command manifest into the
+ * two surfaces consumers see:
+ *
+ *  1. `slowcook help` — plain-text terminal output (what `cli.ts` emits)
+ *  2. README catalog block — markdown spliced into packages/cli/README.md
+ *
+ * Both come from `COMMANDS` in `./commands.manifest.ts`. Adding a
+ * command in one place updates both surfaces.
+ */
+/**
+ * Plain-text help block for `slowcook help`.
+ *
+ * Format (preserves the existing 0.19 shape — backward compat with any
+ * tool that greps `slowcook help` output):
+ *
+ *   slowcook — TDD-first agentic development harness
+ *
+ *   Usage:
+ *     <usage lines>
+ *
+ *   Commands available in <version>:
+ *     <name>  <description>
+ *
+ *   Docs: https://github.com/aminazar/slowcook
+ */
+export declare function renderHelp(version: string): string;
+/**
+ * Per-command help (shown by `slowcook help <cmd>` or future
+ * standardized `slowcook <cmd> --help` shims). Returns `undefined`
+ * if the name is unknown so the caller can decide on the fallback.
+ */
+export declare function renderCommandHelp(nameOrAlias: string): string | undefined;
+/**
+ * Markdown catalog block spliced into packages/cli/README.md between
+ * `<!-- COMMANDS BLOCK BEGIN -->` and `<!-- COMMANDS BLOCK END -->` by
+ * `scripts/sync-readme-help.sh`.
+ *
+ * Grouped by `CommandGroup`; one bullet per command with name + usage
+ * + description. Hidden commands (version, help) excluded.
+ */
+export declare function renderReadmeBlock(): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0CH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAuBlD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAczE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAgB1C"}

package/dist/help.js

@@ -0,0 +1,131 @@
+/**
+ * `packages/cli/src/help.ts` — render the command manifest into the
+ * two surfaces consumers see:
+ *
+ *  1. `slowcook help` — plain-text terminal output (what `cli.ts` emits)
+ *  2. README catalog block — markdown spliced into packages/cli/README.md
+ *
+ * Both come from `COMMANDS` in `./commands.manifest.ts`. Adding a
+ * command in one place updates both surfaces.
+ */
+import { visibleCommands, findCommand } from "./commands.manifest.js";
+const GROUP_ORDER = [
+    "pipeline",
+    "checks",
+    "plumbing",
+    "knowledge",
+    "ops",
+    "experimental",
+];
+const GROUP_LABELS = {
+    pipeline: "Pipeline (agent-driven)",
+    checks: "Checks + guards",
+    plumbing: "Setup + lifecycle plumbing",
+    knowledge: "Knowledge + accounting",
+    ops: "Ops (preview, dev-env, etc.)",
+    experimental: "Experimental",
+};
+function statusBadge(status) {
+    switch (status) {
+        case "alpha": return " [alpha]";
+        case "experimental": return " [experimental]";
+        case "deprecated": return " [DEPRECATED]";
+        case "stable":
+        case undefined:
+        default: return "";
+    }
+}
+function groupBy(cmds) {
+    const out = {
+        pipeline: [], checks: [], plumbing: [], knowledge: [], ops: [], experimental: [],
+    };
+    for (const c of cmds)
+        out[c.group].push(c);
+    return out;
+}
+/**
+ * Plain-text help block for `slowcook help`.
+ *
+ * Format (preserves the existing 0.19 shape — backward compat with any
+ * tool that greps `slowcook help` output):
+ *
+ *   slowcook — TDD-first agentic development harness
+ *
+ *   Usage:
+ *     <usage lines>
+ *
+ *   Commands available in <version>:
+ *     <name>  <description>
+ *
+ *   Docs: https://github.com/aminazar/slowcook
+ */
+export function renderHelp(version) {
+    const cmds = visibleCommands();
+    const usageLines = cmds.map((c) => `  ${c.usage}`).join("\n");
+    // Description block: align names in a column. Longest visible name width.
+    const nameWidth = Math.max(...cmds.map((c) => c.name.length)) + 2;
+    const descLines = cmds
+        .map((c) => `  ${c.name.padEnd(nameWidth)}${c.description}${statusBadge(c.status)}`)
+        .join("\n");
+    return `
+slowcook — TDD-first agentic development harness
+
+Usage:
+${usageLines}
+
+Commands available in ${version}:
+${descLines}
+
+For per-command details: slowcook help <command>   or   slowcook <command> --help
+
+Docs: https://github.com/aminazar/slowcook
+`;
+}
+/**
+ * Per-command help (shown by `slowcook help <cmd>` or future
+ * standardized `slowcook <cmd> --help` shims). Returns `undefined`
+ * if the name is unknown so the caller can decide on the fallback.
+ */
+export function renderCommandHelp(nameOrAlias) {
+    const cmd = findCommand(nameOrAlias);
+    if (!cmd)
+        return undefined;
+    const aliases = cmd.aliases?.length ? `\nAliases: ${cmd.aliases.join(", ")}` : "";
+    return `
+slowcook ${cmd.name}${statusBadge(cmd.status)}
+
+${cmd.description}
+
+Usage:
+  ${cmd.usage}${aliases}
+
+Group: ${GROUP_LABELS[cmd.group]}
+`;
+}
+/**
+ * Markdown catalog block spliced into packages/cli/README.md between
+ * `<!-- COMMANDS BLOCK BEGIN -->` and `<!-- COMMANDS BLOCK END -->` by
+ * `scripts/sync-readme-help.sh`.
+ *
+ * Grouped by `CommandGroup`; one bullet per command with name + usage
+ * + description. Hidden commands (version, help) excluded.
+ */
+export function renderReadmeBlock() {
+    const grouped = groupBy(visibleCommands());
+    const sections = [];
+    for (const g of GROUP_ORDER) {
+        const entries = grouped[g];
+        if (entries.length === 0)
+            continue;
+        sections.push(`### ${GROUP_LABELS[g]}\n`);
+        for (const c of entries) {
+            sections.push(`- **\`${c.name}\`**${statusBadge(c.status)} — ${c.description}`);
+            sections.push(`  \`\`\``);
+            sections.push(`  ${c.usage}`);
+            sections.push(`  \`\`\``);
+        }
+        sections.push("");
+    }
+    return sections.join("\n");
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slowcook-ai/cli",
-  "version": "0.19.5",
+  "version": "0.19.6",
   "description": "CLI for the slowcook brewing harness",
   "license": "MIT",
   "author": "aminazar",
@@ -43,9 +43,9 @@
     "@slowcook-ai/core": "^0.14.0",
     "@slowcook-ai/stack-ts": "^0.9.9",
     "@slowcook-ai/forge-github": "^0.12.3",
+    "@slowcook-ai/recorder": "^0.9.1",
     "@slowcook-ai/llm-anthropic": "^0.16.3",
-    "@slowcook-ai/review-overlay": "^0.5.5",
-    "@slowcook-ai/recorder": "^0.9.1"
+    "@slowcook-ai/review-overlay": "^0.5.5"
   },
   "devDependencies": {
     "@types/node": "^25.9.1"