@gatebolt/cli 0.4.0 → 0.5.0

package/README.md

@@ -21,34 +21,77 @@ Requires Node ≥ 20 and `git` on your `PATH`.
 
 ## Configure
 
-Every command needs three settings — an API **key**, the GateBolt **URL**, and the **repo
-slug** to record the work against. Store them once as a named **profile** in
-`~/.gatebolt/config.json` (written owner-only, `0600`):
+Every command needs two connection settings — an API **key** and the GateBolt **URL**. Store
+them once as a **profile** in `~/.gatebolt/config.json` (written owner-only, `0600`):
 
 ```
-gatebolt configure --profile payments-api \
-  --url https://your-gatebolt.app --repo payments-api
+gatebolt configure --url https://your-gatebolt.app
 # paste the API key when prompted (or pass --key for scripting)
 ```
 
-The `--repo` value is normalized to a slug (lowercase, hyphen-separated), so
-`Payments_API` is stored and reported as `payments-api`.
+One profile per GateBolt workspace. `--profile <name>` saves another alongside it; without the
+flag it saves `default`, and a second `configure` refuses rather than replace the first
+workspace's key. (`gatebolt login` writes a profile for you.)
 
-Add a profile per repo. Inside a repo, the CLI picks the active profile in this order:
+Which repository each change belongs to is recorded separately, by `gatebolt link` (below).
+Inside a repo, the CLI picks the active profile in this order:
 
 1. `--profile <name>` flag
 2. `GATEBOLT_PROFILE` env var
-3. a `.gatebolt` file at the repo root holding a profile name — safe to commit (no secret)
+3. the `profile` field of a committable `.gatebolt` file (see `gatebolt link`)
 4. the sole profile, when there is only one
 5. the `default` profile
 
-An individual setting can still be overridden ad-hoc: a flag (`--key` / `--url` / `--repo`)
-or the `GBOLT_KEY` / `GBOLT_URL` / `GBOLT_REPO` env var wins over the profile, so a
-fully-env setup needs no profile file at all. Point the config elsewhere (CI, tests) with
-`GATEBOLT_CONFIG`.
+An individual setting can still be overridden ad-hoc: a flag (`--key` / `--url`) or the
+`GATEBOLT_KEY` / `GATEBOLT_URL` env var wins over the profile, so a fully-env setup needs no profile
+file at all. Point the config elsewhere (CI, tests) with `GATEBOLT_CONFIG`.
 
