great-cto 2.9.2 → 2.9.3

package/dist/leash.js

@@ -0,0 +1,289 @@
+// `great-cto leash <subcommand>` — install, start, status, kill, update.
+//
+// Distribution model: we track llm-leash by *git repository* (not PyPI) so
+// every push to https://github.com/avelikiy/llm-leash main is one
+// `great-cto leash update` away. The repo is cloned to ~/.great_cto/llm-leash
+// and installed as editable (`pip install -e .`). Updates run `git pull` +
+// `pip install -e . --upgrade`.
+//
+// Three sources of truth:
+//   1. Installed SHA   = git rev-parse HEAD in ~/.great_cto/llm-leash
+//   2. Latest SHA      = GitHub commits API
+//   3. Pinned SHA      = .great_cto/leash.json → "pinned_sha" (optional)
+//
+// If pinned_sha is set, update() refuses to bump past it without --force.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log, success, warn, error, cyan, dim, bold } from "./ui.js";
+const REPO_URL = "https://github.com/avelikiy/llm-leash.git";
+const REPO_API = "https://api.github.com/repos/avelikiy/llm-leash";
+const INSTALL_ROOT = join(homedir(), ".great_cto", "llm-leash");
+const CONFIG_PATH = join(homedir(), ".great_cto", "leash.json");
+// ── public API ────────────────────────────────────────────────────────────────
+export async function runLeash(argv) {
+    const sub = argv[0];
+    switch (sub) {
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            return { exitCode: 0 };
+        case "install":
+            return install();
+        case "update":
+            return update(argv.includes("--force"));
+        case "status":
+            return status();
+        case "start":
+            return startProxy(argv.slice(1));
+        case "kill":
+            return killAll();
+        case "uninstall":
+            return uninstall();
+        default:
+            error(`great-cto leash: unknown subcommand '${sub}'`);
+            printHelp();
+            return { exitCode: 2 };
+    }
+}
+// ── subcommands ───────────────────────────────────────────────────────────────
+function printHelp() {
+    log(bold("great-cto leash") + " — runtime governance for LLM agents (https://github.com/avelikiy/llm-leash)");
+    log("");
+    log("  " + cyan("install") + "       clone the repo, install as editable, write default config");
+    log("  " + cyan("update") + "        git pull + reinstall (auto-pulls latest commits from main)");
+    log("  " + cyan("status") + "        installed version vs GitHub latest, last audit-log entry");
+    log("  " + cyan("start") + "         start the HTTP proxy on :8765 (env-var deployment)");
+    log("  " + cyan("kill") + "          fire kill switch — stops all in-flight LLM calls (<300 ms)");
+    log("  " + cyan("uninstall") + "     remove ~/.great_cto/llm-leash (config left intact)");
+    log("");
+    log(dim("  Config: " + CONFIG_PATH));
+    log(dim("  Install dir: " + INSTALL_ROOT));
+}
+function install() {
+    if (!hasGit()) {
+        error("git is required. Install git first: https://git-scm.com/downloads");
+        return { exitCode: 1 };
+    }
+    if (!hasPython()) {
+        error("python3 is required. Install Python 3.10+ first: https://www.python.org/downloads/");
+        return { exitCode: 1 };
+    }
+    mkdirSync(join(homedir(), ".great_cto"), { recursive: true });
+    if (existsSync(INSTALL_ROOT)) {
+        warn(`llm-leash already cloned at ${INSTALL_ROOT}.`);
+        log(`  Run ${cyan("great-cto leash update")} to pull latest.`);
+        return { exitCode: 0 };
+    }
+    log(dim(`  cloning ${REPO_URL} → ${INSTALL_ROOT}`));
+    const cloneResult = spawnSync("git", ["clone", REPO_URL, INSTALL_ROOT], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 120_000,
+    });
+    if (cloneResult.status !== 0) {
+        error(`git clone failed: ${cloneResult.stderr?.toString() || "unknown"}`);
+        return { exitCode: 1 };
+    }
+    log(dim(`  pip install -e .`));
+    const pipResult = spawnSync(pythonCmd(), ["-m", "pip", "install", "-e", INSTALL_ROOT, "--quiet"], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 240_000,
+    });
+    if (pipResult.status !== 0) {
+        warn("pip install reported errors — leash CLI may not be on PATH yet:");
+        warn(pipResult.stderr?.toString() || "");
+        log(`  Try: ${cyan(`${pythonCmd()} -m pip install -e ${INSTALL_ROOT}`)}`);
+    }
+    // Default config (only if absent — never clobber user changes)
+    if (!existsSync(CONFIG_PATH)) {
+        const defaults = {
+            enabled: true,
+            install_root: INSTALL_ROOT,
+            audit_path: join(homedir(), ".leash", "audit.jsonl"),
+            proxy_url: "http://localhost:8765",
+            daily_cap_usd: 50,
+            monthly_cap_usd: 500,
+        };
+        writeFileSync(CONFIG_PATH, JSON.stringify(defaults, null, 2));
+        success(`wrote ${CONFIG_PATH}`);
+    }
+    const sha = getInstalledSha();
+    success(`llm-leash installed at ${INSTALL_ROOT}${sha ? ` (HEAD: ${sha})` : ""}`);
+    log("");
+    log("Next: " + cyan("great-cto leash status") + " — verify proxy reachable");
+    log("      " + cyan("great-cto leash start") + " — start HTTP proxy on :8765");
+    return { exitCode: 0 };
+}
+function update(force) {
+    if (!existsSync(INSTALL_ROOT)) {
+        warn("llm-leash not installed. Run `great-cto leash install` first.");
+        return { exitCode: 1 };
+    }
+    const cfg = readConfig();
+    const beforeSha = getInstalledSha();
+    if (cfg.pinned_sha && !force) {
+        log(dim(`  pinned to ${cfg.pinned_sha} in ${CONFIG_PATH} — checkout pinned commit`));
+        const co = spawnSync("git", ["-C", INSTALL_ROOT, "fetch", "--quiet"], { stdio: "ignore", timeout: 60_000 });
+        if (co.status !== 0) {
+            error("git fetch failed");
+            return { exitCode: 1 };
+        }
+        const reset = spawnSync("git", ["-C", INSTALL_ROOT, "reset", "--hard", cfg.pinned_sha], {
+            stdio: ["ignore", "pipe", "pipe"], timeout: 30_000,
+        });
+        if (reset.status !== 0) {
+            error(`reset to pinned ${cfg.pinned_sha} failed: ${reset.stderr?.toString()}`);
+            return { exitCode: 1 };
+        }
+    }
+    else {
+        log(dim(`  git pull origin main`));
+        const pull = spawnSync("git", ["-C", INSTALL_ROOT, "pull", "--ff-only", "origin", "main"], {
+            stdio: ["ignore", "pipe", "pipe"], timeout: 60_000,
+        });
+        if (pull.status !== 0) {
+            error(`git pull failed: ${pull.stderr?.toString()}`);
+            log(`  Try: ${cyan(`cd ${INSTALL_ROOT} && git status`)}`);
+            return { exitCode: 1 };
+        }
+    }
+    const afterSha = getInstalledSha();
+    if (beforeSha === afterSha) {
+        log(dim(`  already at latest (${afterSha})`));
+        return { exitCode: 0 };
+    }
+    log(dim(`  pip install -e . --upgrade`));
+    const pip = spawnSync(pythonCmd(), ["-m", "pip", "install", "-e", INSTALL_ROOT, "--upgrade", "--quiet"], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 240_000,
+    });
+    if (pip.status !== 0) {
+        warn("pip reinstall reported errors:");
+        warn(pip.stderr?.toString() || "");
+    }
+    success(`llm-leash: ${beforeSha} → ${afterSha}`);
+    // Persist last-known SHA for the version-check hook
+    if (afterSha)
+        writeVersionCache(afterSha);
+    return { exitCode: 0 };
+}
+async function status() {
+    const installed = existsSync(INSTALL_ROOT);
+    if (!installed) {
+        log(bold("llm-leash:") + " " + dim("not installed"));
+        log(`  Install: ${cyan("great-cto leash install")}`);
+        return { exitCode: 0 };
+    }
+    const cfg = readConfig();
+    const head = getInstalledSha() || "?";
+    const latest = await fetchLatestSha();
+    log(bold("llm-leash:") + " installed at " + dim(INSTALL_ROOT));
+    log(`  Installed HEAD : ${head}`);
+    log(`  GitHub latest  : ${latest || dim("unknown (network?)")}`);
+    log(`  Config         : ${CONFIG_PATH}`);
+    log(`  Audit log      : ${cfg.audit_path || dim("default")}`);
+    log(`  Daily cap      : ${cfg.daily_cap_usd ? "$" + cfg.daily_cap_usd : dim("not set")}`);
+    log(`  Pinned SHA     : ${cfg.pinned_sha || dim("none — track main")}`);
+    if (latest && latest !== head) {
+        log("");
+        warn(`Update available. Run ${cyan("great-cto leash update")} to bump.`);
+    }
+    return { exitCode: 0 };
+}
+function startProxy(extraArgs) {
+    if (!existsSync(INSTALL_ROOT)) {
+        warn("llm-leash not installed. Run `great-cto leash install` first.");
+        return { exitCode: 1 };
+    }
+    log(`Starting llm-leash proxy on http://localhost:8765 …`);
+    log(dim(`  set ANTHROPIC_BASE_URL=http://localhost:8765 to route via leash`));
+    const r = spawnSync(pythonCmd(), ["-m", "leash.proxy", ...extraArgs], {
+        stdio: "inherit",
+    });
+    return { exitCode: r.status ?? 0 };
+}
+function killAll() {
+    const r = spawnSync("leash", ["kill", "--all", "--reason", "cli"], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+    });
+    if (r.status === 0) {
+        success("kill switch fired");
+        return { exitCode: 0 };
+    }
+    // Fall back to python -m
+    const r2 = spawnSync(pythonCmd(), ["-m", "leash", "kill", "--all", "--reason", "cli"], {
+        stdio: "inherit", timeout: 5000,
+    });
+    return { exitCode: r2.status ?? 1 };
+}
+function uninstall() {
+    if (!existsSync(INSTALL_ROOT)) {
+        log(dim("nothing to remove"));
+        return { exitCode: 0 };
+    }
+    const r = spawnSync("rm", ["-rf", INSTALL_ROOT], { stdio: "inherit", timeout: 30_000 });
+    if (r.status === 0)
+        success(`removed ${INSTALL_ROOT}`);
+    log(dim(`config left intact at ${CONFIG_PATH}`));
+    return { exitCode: r.status ?? 0 };
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function hasGit() {
+    return spawnSync("git", ["--version"], { stdio: "ignore", timeout: 3000 }).status === 0;
+}
+function hasPython() {
+    return spawnSync(pythonCmd(), ["--version"], { stdio: "ignore", timeout: 3000 }).status === 0;
+}
+function pythonCmd() {
+    // Prefer python3, fall back to python
+    if (spawnSync("python3", ["--version"], { stdio: "ignore", timeout: 2000 }).status === 0)
+        return "python3";
+    return "python";
+}
+function getInstalledSha() {
+    if (!existsSync(INSTALL_ROOT))
+        return null;
+    const r = spawnSync("git", ["-C", INSTALL_ROOT, "rev-parse", "--short", "HEAD"], {
+        stdio: ["ignore", "pipe", "ignore"], timeout: 3000,
+    });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.toString().trim();
+}
+async function fetchLatestSha() {
+    try {
+        const res = await fetch(`${REPO_API}/commits/main`, {
+            headers: {
+                "Accept": "application/vnd.github+json",
+                "User-Agent": "great-cto-leash",
+            },
+            // Node 20 has native AbortController + fetch; cap at 6 s.
+            signal: AbortSignal.timeout(6000),
+        });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        return j.sha?.slice(0, 7) || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readConfig() {
+    try {
+        if (existsSync(CONFIG_PATH))
+            return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    catch { /* ignore */ }
+    return {};
+}
+function writeVersionCache(sha) {
+    const cache = join(homedir(), ".great_cto", "leash-version.json");
+    try {
+        writeFileSync(cache, JSON.stringify({
+            installed_sha: sha,
+            last_checked: new Date().toISOString(),
+        }, null, 2));
+    }
+    catch { /* best-effort */ }
+}

package/dist/main.js

@@ -10,16 +10,17 @@
 //   7. bootstrap .great_cto/PROJECT.md
 //   8. print next steps
 import { resolve } from "node:path";
-import { banner, bold, cyan, dim, error, green, log, step, warn, yellow, confirm } from "./ui.js";
+import { banner, bold, cyan, dim, error, green, log, step, success, warn, yellow, confirm } from "./ui.js";
 import { detect } from "./detect.js";
 import { pickArchetype, suggestCompliance } from "./archetypes.js";
 import { install, findInstalledVersions } from "./installer.js";
 import { enableGreatCto } from "./settings.js";
 import { bootstrap } from "./bootstrap.js";
 import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
-import { readFileSync } from "node:fs";
+import { readFileSync, copyFileSync, chmodSync, existsSync as fsExistsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 function getCliVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -94,6 +95,8 @@ function parseArgs(argv) {
             args.command = "webhook";
         else if (a === "report")
             args.command = "report";
+        else if (a === "leash")
+            args.command = "leash";
         // Slash-commands surfaced as CLI subcommands so users get a clear hint
         // instead of a confusing usage error. These work only in the chat plugin.
         else if (a === "start" || a === "audit" || a === "inbox" || a === "digest" ||
@@ -110,8 +113,14 @@ function parseArgs(argv) {
             args.dir = a.slice("--dir=".length);
         else if (a === "--dir")
             args.dir = argv[++i] ?? args.dir;
-        else if (a === "init" || a === "help" || a === "version") {
-            args.command = a;
+        else if (a === "init" || a === "install" || a === "help" || a === "version") {
+            // `install` is an alias for `init`. Both run the same flow; only
+            // difference: `install` upgrades llm-leash to latest on every run,
+            // while `init` is silent-skip when already installed.
+            args.command = (a === "install" ? "init" : a);
+            if (a === "install") {
+                args._fromInstall = true;
+            }
         }
         else if (!a.startsWith("-") && args.command === "init" && i === 0) {
             // First positional that isn't a recognised subcommand → unknown
@@ -345,7 +354,8 @@ function printHelp() {
     log(`${bold("great-cto")} — one-command install for the great_cto Claude Code plugin
 
 ${bold("Usage:")}
-  npx great-cto [init] [options]
+  npx great-cto install [options]    Same as init; also upgrades llm-leash
+  npx great-cto [init] [options]     Detect + bootstrap; installs llm-leash if absent
   npx great-cto board [--port 3141] [--no-open]
   npx great-cto register [--dir PATH]
   npx great-cto scan [path] [--severity LVL] [--scanner NAME] [--sarif FILE]
@@ -746,6 +756,14 @@ async function runInit(args) {
     if (!bs.created) {
         log(`  ${dim("PROJECT.md already exists at")} ${bs.projectMdPath} ${dim("— kept as-is")}`);
     }
+    // ── 6. install pre-push git hook ─────────────────────────
+    installPrePushHook(args.dir);
+    // ── 7. install / update llm-leash (runtime governance) ───
+    // `init` is idempotent (silent skip when present). `install` always
+    // upgrades to the latest commit on llm-leash main. Both best-effort:
+    // missing git/python doesn't fail the flow.
+    const fromInstall = args._fromInstall === true;
+    await tryInstallLeash(fromInstall);
     // ── done ─────────────────────────────────────────────────
     log("");
     log(green(bold("✓ great_cto is ready.")));
@@ -761,6 +779,71 @@ async function runInit(args) {
     log("");
     return 0;
 }
+/**
+ * Copy scripts/hooks/pre-push.sh from the installed plugin into the project's
+ * .git/hooks/pre-push so that future pushes are scanned for private project
+ * name leaks. Best-effort — never throws.
+ */
+function installPrePushHook(projectDir) {
+    try {
+        const gitHooksDir = join(projectDir, ".git", "hooks");
+        if (!fsExistsSync(gitHooksDir))
+            return; // not a git repo — skip silently
+        const dest = join(gitHooksDir, "pre-push");
+        if (fsExistsSync(dest)) {
+            log(`  ${dim("pre-push hook already present — skipped")}`);
+            return;
+        }
+        // Locate source: dist/main.js → ../../scripts/hooks/pre-push.sh
+        const here = dirname(fileURLToPath(import.meta.url));
+        const src = join(here, "..", "..", "scripts", "hooks", "pre-push.sh");
+        if (!fsExistsSync(src)) {
+            warn("pre-push hook source not found — skipping hook installation");
+            return;
+        }
+        copyFileSync(src, dest);
+        chmodSync(dest, 0o755);
+        success("installed pre-push hook (blocks private project name leaks)");
+    }
+    catch {
+        // Best-effort: hook failure must never block init
+    }
+}
+/**
+ * Best-effort llm-leash install — runs after bootstrap so every great-cto
+ * init turns on runtime governance for free.
+ *
+ *   forceUpdate=false  (called from `init`)    — silent-skip if installed
+ *   forceUpdate=true   (called from `install`) — git pull + reinstall
+ *
+ * Never throws. Opt out via env: GREAT_CTO_SKIP_LEASH=1
+ */
+async function tryInstallLeash(forceUpdate = false) {
+    if (process.env.GREAT_CTO_SKIP_LEASH === "1") {
+        log(`  ${dim("skipped llm-leash install (GREAT_CTO_SKIP_LEASH=1)")}`);
+        return;
+    }
+    try {
+        const { runLeash } = await import("./leash.js");
+        const { existsSync } = await import("node:fs");
+        const installRoot = join(homedir(), ".great_cto", "llm-leash");
+        if (existsSync(installRoot)) {
+            if (forceUpdate) {
+                log(`  ${dim("updating llm-leash to latest …")}`);
+                await runLeash(["update"]);
+            }
+            else {
+                log(`  ${dim("llm-leash already installed — skipped")}`);
+            }
+            return;
+        }
+        log(`  ${dim("installing llm-leash (runtime governance) …")}`);
+        await runLeash(["install"]);
+    }
+    catch {
+        warn("llm-leash install failed — run `great-cto leash install` manually later");
+    }
+}
 async function main() {
     const rawArgv = process.argv.slice(2);
     const args = parseArgs(rawArgv);
@@ -886,6 +969,19 @@ async function main() {
             process.exit(2);
         }
     }
+    if (args.command === "leash") {
+        try {
+            const { runLeash } = await import("./leash.js");
+            // rawArgv[0] is "leash" — pass the rest as subcommand + flags
+            const leashArgs = rawArgv.slice(rawArgv.indexOf("leash") + 1);
+            const result = await runLeash(leashArgs);
+            process.exit(result.exitCode);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
     if (args.command === "chat-only-hint") {
         const tried = args._slashTried || "<command>";
         error(`'${tried}' is a chat slash command, not a CLI subcommand.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.9.2",
+  "version": "2.9.3",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",
@@ -70,6 +70,7 @@
     "index.mjs",
     "dist/",
     "agentshield-rules/",
+    "postinstall.mjs",
     "README.md"
   ],
   "type": "module",
@@ -77,6 +78,7 @@
     "build": "tsc",
     "test": "npm run build && node --test tests/*.test.mjs tests/**/*.test.mjs",
     "test:e2e": "npm run build && node ../../tests/run-archetype-e2e.mjs",
+    "postinstall": "node postinstall.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
@@ -86,4 +88,4 @@
   "engines": {
     "node": ">=18.17.0"
   }
-}
+}

package/postinstall.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * great-cto postinstall — best-effort one-time setup that runs when the npm
+ * package is installed globally or as a dependency.
+ *
+ * Currently does one thing: install llm-leash (https://github.com/avelikiy/llm-leash)
+ * for runtime governance — budget caps, audit log, kill switch, HITL gates.
+ *
+ * Design rules:
+ *   - NEVER fail the npm install. All errors swallowed.
+ *   - Idempotent — skips if ~/.great_cto/llm-leash already cloned.
+ *   - Honors GREAT_CTO_SKIP_LEASH=1 to opt out (CI envs, restricted machines).
+ *   - Skips on CI by default unless GREAT_CTO_FORCE_LEASH=1 — npm install in
+ *     CI shouldn't trigger 30s of git clone + pip install per build.
+ *   - Skips if `npm install` was invoked with --ignore-scripts (npm sets
+ *     `npm_config_ignore_scripts=true` — actually no, it just doesn't run
+ *     scripts; we can't detect it from inside).
+ *   - Detached output — postinstall noise is intentional and short.
+ *
+ * The "real" install path remains `great-cto leash install`. This hook just
+ * makes the common case (one-shot `npm install -g great-cto`) feel zero-config.
+ */
+
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const INSTALL_ROOT = path.join(homedir(), '.great_cto', 'llm-leash');
+
+function main() {
+  // ── opt-outs ─────────────────────────────────────────────────────────────
+  if (process.env.GREAT_CTO_SKIP_LEASH === '1') {
+    return; // silent
+  }
+
+  // Skip in CI unless explicitly forced — CI builds get no benefit from
+  // having leash installed in the runner's home dir, and the latency hurts.
+  const inCI = process.env.CI === 'true' || process.env.CI === '1';
+  if (inCI && process.env.GREAT_CTO_FORCE_LEASH !== '1') {
+    return;
+  }
+
+  // Already installed — fast exit
+  if (existsSync(INSTALL_ROOT)) {
+    return;
+  }
+
+  // Need git + python3 — bail silently if either is missing
+  if (!hasCommand('git') || !hasCommand('python3')) {
+    console.log('[great-cto] llm-leash skipped — git or python3 not on PATH');
+    console.log('[great-cto] run `great-cto leash install` later to enable runtime governance');
+    return;
+  }
+
+  // Locate the bundled dist/main.js — postinstall runs with cwd=package root
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  const cli = path.join(here, 'dist', 'main.js');
+  if (!existsSync(cli)) {
+    return; // package built incorrectly — fail-safe
+  }
+
+  console.log('[great-cto] installing llm-leash for runtime governance (~30s) …');
+  console.log('[great-cto] opt out next time: GREAT_CTO_SKIP_LEASH=1 npm install -g great-cto');
+
+  const result = spawnSync(process.execPath, [cli, 'leash', 'install'], {
+    stdio: 'inherit',
+    timeout: 300_000,
+    env: { ...process.env, NO_COLOR: process.env.NO_COLOR || '1' },
+  });
+
+  if (result.status !== 0) {
+    console.log('[great-cto] llm-leash install hit an issue — run `great-cto leash install` later');
+  }
+}
+
+function hasCommand(cmd) {
+  try {
+    const r = spawnSync(cmd, ['--version'], { stdio: 'ignore', timeout: 3000 });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+try { main(); } catch { /* never fail npm install */ }