@gatebolt/cli 0.6.0 → 0.8.0

package/README.md

@@ -56,10 +56,11 @@ gatebolt init
 ```
 
 It **links** the repository (writing a committable `.gatebolt`, exactly like `gatebolt link`),
-**wires** your agent's declare → observe hooks — for Claude Code, appended to
-`.claude/settings.local.json` — and installs a **pre-push backstop** at `.git/hooks/pre-push`
-that reconciles an open declaration before a push. It reuses a saved profile (it never signs you
-in), and is safe to re-run — it never duplicates hooks.
+**wires** your agent's declare → observe hooks — for Claude Code, merged into the committable
+`.claude/settings.json` so enforcement travels to every clone and worktree — and installs a
+**pre-push backstop** at `.git/hooks/pre-push` that reconciles an open declaration before a push.
+It reuses a saved profile (it never signs you in), and is safe to re-run — it never duplicates
+hooks.
 
 | Flag               | Description                                                                                                         |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------- |

package/dist/agents/claude-code.js

@@ -2,9 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isRecord } from "../json.js";
 const CLAUDE_DIR = ".claude";
-const SETTINGS_FILE = "settings.local.json";
-const GITIGNORE_FILE = ".gitignore";
-const GITIGNORE_ENTRY = `${CLAUDE_DIR}/${SETTINGS_FILE}`;
+const SETTINGS_FILE = "settings.json";
 const PRE_TOOL_USE = "PreToolUse";
 const STOP = "Stop";
 const EDIT_TOOLS_MATCHER = "Edit|Write|NotebookEdit";
@@ -13,18 +11,39 @@ const GUARD_SUB = "guard";
 const POST_TURN_SUB = "post-turn";
 const ENFORCE_STRICT = "strict";
 const ENFORCE_LENIENT = "lenient";
+const DENY_DECISION = "deny";
+export const MISSING_CLI_MESSAGE = "GateBolt: CLI not found on PATH - install it: npm i -g @gatebolt/cli";
+function missingCliDenyPayload() {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: PRE_TOOL_USE,
+            permissionDecision: DENY_DECISION,
+            permissionDecisionReason: MISSING_CLI_MESSAGE,
+        },
+    });
+}
+function guardCommand(cli) {
+    return (`command -v ${cli} >/dev/null 2>&1 && exec ${cli} hook ${GUARD_SUB} || ` +
+        `{ [ "$GATEBOLT_ENFORCE" = ${ENFORCE_STRICT} ] && ` +
+        `{ echo "${MISSING_CLI_MESSAGE}" >&2; ` +
+        `printf '%s\\n' '${missingCliDenyPayload()}'; }; exit 0; }`);
+}
+function postTurnCommand(cli) {
+    return (`command -v ${cli} >/dev/null 2>&1 && exec ${cli} hook ${POST_TURN_SUB} || ` +
+        `echo "${MISSING_CLI_MESSAGE}" >&2`);
+}
 export function mergeSettings(existing, opts) {
     const settings = structuredClone(existing);
     const hooks = plainObject(settings.hooks, "hooks");
     settings.hooks = hooks;
     let changed = false;
     const preToolUse = arrayField(hooks[PRE_TOOL_USE], `hooks.${PRE_TOOL_USE}`);
-    if (ensureHookCommand(preToolUse, `hook ${GUARD_SUB}`, opts.command, EDIT_TOOLS_MATCHER)) {
+    if (ensureHookCommand(preToolUse, `hook ${GUARD_SUB}`, guardCommand(opts.command), EDIT_TOOLS_MATCHER)) {
         changed = true;
     }
     hooks[PRE_TOOL_USE] = preToolUse;
     const stop = arrayField(hooks[STOP], `hooks.${STOP}`);
-    if (ensureHookCommand(stop, `hook ${POST_TURN_SUB}`, opts.command)) {
+    if (ensureHookCommand(stop, `hook ${POST_TURN_SUB}`, postTurnCommand(opts.command))) {
         changed = true;
     }
     hooks[STOP] = stop;
@@ -59,13 +78,6 @@ export function mergeSettings(existing, opts) {
     }
     return { settings, changed };
 }
-export function withGitignoreEntry(existing, entry) {
-    const present = existing.split("\n").some((line) => line.trim() === entry);
-    if (present)
-        return null;
-    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-    return `${existing}${prefix}${entry}\n`;
-}
 function plainObject(value, label) {
     if (value === undefined)
         return {};
@@ -80,11 +92,8 @@ function arrayField(value, label) {
         return value;
     throw new Error(`${SETTINGS_FILE}: "${label}" must be a JSON array.`);
 }
-// Update our command in place when it drifts, not just add-when-absent: a
-// re-run of `init` that left a stale command would silently disable the guard.
-function ensureHookCommand(entries, suffix, command, matcher) {
-    const desired = `${command} ${suffix}`;
-    const existing = findGateboltHook(entries, suffix);
+function ensureHookCommand(entries, marker, desired, matcher) {
+    const existing = findGateboltHook(entries, marker);
     if (existing) {
         if (existing.command === desired)
             return false;
@@ -95,14 +104,14 @@ function ensureHookCommand(entries, suffix, command, matcher) {
     entries.push(matcher === undefined ? { hooks: [hook] } : { matcher, hooks: [hook] });
     return true;
 }
-function findGateboltHook(entries, suffix) {
+function findGateboltHook(entries, marker) {
     for (const entry of entries) {
         if (!isRecord(entry) || !Array.isArray(entry.hooks))
             continue;
         for (const hook of entry.hooks) {
             if (isRecord(hook) &&
                 typeof hook.command === "string" &&
-                hook.command.trim().endsWith(suffix)) {
+                hook.command.includes(marker)) {
                 return hook;
             }
         }
@@ -116,11 +125,9 @@ async function wireClaudeCode(root, opts) {
         await mkdir(join(root, CLAUDE_DIR), { recursive: true });
         await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
     }
-    const gitignoreChanged = await ensureGitignore(root);
     return {
         settingsPath,
         settingsChanged: changed,
-        gitignoreChanged,
         enforce: effectiveEnforce(settings),
     };
 }
@@ -147,24 +154,6 @@ async function readSettings(path) {
     }
     return data;
 }
-async function ensureGitignore(root) {
-    const path = join(root, GITIGNORE_FILE);
-    const updated = withGitignoreEntry(await readTextOrEmpty(path), GITIGNORE_ENTRY);
-    if (updated === null)
-        return false;
-    await writeFile(path, updated, "utf8");
-    return true;
-}
-async function readTextOrEmpty(path) {
-    try {
-        return await readFile(path, "utf8");
-    }
-    catch (error) {
-        if (isNotFound(error))
-            return "";
-        throw error;
-    }
-}
 function safeParse(raw) {
     try {
         return JSON.parse(raw);

package/dist/commands/hook.js

@@ -1,6 +1,8 @@
 import { existsSync } from "node:fs";
+import { dirname } from "node:path";
 import { formatError } from "../errors.js";
 import { hasCommits, repoContext } from "../git.js";
+import { isRecord } from "../json.js";
 import { readSession } from "../session.js";
 import { RequestError } from "../transport.js";
 import { runObserve } from "./observe.js";
@@ -21,33 +23,68 @@ task — specific repo-relative paths, not broad globs like src/** :
 The GateBolt CLI is already configured for this repository. Once it
 prints "Declared change …", retry the edit.`;
 }