-> **Rate limit.** A new key allows 10 requests/day (~5 changes) today — grab a fresh key
-> while iterating, and a `401` means you hit the daily limit.
+## `gatebolt init`
+
+Sets up GateBolt in a repository in one command. Run it once from the repo root, after saving a
+key (see [Configure](#configure)):
+
+```
+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.
+
+| Flag               | Description                                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `--enforce <mode>` | `strict` blocks edits until you declare; `lenient` keeps it advisory; omit to leave a repo's current mode unchanged |
+| `--no-hooks`       | Only link the repository; don't wire the agent hooks                                                                |
+| `--no-pre-push`    | Don't install the pre-push backstop                                                                                 |
+| `--force`          | Replace an existing, non-GateBolt pre-push hook                                                                     |
+| `--name <name>`    | Name the repository (when there is no `origin` remote to derive from)                                               |
+
+`--profile` selects a saved profile. Unlike the other commands, `init` takes no `--key` / `--url`:
+the hooks it wires authenticate later, so they need a durable saved profile, not one-off flags
+(`GATEBOLT_KEY` / `GATEBOLT_URL` env still apply).
+
+The hooks call `gatebolt hook <guard|post-turn|pre-push>` — internal subcommands you don't run by
+hand: `guard` blocks an edit until a declaration exists (strict mode), `post-turn` reconciles the
+diff when a turn ends, and `pre-push` reconciles before a push.
+
+## `gatebolt link`
+
+Records **which repository** this checkout is, so every clone, worktree and CI job records
+against the same one. Run it once per repo, from the repo root, and commit the file it writes:
+
+```
+gatebolt link
+git add .gatebolt && git commit -m "record the GateBolt repository"
+```
+
+It derives the repository's name from the `origin` remote (or pass `--name` when there is no
+remote), asks the server to find-or-create it, and writes the repository id to a committable
+`.gatebolt` file. `declare` and `observe` read that id; when `.gatebolt` is absent, `declare`
+links automatically from the remote. The file is authoritative — a malformed one is a hard
+error telling you to re-run `gatebolt link`, never a silent guess.
 
 ## `gatebolt declare`
 
@@ -116,5 +159,5 @@ than 2000 files is rejected; narrow the change.
 - **One session per worktree.** Session state lives in `<git-dir>/gatebolt/`, which is
   per-worktree. Run one agent session per working tree; for parallel agents, use separate git
   worktrees (a shared tree can't attribute one diff to two sessions).
-- **Claude Code.** To run the declare → observe loop automatically inside a Claude Code
-  session, use the hook recipe in [`recipes/claude-code/`](./recipes/claude-code/).
+- **Claude Code.** `gatebolt init` wires the declare → observe loop to run automatically inside a
+  Claude Code session — see [`gatebolt init`](#gatebolt-init).

package/dist/agents/claude-code.js

@@ -0,0 +1,183 @@
+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 PRE_TOOL_USE = "PreToolUse";
+const STOP = "Stop";
+const EDIT_TOOLS_MATCHER = "Edit|Write|NotebookEdit";
+const COMMAND_TYPE = "command";
+const GUARD_SUB = "guard";
+const POST_TURN_SUB = "post-turn";
+const ENFORCE_STRICT = "strict";
+const ENFORCE_LENIENT = "lenient";
+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)) {
+        changed = true;
+    }
+    hooks[PRE_TOOL_USE] = preToolUse;
+    const stop = arrayField(hooks[STOP], `hooks.${STOP}`);
+    if (ensureHookCommand(stop, `hook ${POST_TURN_SUB}`, opts.command)) {
+        changed = true;
+    }
+    hooks[STOP] = stop;
+    if (opts.enforce === ENFORCE_STRICT) {
+        const env = plainObject(settings.env, "env");
+        settings.env = env;
+        if (env.GATEBOLT_ENFORCE !== ENFORCE_STRICT) {
+            env.GATEBOLT_ENFORCE = ENFORCE_STRICT;
+            changed = true;
+        }
+        if (env.GATEBOLT_CLI !== opts.command) {
+            env.GATEBOLT_CLI = opts.command;
+            changed = true;
+        }
+    }
+    else if (opts.enforce === ENFORCE_LENIENT && settings.env !== undefined) {
+        const env = plainObject(settings.env, "env");
+        if ("GATEBOLT_ENFORCE" in env) {
+            delete env.GATEBOLT_ENFORCE;
+            changed = true;
+        }
+        if ("GATEBOLT_CLI" in env) {
+            delete env.GATEBOLT_CLI;
+            changed = true;
+        }
+        if (Object.keys(env).length === 0) {
+            delete settings.env;
+        }
+        else {
+            settings.env = env;
+        }
+    }
+    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 {};
+    if (isRecord(value) && !Array.isArray(value))
+        return value;
+    throw new Error(`${SETTINGS_FILE}: "${label}" must be a JSON object.`);
+}
+function arrayField(value, label) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        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);
+    if (existing) {
+        if (existing.command === desired)
+            return false;
+        existing.command = desired;
+        return true;
+    }
+    const hook = { type: COMMAND_TYPE, command: desired };
+    entries.push(matcher === undefined ? { hooks: [hook] } : { matcher, hooks: [hook] });
+    return true;
+}
+function findGateboltHook(entries, suffix) {
+    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)) {
+                return hook;
+            }
+        }
+    }
+    return undefined;
+}
+async function wireClaudeCode(root, opts) {
+    const settingsPath = join(root, CLAUDE_DIR, SETTINGS_FILE);
+    const { settings, changed } = mergeSettings(await readSettings(settingsPath), opts);
+    if (changed) {
+        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),
+    };
+}
+function effectiveEnforce(settings) {
+    const env = settings.env;
+    if (isRecord(env) && env.GATEBOLT_ENFORCE === ENFORCE_STRICT) {
+        return ENFORCE_STRICT;
+    }
+    return ENFORCE_LENIENT;
+}
+async function readSettings(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return {};
+        throw error;
+    }
+    const data = safeParse(raw);
+    if (!isRecord(data) || Array.isArray(data)) {
+        throw new Error(`${path} is not a JSON object. Fix or remove it, then re-run \`gatebolt init\`.`);
+    }
+    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);
+    }
+    catch {
+        return null;
+    }
+}
+function isNotFound(error) {
+    return isRecord(error) && error.code === "ENOENT";
+}
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    displayName: "Claude Code",
+    wire: wireClaudeCode,
+};

