@slowcook-ai/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Azar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @slowcook-ai/cli
+
+CLI for the slowcook brewing harness. Installs the `slowcook` binary.
+
+## Install
+
+```bash
+npm i -D @slowcook-ai/cli
+```
+
+## Commands (v0.1)
+
+### `slowcook guard`
+
+Checks for frozen-path violations between two git refs. Intended for CI.
+
+```bash
+npx slowcook guard --base origin/main --head HEAD
+```
+
+**Options:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--base <ref>` | `origin/main` | Base git ref to compare from |
+| `--head <ref>` | `HEAD` | Head git ref to compare to |
+| `--override` | false | Report violations but exit 0 (audit-only) |
+| `--config <path>` | `.brewing/frozen-paths.json` | Config file location |
+
+**Exit codes:**
+
+- `0` — no violations (or `--override` was set and violations existed)
+- `1` — violations detected
+- `2` — script error (missing config, git failure)
+
+**Config file** — a JSON file the consumer project ships, typically at `.brewing/frozen-paths.json`:
+
+```json
+{
+  "directories": ["tests/", "tests-fixtures/"],
+  "files": ["vitest.config.ts", "playwright.config.ts"],
+  "partial": {
+    "package.json": {
+      "frozen_key_paths": ["scripts.test", "scripts.e2e"]
+    }
+  }
+}
+```
+
+- `directories` — prefix match; anything under these paths is frozen.
+- `files` — exact path match.
+- `partial` — for files where only certain JSON keys are frozen (e.g., only `scripts.test*` in `package.json`).
+
+### Use in GitHub Actions
+
+```yaml
+# .github/workflows/frozen-paths-guard.yml
+name: frozen-paths-guard
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - name: Run guard
+        env:
+          HAS_OVERRIDE: ${{ contains(github.event.pull_request.labels.*.name, 'override-freeze') }}
+        run: |
+          ARGS="--base origin/${{ github.base_ref }} --head HEAD"
+          if [ "$HAS_OVERRIDE" = "true" ]; then ARGS="$ARGS --override"; fi
+          npx --yes @slowcook-ai/cli@latest guard $ARGS
+```
+
+The guard emits `::error file=...::` annotations and writes to `$GITHUB_STEP_SUMMARY` when run in GitHub Actions.
+
+## Coming in later versions
+
+See the [monorepo README](../../README.md) for the roadmap.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { guard } from "./commands/guard.js";
+const VERSION = "0.1.0";
+const USAGE = `
+slowcook — TDD-first agentic development harness
+
+Usage:
+  slowcook guard --base <ref> --head <ref> [--override] [--config <path>]
+  slowcook version
+  slowcook help
+
+Commands available in ${VERSION}:
+  guard       Check for frozen-path violations between two git refs.
+
+Coming in later versions:
+  init, manifest, refine, testgen, brew, review, dashboard
+
+Docs: https://github.com/aminazar/slowcook
+`;
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    switch (command) {
+        case "guard":
+            await guard(args.slice(1));
+            return;
+        case "version":
+        case "--version":
+        case "-v":
+            console.log(`slowcook ${VERSION}`);
+            return;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(USAGE);
+            return;
+        default:
+            console.error(`Unknown command: ${command}\n${USAGE}`);
+            process.exit(64); // EX_USAGE
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE5C,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,MAAM,KAAK,GAAG;;;;;;;;wBAQU,OAAO;;;;;;;CAO9B,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,OAAO;YACV,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,OAAO;QACT,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;YACnC,OAAO;QACT,KAAK,SAAS,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI;YACP,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO;QACT;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW;IACjC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/commands/guard.d.ts

@@ -0,0 +1,2 @@
+export declare function guard(argv: string[]): Promise<void>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/commands/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/commands/guard.ts"],"names":[],"mappings":"AAgFA,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsFzD"}

package/dist/commands/guard.js

@@ -0,0 +1,138 @@
+import { readFileSync, appendFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { checkFrozenPaths, } from "@slowcook-ai/core";
+function parseArgs(argv) {
+    const args = {
+        base: "origin/main",
+        head: "HEAD",
+        override: false,
+        config: ".brewing/frozen-paths.json",
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        if (arg === "--base" && next) {
+            args.base = next;
+            i++;
+        }
+        else if (arg === "--head" && next) {
+            args.head = next;
+            i++;
+        }
+        else if (arg === "--override") {
+            args.override = true;
+        }
+        else if (arg === "--config" && next) {
+            args.config = next;
+            i++;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+    }
+    return args;
+}
+function printHelp() {
+    console.log(`
+slowcook guard — enforce frozen paths between two git refs
+
+Usage:
+  slowcook guard [options]
+
+Options:
+  --base <ref>       Base git ref to compare from (default: origin/main)
+  --head <ref>       Head git ref to compare to (default: HEAD)
+  --override         Report violations but exit 0 (use via CI label for audit)
+  --config <path>    Config file path (default: .brewing/frozen-paths.json)
+  --help, -h         Show this help
+
+Exit codes:
+  0 = no violations (or --override and there were violations)
+  1 = violations
+  2 = script error (bad config, git failure)
+`);
+}
+function sh(cmd) {
+    return execSync(cmd, { encoding: "utf8" }).trim();
+}
+function appendGhSummary(md) {
+    const summary = process.env.GITHUB_STEP_SUMMARY;
+    if (!summary)
+        return;
+    try {
+        appendFileSync(summary, md);
+    }
+    catch {
+        // best effort — CI output is the source of truth
+    }
+}
+export async function guard(argv) {
+    const args = parseArgs(argv);
+    // Load config
+    let config;
+    try {
+        config = JSON.parse(readFileSync(args.config, "utf8"));
+    }
+    catch (e) {
+        console.error(`Could not read config at ${args.config}: ${e.message}`);
+        process.exit(2);
+    }
+    // Collect changed files
+    let paths;
+    try {
+        const out = sh(`git diff --name-only ${args.base}...${args.head}`);
+        paths = out ? out.split("\n").filter(Boolean) : [];
+    }
+    catch (e) {
+        console.error(`git diff failed between ${args.base} and ${args.head}: ${e.message}`);
+        process.exit(2);
+    }
+    if (paths.length === 0) {
+        console.log("No changed files.");
+        process.exit(0);
+    }
+    // For partial-freeze files, fetch base/head content
+    const partial = config.partial ?? {};
+    const changed = paths.map((path) => {
+        const out = { path };
+        if (partial[path]) {
+            try {
+                out.baseContent = sh(`git show ${args.base}:${path}`);
+            }
+            catch {
+                // file didn't exist at base — leave undefined
+            }
+            try {
+                out.headContent = readFileSync(path, "utf8");
+            }
+            catch {
+                // file doesn't exist in working tree (deleted)
+            }
+        }
+        return out;
+    });
+    const violations = checkFrozenPaths(changed, config);
+    if (violations.length === 0) {
+        console.log(`No frozen-path violations in ${paths.length} changed file(s).`);
+        appendGhSummary(`### Frozen-path guard\n\n✅ No violations in ${paths.length} changed file(s).\n`);
+        process.exit(0);
+    }
+    const lines = violations.map((v) => `- \`${v.file}\` — ${v.rule}`);
+    console.error(`Frozen-path violations (${violations.length}):`);
+    console.error(lines.join("\n"));
+    const mdHeader = `### Frozen-path guard\n\n`;
+    if (args.override) {
+        appendGhSummary(`${mdHeader}⚠️ ${violations.length} violation(s), but \`--override\` is set — advisory only.\n\n${lines.join("\n")}\n`);
+        console.log("::warning::override flag present — not failing.");
+        process.exit(0);
+    }
+    else {
+        appendGhSummary(`${mdHeader}❌ ${violations.length} violation(s).\n\n${lines.join("\n")}\n`);
+        for (const v of violations) {
+            console.log(`::error file=${v.file}::Frozen-path violation — ${v.rule}`);
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=guard.js.map

package/dist/commands/guard.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@slowcook-ai/cli",
+  "version": "0.1.0",
+  "description": "CLI for the slowcook brewing harness",
+  "license": "MIT",
+  "author": "aminazar",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aminazar/slowcook.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/aminazar/slowcook/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/aminazar/slowcook/issues"
+  },
+  "keywords": [
+    "tdd",
+    "ai",
+    "agents",
+    "testing",
+    "cli",
+    "brewing",
+    "slowcook"
+  ],
+  "type": "module",
+  "bin": {
+    "slowcook": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@slowcook-ai/core": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}