-export async function runHook(argv) {
-    anchorToProjectDir();
-    drainStdin();
+export async function runHook(argv, input = {}) {
     const sub = argv[0] ?? "";
     switch (sub) {
         case "guard":
-            return runGuard();
+            return runGuard(input);
         case "post-turn":
-            return runPostTurn();
+            return runPostTurn(input);
         case "pre-push":
-            return runPrePush();
+            return runPrePush(input);
         default:
             throw new Error(`Unknown hook '${sub}'. Expected one of: guard, post-turn, pre-push.`);
     }
 }
-let stdinDrained = false;
-function drainStdin() {
-    if (stdinDrained || process.stdin.isTTY)
-        return;
-    stdinDrained = true;
-    process.stdin.on("error", () => undefined);
-    process.stdin.resume();
-}
-function anchorToProjectDir() {
-    const dir = process.env.CLAUDE_PROJECT_DIR;
-    if (dir && existsSync(dir))
+async function resolveRepo(input) {
+    const candidates = [
+        input.filePath ? dirname(input.filePath) : undefined,
+        input.cwd,
+        process.env.CLAUDE_PROJECT_DIR,
+        process.cwd(),
+    ];
+    for (const dir of candidates) {
+        if (!dir || !existsSync(dir))
+            continue;
         process.chdir(dir);
+        const repo = await hookRepoContext();
+        if (repo)
+            return repo;
+    }
+    return null;
+}
+export async function readHookPayload() {
+    const data = safeJsonParse(await readStdin());
+    if (!isRecord(data))
+        return {};
+    const toolInput = isRecord(data.tool_input) ? data.tool_input : undefined;
+    return {
+        cwd: typeof data.cwd === "string" ? data.cwd : undefined,
+        filePath: toolInput && typeof toolInput.file_path === "string"
+            ? toolInput.file_path
+            : undefined,
+    };
+}
+function safeJsonParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function readStdin() {
+    if (process.stdin.isTTY)
+        return Promise.resolve("");
+    return new Promise((resolve) => {
+        const chunks = [];
+        const done = () => resolve(Buffer.concat(chunks).toString("utf8"));
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+        });
+        process.stdin.on("end", done);
+        process.stdin.on("error", done);
+    });
 }
 async function hookRepoContext() {
     try {
@@ -57,10 +94,10 @@ async function hookRepoContext() {
         return null;
     }
 }
-async function runGuard() {
+async function runGuard(input) {
     if (process.env.GATEBOLT_ENFORCE !== ENFORCE_STRICT)
         return;
-    const repo = await hookRepoContext();
+    const repo = await resolveRepo(input);
     if (!repo)
         return;
     if (await readSession(repo.gitDir))
@@ -71,8 +108,8 @@ async function runGuard() {
     const cli = process.env.GATEBOLT_CLI ?? DEFAULT_CLI;
     process.stdout.write(denyPayload(declareInstructions(cli)));
 }
-async function runPostTurn() {
-    const repo = await hookRepoContext();
+async function runPostTurn(input) {
+    const repo = await resolveRepo(input);
     if (!repo)
         return;
     if (!(await readSession(repo.gitDir)))
@@ -86,8 +123,8 @@ async function runPostTurn() {
 }
 // Backstop for the interrupt case the Stop hook misses: an open, un-observed
 // declaration.
-async function runPrePush() {
-    const repo = await hookRepoContext();
+async function runPrePush(input) {
+    const repo = await resolveRepo(input);
     if (!repo)
         return;
     if (!(await readSession(repo.gitDir)))

package/dist/commands/init.js

@@ -3,9 +3,9 @@ import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { delimiter, dirname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { claudeCodeAdapter } from "../agents/claude-code.js";
+import { claudeCodeAdapter, MISSING_CLI_MESSAGE, } from "../agents/claude-code.js";
 import { repoIdentityFromName, resolveConnection } from "../config.js";
-import { hooksPath, repoContext } from "../git.js";
+import { hooksPath, isPathIgnored, isUncommitted, repoContext, } from "../git.js";
 import { isRecord } from "../json.js";
 import { pinRepoProfile, profileLoader, readRepoLink } from "../profiles.js";
 import { deriveIdentity, linkRepository } from "./link.js";
@@ -15,10 +15,10 @@ const PRE_PUSH_FILE = "pre-push";
 const PRE_PUSH_MARKER = "GateBolt pre-push backstop";
 const HOOK_MODE = 0o755;
 const ID_PREFIX_LEN = 8;
-const GITIGNORE_ENTRY = ".claude/settings.local.json";
 const NO_REMOTE = "GateBolt cannot derive this repository's identity from its `origin` remote. Re-run with --name <a-name-for-this-repo>.";
 const NO_KEY = "No GateBolt key found. Run `gatebolt login` (or `gatebolt configure`) first, then re-run `gatebolt init`.";
-const EPHEMERAL_CLI = "GateBolt is running from a temporary npx/dlx cache, so the hooks would break when the package manager prunes it. Install it durably first — `npm i -g @gatebolt/cli`, or add it as a project dependency so `gatebolt` is on PATH — then re-run `gatebolt init`. To link only, pass --no-hooks --no-pre-push.";
+const EPHEMERAL_CLI = "GateBolt is running from a temporary npx/dlx cache, so the hooks would break when the package manager prunes it. Install it durably so `gatebolt` is on PATH on every machine — `npm i -g @gatebolt/cli` — then re-run `gatebolt init`. To link only, pass --no-hooks --no-pre-push.";
+const NOT_ON_PATH = "GateBolt isn't on your PATH, so a committed hook command would only name a path that exists on this machine. Install it durably so `gatebolt` is on PATH on every machine — `npm i -g @gatebolt/cli` — then re-run `gatebolt init`. To link only, pass --no-hooks --no-pre-push.";
 export async function runInit(argv) {
     const { values } = parseArgs({
         args: argv,
@@ -47,6 +47,7 @@ export async function runInit(argv) {
     const prePush = values["no-pre-push"]
         ? null
         : await installPrePush(command, Boolean(values.force));
+    const settingsState = await settingsGitState(wired[0]?.result.settingsPath);
     process.stdout.write(summary({
         root: repo.root,
         link,
@@ -54,6 +55,7 @@ export async function runInit(argv) {
         prePush,
         enforce: wired[0]?.result.enforce ?? enforce ?? "lenient",
         noHooks: Boolean(values["no-hooks"]),
+        ...settingsState,
     }));
 }
 export function parseEnforce(value) {
@@ -94,14 +96,25 @@ async function ensureLink(connection, root, name) {
         created: result.created,
     };
 }
+async function settingsGitState(settingsPath) {
+    if (!settingsPath) {
+        return { settingsIgnored: false, settingsUncommitted: false };
+    }
+    const settingsIgnored = await isPathIgnored(settingsPath);
+    const settingsUncommitted = settingsIgnored
+        ? false
+        : await isUncommitted(settingsPath);
+    return { settingsIgnored, settingsUncommitted };
+}
 function resolveCommand(root) {
     const cli = fileURLToPath(new URL("../index.js", import.meta.url));
     if (isEphemeralPath(cli)) {
         throw new Error(EPHEMERAL_CLI);
     }
-    if (onDurablePath("gatebolt", root))
-        return "gatebolt";
-    return `${quote(process.execPath)} ${quote(cli)}`;
+    if (!onDurablePath("gatebolt", root)) {
+        throw new Error(NOT_ON_PATH);
+    }
+    return "gatebolt";
 }
 // npx/dlx run from throwaway caches that get pruned, breaking any hook wired
 // here: npm marks them with an `_npx` segment, pnpm with `dlx`, yarn with `xfs-…`.
@@ -122,9 +135,6 @@ function isInsideRoot(dir, root) {
     const rel = relative(root, dir);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-function quote(value) {
-    return /\s/.test(value) ? `"${value}"` : value;
-}
 async function wireAgents(root, command, enforce) {
     const wired = [];
     for (const adapter of ADAPTERS) {
@@ -153,6 +163,10 @@ export function prePushScript(command) {
     return [
         "#!/usr/bin/env sh",
         `# ${PRE_PUSH_MARKER} — reconciles an open declaration before a push.`,
+        `if ! command -v ${command} >/dev/null 2>&1; then`,
+        `  echo "${MISSING_CLI_MESSAGE}" >&2`,
+        "  exit 0",
+        "fi",
         `exec ${command} hook ${PRE_PUSH_FILE}`,
         "",
     ].join("\n");
@@ -175,6 +189,12 @@ function summary(parts) {
         "",
         enforceLine(parts.enforce),
     ];
+    if (!parts.noHooks && parts.settingsIgnored) {
+        lines.push("Warning: .claude/settings.json is gitignored, so committing it won't work — enforcement won't travel to other clones or worktrees until you remove the ignore rule and commit it.");
+    }
+    else if (!parts.noHooks && parts.settingsUncommitted) {
+        lines.push("Commit .claude/settings.json so every worktree, clone, and machine enforces this policy.");
+    }
     if (!parts.link.existed) {
         lines.push("Commit .gatebolt so every clone and CI job resolves the same repository.");
     }
@@ -194,9 +214,6 @@ function hookLines(root, wired, noHooks) {
     for (const { displayName, result } of wired) {
         const verb = result.settingsChanged ? "wired" : "already wired";
         lines.push(`${displayName}: ${verb} → ${relative(root, result.settingsPath)}`);
-        if (result.gitignoreChanged) {
-            lines.push(`  ignored ${GITIGNORE_ENTRY} in .gitignore`);
-        }
     }
     return lines;
 }

package/dist/git.js

@@ -34,6 +34,21 @@ export async function hooksPath() {
     const output = await git(["rev-parse", "--git-path", "hooks"]);
     return resolve(output.trim());
 }
+export async function isPathIgnored(path) {
+    try {
+        await git(["check-ignore", "--quiet", path]);
+        return true;
+    }
+    catch (error) {
+        if (gitExitedNonZero(error))
+            return false;
+        throw gitFailure(error);
+    }
+}
+export async function isUncommitted(path) {
+    const output = await git(["status", "--porcelain", "--", path]);
+    return output.trim() !== "";
+}
 export async function remoteOriginUrl() {
     try {
         const output = await git(["remote", "get-url", "origin"]);

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { runConfigure } from "./commands/configure.js";
 import { runDeclare } from "./commands/declare.js";
-import { runHook } from "./commands/hook.js";
+import { readHookPayload, runHook } from "./commands/hook.js";
 import { runInit } from "./commands/init.js";
 import { runLink } from "./commands/link.js";
 import { runLogin } from "./commands/login.js";
@@ -43,7 +43,7 @@ async function dispatch(command, argv) {
         case "init":
             return runInit(argv);
         case "hook":
-            return runHook(argv);
+            return runHook(argv, await readHookPayload());
         default:
             process.stderr.write(`${USAGE}\nRun \`gatebolt --help\` for details.\n`);
             process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatebolt/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Declare-then-observe agent client for GateBolt — records the files an AI agent intends to touch, then reconciles the actual git diff.",
   "keywords": [
     "gatebolt",