package/dist/commands/configure.js

@@ -2,37 +2,34 @@ import { stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
 import { parseArgs } from "node:util";
-import { slugifyRepo } from "../config.js";
 import { readConfigForWrite, writeConfig } from "../profiles.js";
+const DEFAULT_PROFILE = "default";
 export async function runConfigure(argv) {
     const { values } = parseArgs({
         args: argv,
         options: {
             profile: { type: "string" },
             url: { type: "string" },
-            repo: { type: "string" },
             key: { type: "string" },
         },
     });
-    const repo = slugifyRepo(requireFlag(values.repo, "--repo"));
     const url = values.url?.replace(/\/+$/, "");
-    const name = values.profile ?? repo;
+    const name = values.profile ?? DEFAULT_PROFILE;
     const key = (values.key ?? (await promptForKey())).trim();
     if (!key) {
         throw new Error("No API key provided.");
     }
     const config = await readConfigForWrite();
-    config.profiles[name] = url ? { url, repo, key } : { repo, key };
+    const existing = config.profiles[name];
+    if (!values.profile && existing && existing.key !== key) {
+        throw new Error(`Profile "${name}" already holds a different key. Pass --profile <name> to save ` +
+            `this one alongside it, or --profile ${name} to replace it.`);
+    }
+    config.profiles[name] = url ? { url, key } : { key };
     config.default ??= name;
     const path = await writeConfig(config);
     process.stdout.write(`Saved profile "${name}" to ${path}.\n`);
 }
-function requireFlag(value, flag) {
-    if (!value) {
-        throw new Error(`Missing required option ${flag}.`);
-    }
-    return value;
-}
 async function promptForKey() {
     let muted = false;
     const output = new Writable({

package/dist/commands/declare.js

@@ -1,13 +1,26 @@
 import { randomUUID } from "node:crypto";
 import { relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
-import { resolveConnection, resolveRepoSlug } from "../config.js";
+import { resolveConnection } from "../config.js";
 import { AGENT_VENDORS, DECLARED_FILES_MAX, isAgentVendor, TASK_MAX_LENGTH, } from "../contracts.js";
 import { currentBranch, currentHead, hasCommits, repoContext } from "../git.js";
 import { isRecord } from "../json.js";
-import { profileLoader } from "../profiles.js";
-import { readPendingDeclare, writePendingDeclare, writeSession, } from "../session.js";
+import { profileLoader, readRepoLink } from "../profiles.js";
+import { clearPendingDeclare, clearSession, readPendingDeclare, readSession, writePendingDeclare, writeSession, } from "../session.js";
 import { postChange } from "../transport.js";
+import { deriveIdentity, linkRepository } from "./link.js";
+const NO_REMOTE = `GateBolt cannot derive this repository's identity from its \`origin\` remote.
+
+Ask a human to run this once, from the repo root:
+
+  gatebolt link --name <a-name-for-this-repo>
+
+It writes a .gatebolt file holding the repository id. Commit that file and every
+clone, worktree and CI job will resolve the same repository.
+
+Do not guess a name. A wrong name creates a second repository and splits this
+repo's audit trail in two.`;
+const ID_PREFIX_LEN = 8;
 export async function runDeclare(argv) {
     const { values } = parseArgs({
         args: argv,
@@ -15,7 +28,6 @@ export async function runDeclare(argv) {
             key: { type: "string" },
             url: { type: "string" },
             profile: { type: "string" },
-            repo: { type: "string" },
             task: { type: "string" },
             vendor: { type: "string" },
             name: { type: "string" },
@@ -23,8 +35,12 @@ export async function runDeclare(argv) {
             "agent-version": { type: "string" },
             "launched-by": { type: "string" },
             file: { type: "string", multiple: true },
+            abort: { type: "boolean" },
         },
     });
+    if (values.abort) {
+        return abortDeclaration();
+    }
     const rawFiles = collectFiles(values.file);
     if (rawFiles.length === 0) {
         throw new Error("Declare at least one file with --file.");
@@ -56,10 +72,10 @@ export async function runDeclare(argv) {
     const { gitDir: dir, root } = repo;
     const loadProfile = profileLoader({ name: values.profile, root });
     const connection = await resolveConnection({ key: values.key, url: values.url }, loadProfile);
-    const repoSlug = await resolveRepoSlug({ repo: values.repo }, loadProfile);
     if (!(await hasCommits())) {
         throw new Error("This repository has no commits yet — make an initial commit before declaring.");
     }
+    const repositoryId = await resolveRepositoryId(root, connection);
     const baseSha = await currentHead();
     const branch = await currentBranch();
     const declaredFiles = dedupeByPath(rawFiles.map((raw) => ({ path: normalizeRepoPath(root, raw) })));
@@ -67,7 +83,7 @@ export async function runDeclare(argv) {
         throw new Error(`Declaring ${declaredFiles.length} files, over the ${DECLARED_FILES_MAX} limit. Narrow the change.`);
     }
     const intentKey = buildIntentKey({
-        repoSlug,
+        repositoryId,
         task,
         agent,
         baseSha,
@@ -75,7 +91,7 @@ export async function runDeclare(argv) {
     });
     const correlationId = correlationIdFor(await readPendingDeclare(dir), intentKey);
     const input = buildDeclareInput({
-        repoSlug,
+        repositoryId,
         task,
         agent,
         declaredFiles,
@@ -92,15 +108,40 @@ export async function runDeclare(argv) {
         changeId: result.changeId,
         baseSha,
         branch,
+        profile: connection.profileName,
     });
     process.stdout.write(`Declared change ${result.changeId} (${declaredFiles.length} file(s)).\n`);
 }
+async function abortDeclaration() {
+    const repo = await repoContext();
+    if (!repo) {
+        throw new Error("Not inside a git repository.");
+    }
+    const session = await readSession(repo.gitDir);
+    if (!session) {
+        process.stdout.write("No open declaration to clear.\n");
+        return;
+    }
+    await clearSession(repo.gitDir);
+    await clearPendingDeclare(repo.gitDir);
+    process.stdout.write(`Cleared the open declaration (change ${session.changeId.slice(0, ID_PREFIX_LEN)}…). Declare again to track new work.\n`);
+}
+async function resolveRepositoryId(root, connection) {
+    const link = await readRepoLink(root);
+    if (link)
+        return link.repositoryId;
+    const identity = await deriveIdentity();
+    if (!identity) {
+        throw new Error(NO_REMOTE);
+    }
+    return (await linkRepository(connection, root, identity)).repositoryId;
+}
 export function isDeclareResult(value) {
     return isRecord(value) && typeof value.changeId === "string";
 }
 export function buildIntentKey(parts) {
     return JSON.stringify({
-        repoSlug: parts.repoSlug,
+        repositoryId: parts.repositoryId,
         task: parts.task,
         agent: parts.agent,
         baseSha: parts.baseSha,
@@ -109,7 +150,7 @@ export function buildIntentKey(parts) {
 }
 function buildDeclareInput(parts) {
     const input = {
-        repoSlug: parts.repoSlug,
+        repositoryId: parts.repositoryId,
         task: parts.task,
         agent: parts.agent,
         declaredFiles: parts.declaredFiles,

package/dist/commands/hook.js

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { formatError } from "../errors.js";
+import { hasCommits, repoContext } from "../git.js";
+import { readSession } from "../session.js";
+import { RequestError } from "../transport.js";
+import { runObserve } from "./observe.js";
+const ENFORCE_STRICT = "strict";
+const PRE_TOOL_USE = "PreToolUse";
+const DENY_DECISION = "deny";
+const DEFAULT_CLI = "gatebolt";
+function declareInstructions(cli) {
+    return `GateBolt strict mode: declare the files you plan to touch before editing.
+Run this in Bash first, listing EVERY file you plan to create or modify for this
+task — specific repo-relative paths, not broad globs like src/** :
+
+  ${cli} declare \\
+    --task "<one line describing the task>" \\
+    --vendor claude_code --name "Claude Code" --model <your-model-id> \\
+    --file <path> [--file <path> ...]
+
+The GateBolt CLI is already configured for this repository. Once it
+prints "Declared change …", retry the edit.`;
+}
+export async function runHook(argv) {
+    anchorToProjectDir();
+    drainStdin();
+    const sub = argv[0] ?? "";
+    switch (sub) {
+        case "guard":
+            return runGuard();
+        case "post-turn":
+            return runPostTurn();
+        case "pre-push":
+            return runPrePush();
+        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))
+        process.chdir(dir);
+}
+async function hookRepoContext() {
+    try {
+        return await repoContext();
+    }
+    catch {
+        return null;
+    }
+}
+async function runGuard() {
+    if (process.env.GATEBOLT_ENFORCE !== ENFORCE_STRICT)
+        return;
+    const repo = await hookRepoContext();
+    if (!repo)
+        return;
+    if (await readSession(repo.gitDir))
+        return;
+    const hasBaseCommit = await hasCommits();
+    if (!hasBaseCommit)
+        return;
+    const cli = process.env.GATEBOLT_CLI ?? DEFAULT_CLI;
+    process.stdout.write(denyPayload(declareInstructions(cli)));
+}
+async function runPostTurn() {
+    const repo = await hookRepoContext();
+    if (!repo)
+        return;
+    if (!(await readSession(repo.gitDir)))
+        return;
+    try {
+        await runObserve([]);
+    }
+    catch (error) {
+        process.stderr.write(`${formatError(error)}\n`);
+    }
+}
+// Backstop for the interrupt case the Stop hook misses: an open, un-observed
+// declaration.
+async function runPrePush() {
+    const repo = await hookRepoContext();
+    if (!repo)
+        return;
+    if (!(await readSession(repo.gitDir)))
+        return;
+    process.stderr.write("GateBolt: an un-observed declaration is still open; reconciling before push…\n");
+    try {
+        await runObserve([]);
+    }
+    catch (error) {
+        if (isUnreachable(error)) {
+            process.stderr.write("GateBolt: couldn't reach the server to reconcile; allowing the push.\n" +
+                `${formatError(error)}\n` +
+                "The declaration stays open and will reconcile on your next `gatebolt observe`.\n");
+            return;
+        }
+        process.stderr.write("GateBolt: observe failed — refusing to push unreconciled work.\n" +
+            `${formatError(error)}\n` +
+            "Resolve the error above (or run `gatebolt observe` yourself), then push again.\n" +
+            "If this declaration can no longer be reconciled, run `gatebolt declare --abort` to clear it.\n");
+        process.exitCode = 1;
+    }
+}
+function isUnreachable(error) {
+    return (error instanceof RequestError &&
+        (error.code === "NETWORK" || error.code === "TIMEOUT"));
+}
+// Claude Code's PreToolUse deny contract. Emitting this JSON on stdout with a
+// zero exit holds the block even under --dangerously-skip-permissions, where an
+// exit-2 fallback would not.
+export function denyPayload(reason) {
+    return (JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: PRE_TOOL_USE,
+            permissionDecision: DENY_DECISION,
+            permissionDecisionReason: reason,
+        },
+    }) + "\n");
+}