@gatebolt/cli 0.2.0

package/README.md

@@ -0,0 +1,114 @@
+# @gatebolt/cli
+
+The GateBolt agent client. An AI agent **declares** the files it intends to touch before it
+edits, then **observes** the actual diff when work lands; GateBolt reconciles the two and
+scores the drift. This CLI is a thin, dependency-light wrapper (Node `fetch` + `git` via
+`child_process`, zero runtime dependencies) over the `change.declare` / `change.observe`
+ingestion API.
+
+## Install
+
+```
+npm i -g @gatebolt/cli    # global `gatebolt` binary
+# …or run on demand:
+npx @gatebolt/cli declare …
+```
+
+Requires Node ≥ 20 and `git` on your `PATH`.
+
+## Configure
+
+Every command needs three settings — an API **key**, the GateBolt **URL**, and the **repo
+slug** bound to that key. Store them once as a named **profile** in `~/.gatebolt/config.json`
+(written owner-only, `0600`):
+
+```
+gatebolt configure --profile payments-api \
+  --url https://your-gatebolt.app --repo payments-api
+# 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`.
+
+Add a profile per repo. 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)
+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`.
+
+> **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 declare`
+
+Records the agent's intended files **before** editing. Snapshots the current commit
+(`git rev-parse HEAD`) as the base plus the current branch, and writes `{ changeId, baseSha }`
+to `<git-dir>/gatebolt/session.json`. The repository must have at least one commit.
+
+| Flag                    | Required | Description                                                             |
+| ----------------------- | -------- | ----------------------------------------------------------------------- |
+| `--task <text>`         | yes      | What the agent is doing                                                 |
+| `--vendor <vendor>`     | yes      | `claude_code` \| `cursor` \| `copilot` \| `codex` \| `devin` \| `other` |
+| `--name <name>`         | yes      | Agent name                                                              |
+| `--model <model>`       | yes      | Model id                                                                |
+| `--file <path>`         | yes\*    | Intended file (repeatable, one per path)                                |
+| `--version <v>`         | no       | Agent/tool version                                                      |
+| `--launched-by <email>` | no       | Who launched the agent                                                  |
+| `--profile <name>`      | no       | Profile to resolve `key`/`url`/`repo` from                              |
+
+\* At least one `--file` is required. Repeat it per path (`--file a --file b`)
+rather than comma-joining, so paths that contain commas stay intact.
+
+Declared paths must be **repo-root-relative** and match git's output exactly, or be a
+directory glob like `src/auth/**` — a bare `src/auth` will **not** match the files inside it.
+
+```
+gatebolt declare \
+  --task "Refresh session on token expiry" \
+  --vendor claude_code --name "Claude Code" --model opus-4 \
+  --file src/auth/session.ts
+# → Declared change 1df4210c-… (1 file(s)).
+```
+
+## `gatebolt observe`
+
+Derives the actual diff from git when work lands, posts it, and prints the drift verdict. It
+takes no file arguments — it reads the session written by `declare`.
+
+| Flag                 | Required | Description                                        |
+| -------------------- | -------- | -------------------------------------------------- |
+| `--change-id <uuid>` | no       | Change to observe (defaults to the active session) |
+| `--base <sha>`       | no       | Base commit to diff against (defaults to session)  |
+| `--profile <name>`   | no       | Profile to resolve `key`/`url` from                |
+
+```
+gatebolt observe
+# Change  1df4210c-…
+# Drift   critical (100)
+# Files   1 matched, 1 unexpected, 0 missing
+#   Touched 1 undeclared secrets file: .env
+```
+
+`observe` diffs the working tree against the recorded base (`git diff <base>`) and sweeps in
+untracked files, so uncommitted edits and newly created files are both captured. It accepts a
+base that is an ancestor of HEAD or one HEAD amended/squashed in place on the same branch, but
+**refuses if the working tree has diverged from the recorded base** — a branch switch or reset
+would fold in unrelated work, so re-run `declare`. It is **advisory** — it exits `0` regardless of the
+drift level (errors exit non-zero) — and on success it clears the session. A diff touching more
+than 2000 files is rejected; narrow the change.
+
+## Notes
+
+- **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/).

package/dist/commands/configure.js

@@ -0,0 +1,43 @@
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { slugifyRepo } from "../config.js";
+import { readConfigForWrite, writeConfig } from "../profiles.js";
+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 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 };
+    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() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        return await rl.question("API key: ");
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/commands/declare.js

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { relative, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { resolveConnection, resolveRepoSlug } 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 { postChange } from "../transport.js";
+export async function runDeclare(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            key: { type: "string" },
+            url: { type: "string" },
+            profile: { type: "string" },
+            repo: { type: "string" },
+            task: { type: "string" },
+            vendor: { type: "string" },
+            name: { type: "string" },
+            model: { type: "string" },
+            version: { type: "string" },
+            "launched-by": { type: "string" },
+            file: { type: "string", multiple: true },
+        },
+    });
+    const rawFiles = collectFiles(values.file);
+    if (rawFiles.length === 0) {
+        throw new Error("Declare at least one file with --file.");
+    }
+    const vendor = requireFlag(values.vendor, "--vendor");
+    if (!isAgentVendor(vendor)) {
+        throw new Error(`Invalid --vendor '${vendor}'. Expected one of: ${AGENT_VENDORS.join(", ")}.`);
+    }
+    const agent = {
+        vendor,
+        name: requireFlag(values.name, "--name"),
+        model: requireFlag(values.model, "--model"),
+    };
+    if (values.version)
+        agent.version = values.version;
+    const launchedBy = values["launched-by"];
+    if (launchedBy && !isValidEmail(launchedBy)) {
+        throw new Error(`Invalid --launched-by '${launchedBy}'. Expected an email address.`);
+    }
+    const task = requireFlag(values.task, "--task");
+    if (task.length > TASK_MAX_LENGTH) {
+        throw new Error(`--task is ${task.length} characters, over the ${TASK_MAX_LENGTH} limit.`);
+    }
+    const repo = await repoContext();
+    if (!repo) {
+        throw new Error("Not inside a git repository.");
+    }
+    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 baseSha = await currentHead();
+    const branch = await currentBranch();
+    const declaredFiles = dedupeByPath(rawFiles.map((raw) => ({ path: normalizeRepoPath(root, raw) })));
+    if (declaredFiles.length > DECLARED_FILES_MAX) {
+        throw new Error(`Declaring ${declaredFiles.length} files, over the ${DECLARED_FILES_MAX} limit. Narrow the change.`);
+    }
+    const intentKey = buildIntentKey({
+        repoSlug,
+        task,
+        agent,
+        baseSha,
+        declaredFiles,
+    });
+    const correlationId = correlationIdFor(await readPendingDeclare(dir), intentKey);
+    const input = buildDeclareInput({
+        repoSlug,
+        task,
+        agent,
+        declaredFiles,
+        correlationId,
+        launchedBy,
+        branch,
+    });
+    await writePendingDeclare(dir, { correlationId, intentKey });
+    const result = await postChange(connection, "change.declare", input);
+    if (!isDeclareResult(result)) {
+        throw new Error("Unexpected response from server.");
+    }
+    await writeSession(dir, {
+        changeId: result.changeId,
+        baseSha,
+        branch,
+    });
+    process.stdout.write(`Declared change ${result.changeId} (${declaredFiles.length} file(s)).\n`);
+}
+export function isDeclareResult(value) {
+    return isRecord(value) && typeof value.changeId === "string";
+}
+export function buildIntentKey(parts) {
+    return JSON.stringify({
+        repoSlug: parts.repoSlug,
+        task: parts.task,
+        agent: parts.agent,
+        baseSha: parts.baseSha,
+        files: parts.declaredFiles.map((file) => file.path).sort(),
+    });
+}
+function buildDeclareInput(parts) {
+    const input = {
+        repoSlug: parts.repoSlug,
+        task: parts.task,
+        agent: parts.agent,
+        declaredFiles: parts.declaredFiles,
+        correlationId: parts.correlationId,
+    };
+    if (parts.launchedBy)
+        input.launchedBy = parts.launchedBy;
+    if (parts.branch)
+        input.branch = parts.branch;
+    return input;
+}
+export function correlationIdFor(pending, intentKey) {
+    if (pending?.intentKey === intentKey) {
+        return pending.correlationId;
+    }
+    return randomUUID();
+}
+function collectFiles(file) {
+    return (file ?? [])
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}
+export function dedupeByPath(files) {
+    const seen = new Set();
+    return files.filter((file) => {
+        if (seen.has(file.path))
+            return false;
+        seen.add(file.path);
+        return true;
+    });
+}
+export function normalizeRepoPath(root, rawPath) {
+    const repoRelative = relative(root, resolve(process.cwd(), rawPath))
+        .split(sep)
+        .join("/");
+    if (repoRelative === "" ||
+        repoRelative === ".." ||
+        repoRelative.startsWith("../")) {
+        throw new Error(`--file '${rawPath}' is outside the repository.`);
+    }
+    return repoRelative;
+}
+function requireFlag(value, flag) {
+    if (!value) {
+        throw new Error(`Missing required option ${flag}.`);
+    }
+    return value;
+}
+// Mirrors z.email() in @gatebolt/validators; keep in sync by hand (the CLI
+// takes no dependency on the validators package).
+const SERVER_EMAIL = /^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+.-]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$/;
+export function isValidEmail(value) {
+    return SERVER_EMAIL.test(value);
+}

package/dist/commands/observe.js

@@ -0,0 +1,100 @@
+import { parseArgs } from "node:util";
+import { resolveConnection } from "../config.js";
+import { OBSERVED_FILES_MAX } from "../contracts.js";
+import { observedFilesFromGit } from "../diff.js";
+import { commitExists, diffNameStatus, diffNumstat, isReconcilableBase, listUntracked, repoContext, } from "../git.js";
+import { isRecord } from "../json.js";
+import { profileLoader } from "../profiles.js";
+import { clearPendingDeclare, clearSession, readSession } from "../session.js";
+import { postChange } from "../transport.js";
+function resolveTarget(values, session) {
+    const provided = values["change-id"];
+    if (provided !== undefined && !isUuid(provided)) {
+        throw new Error(`Invalid --change-id '${provided}'. Expected a UUID.`);
+    }
+    const changeId = provided ?? session?.changeId;
+    const observingSessionChange = !values["change-id"] || values["change-id"] === session?.changeId;
+    const base = values.base ?? (observingSessionChange ? session?.baseSha : undefined);
+    if (!changeId) {
+        throw new Error("No active declaration. Run `gatebolt declare` first, or pass --change-id.");
+    }
+    if (!base) {
+        throw new Error("No base commit for this change. Pass --base (the commit it was declared against).");
+    }
+    return { changeId, base, observingSessionChange };
+}
+export async function runObserve(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            key: { type: "string" },
+            url: { type: "string" },
+            profile: { type: "string" },
+            "change-id": { type: "string" },
+            base: { type: "string" },
+        },
+    });
+    const repo = await repoContext();
+    if (!repo) {
+        throw new Error("Not inside a git repository.");
+    }
+    const dir = repo.gitDir;
+    const loadProfile = profileLoader({ name: values.profile, root: repo.root });
+    const connection = await resolveConnection({ key: values.key, url: values.url }, loadProfile);
+    const session = await readSession(dir);
+    const { changeId, base, observingSessionChange } = resolveTarget(values, session);
+    if (!(await commitExists(base))) {
+        throw new Error(`Base commit ${base} no longer exists. Re-run \`gatebolt declare\`.`);
+    }
+    const declaredBranch = observingSessionChange ? session?.branch : undefined;
+    if (!(await isReconcilableBase(base, declaredBranch))) {
+        throw new Error("The working tree has moved off the declared base (branch switch or divergent rebase?). Re-run `gatebolt declare`.");
+    }
+    const [nameStatus, numstat, untracked] = await Promise.all([
+        diffNameStatus(base),
+        diffNumstat(base),
+        listUntracked(),
+    ]);
+    const observedFiles = observedFilesFromGit(nameStatus, numstat, untracked);
+    if (observedFiles.length > OBSERVED_FILES_MAX) {
+        throw new Error(`Diff touches ${observedFiles.length} files, over the ${OBSERVED_FILES_MAX} limit. Narrow the change.`);
+    }
+    const input = { changeId, observedFiles };
+    const result = await postChange(connection, "change.observe", input);
+    if (!isReconciliation(result)) {
+        throw new Error("Unexpected response from server.");
+    }
+    printVerdict(result);
+    if (observingSessionChange) {
+        await clearSession(dir);
+        await clearPendingDeclare(dir);
+    }
+}
+// Mirrors z.uuid() in @gatebolt/validators; keep in sync by hand (the CLI
+// takes no dependency on the validators package).
+const SERVER_UUID = /^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/;
+export function isUuid(value) {
+    return SERVER_UUID.test(value);
+}
+export function isReconciliation(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.changeId === "string" &&
+        typeof value.driftScore === "number" &&
+        typeof value.driftLevel === "string" &&
+        Array.isArray(value.matched) &&
+        Array.isArray(value.unexpected) &&
+        Array.isArray(value.missing) &&
+        Array.isArray(value.reasons));
+}
+function printVerdict(result) {
+    const lines = [
+        `Change  ${result.changeId}`,
+        `Drift   ${result.driftLevel} (${result.driftScore})`,
+        `Files   ${result.matched.length} matched, ${result.unexpected.length} unexpected, ${result.missing.length} missing`,
+    ];
+    for (const reason of result.reasons) {
+        lines.push(`  ${reason}`);
+    }
+    process.stdout.write(`${lines.join("\n")}\n`);
+}

package/dist/config.js

@@ -0,0 +1,32 @@
+export const DEFAULT_BASE_URL = "https://gatebolt.com";
+export async function resolveConnection(flags, loadProfile) {
+    const key = flags.key ?? process.env.GBOLT_KEY;
+    const url = flags.url ?? process.env.GBOLT_URL;
+    const profile = key && url ? null : await loadProfile();
+    const resolvedKey = key ?? profile?.key;
+    const baseUrl = (url ?? profile?.url ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (!resolvedKey) {
+        throw new Error("Missing API key. Set GBOLT_KEY, pass --key, or run `gatebolt configure`.");
+    }
+    return { key: resolvedKey, baseUrl };
+}
+export async function resolveRepoSlug(flags, loadProfile) {
+    const raw = flags.repo ?? process.env.GBOLT_REPO ?? (await loadProfile())?.repo;
+    if (!raw) {
+        throw new Error("Missing repository slug. Set GBOLT_REPO, pass --repo, or run `gatebolt configure`.");
+    }
+    return slugifyRepo(raw);
+}
+const SLUG_MAX_LENGTH = 48;
+export function slugifyRepo(value) {
+    const slug = value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, SLUG_MAX_LENGTH)
+        .replace(/^-+|-+$/g, "");
+    if (!slug) {
+        throw new Error(`Could not derive a repository slug from "${value}".`);
+    }
+    return slug;
+}

package/dist/contracts.js

@@ -0,0 +1,14 @@
+export const OBSERVED_FILES_MAX = 2000;
+export const DECLARED_FILES_MAX = 500;
+export const TASK_MAX_LENGTH = 2000;
+export const AGENT_VENDORS = [
+    "claude_code",
+    "cursor",
+    "copilot",
+    "codex",
+    "devin",
+    "other",
+];
+export function isAgentVendor(value) {
+    return AGENT_VENDORS.includes(value);
+}

package/dist/diff.js

@@ -0,0 +1,98 @@
+export function observedFilesFromGit(nameStatusOutput, numstatOutput, untrackedOutput) {
+    const counts = parseNumstat(numstatOutput);
+    const observed = parseNameStatus(nameStatusOutput).map((entry) => {
+        const file = { path: entry.path, action: entry.action };
+        const line = counts.get(entry.path);
+        if (line) {
+            file.additions = line.additions;
+            file.deletions = line.deletions;
+        }
+        return file;
+    });
+    // A path can appear in both lists — `git rm --cached` leaves a staged deletion
+    // in the diff while the on-disk file shows as untracked; prefer the diff entry.
+    const seen = new Set(observed.map((file) => file.path));
+    for (const path of splitFields(untrackedOutput)) {
+        if (seen.has(path))
+            continue;
+        observed.push({ path, action: "added" });
+    }
+    return observed;
+}
+function parseNameStatus(output) {
+    const reader = createReader(splitFields(output));
+    const entries = [];
+    while (!reader.done()) {
+        const status = reader.take();
+        const code = status.charAt(0);
+        if (code === "R") {
+            const from = reader.take();
+            const to = reader.take();
+            entries.push({ action: "deleted", path: from });
+            entries.push({ action: "renamed", path: to });
+            continue;
+        }
+        entries.push({ action: statusToAction(status), path: reader.take() });
+    }
+    return entries;
+}
+function parseNumstat(output) {
+    const reader = createReader(splitFields(output));
+    const counts = new Map();
+    while (!reader.done()) {
+        const head = reader.take();
+        const firstTab = head.indexOf("\t");
+        const secondTab = head.indexOf("\t", firstTab + 1);
+        if (firstTab < 0 || secondTab < 0) {
+            throw new Error(`malformed numstat record: ${head}`);
+        }
+        const additions = head.slice(0, firstTab);
+        const deletions = head.slice(firstTab + 1, secondTab);
+        let path = head.slice(secondTab + 1);
+        if (path === "") {
+            reader.take();
+            path = reader.take();
+        }
+        if (additions === "-")
+            continue;
+        counts.set(path, {
+            additions: Number(additions),
+            deletions: Number(deletions),
+        });
+    }
+    return counts;
+}
+function statusToAction(status) {
+    switch (status.charAt(0)) {
+        case "A":
+            return "added";
+        case "M":
+        case "T":
+            return "modified";
+        case "D":
+            return "deleted";
+        default:
+            throw new Error(`unsupported git status: ${status}`);
+    }
+}
+function splitFields(output) {
+    const fields = output.split("\0");
+    while (fields.length > 0 && fields[fields.length - 1] === "") {
+        fields.pop();
+    }
+    return fields;
+}
+function createReader(fields) {
+    let index = 0;
+    return {
+        done: () => index >= fields.length,
+        take: () => {
+            const value = fields[index];
+            if (value === undefined) {
+                throw new Error("unexpected end of git output");
+            }
+            index += 1;
+            return value;
+        },
+    };
+}

package/dist/git.js

@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const MAX_GIT_OUTPUT_BYTES = 67_108_864;
+async function git(args) {
+    const { stdout } = await run("git", args, {
+        maxBuffer: MAX_GIT_OUTPUT_BYTES,
+    });
+    return stdout;
+}
+export async function repoContext() {
+    let output;
+    try {
+        output = await git([
+            "rev-parse",
+            "--is-inside-work-tree",
+            "--show-toplevel",
+            "--git-dir",
+        ]);
+    }
+    catch (error) {
+        if (gitExitedNonZero(error))
+            return null;
+        throw gitFailure(error);
+    }
+    const [inside, root, dir] = output.split("\n").map((line) => line.trim());
+    if (inside !== "true" || !root || !dir)
+        return null;
+    return { gitDir: dir, root };
+}
+export async function currentHead() {
+    const output = await git(["rev-parse", "HEAD"]);
+    return output.trim();
+}
+export async function commitExists(rev) {
+    try {
+        await git(["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]);
+        return true;
+    }
+    catch (error) {
+        if (gitExitedNonZero(error))
+            return false;
+        throw gitFailure(error);
+    }
+}
+export function hasCommits() {
+    return commitExists("HEAD");
+}
+export async function currentBranch() {
+    // `git branch --show-current` needs Git 2.22+; symbolic-ref is portable.
+    try {
+        const output = await git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+        return output.trim();
+    }
+    catch (error) {
+        if (gitExitedNonZero(error))
+            return "";
+        throw gitFailure(error);
+    }
+}
+export async function isAncestor(rev) {
+    try {
+        await git(["merge-base", "--is-ancestor", rev, "HEAD"]);
+        return true;
+    }
+    catch (error) {
+        if (gitExitedNonZero(error))
+            return false;
+        throw gitFailure(error);
+    }
+}
+async function parentOf(rev) {
+    try {
+        const output = await git(["rev-parse", "--verify", "--quiet", `${rev}^`]);
+        return output.trim() || null;
+    }
+    catch (error) {
+        if (gitExitedNonZero(error))
+            return null;
+        throw gitFailure(error);
+    }
+}
+export async function isReconcilableBase(base, declaredBranch) {
+    if (await isAncestor(base))
+        return true;
+    // An in-place amend/squash shares HEAD's parent — but so does a sibling branch
+    // cut from that parent, and only the amend is safe to diff. Require the branch
+    // to distinguish them.
+    if (!declaredBranch || (await currentBranch()) !== declaredBranch) {
+        return false;
+    }
+    const [baseParent, headParent] = await Promise.all([
+        parentOf(base),
+        parentOf("HEAD"),
+    ]);
+    return baseParent !== null && baseParent === headParent;
+}
+export function diffNameStatus(base) {
+    return git(["diff", "--name-status", "-M", "-z", base]);
+}
+export function diffNumstat(base) {
+    return git(["diff", "--numstat", "-M", "-z", base]);
+}
+export function listUntracked() {
+    return git(["ls-files", "--others", "--exclude-standard", "-z"]);
+}
+function errorCode(error) {
+    return error instanceof Error
+        ? error.code
+        : undefined;
+}
+function gitExitedNonZero(error) {
+    return typeof errorCode(error) === "number";
+}
+function gitFailure(error) {
+    if (errorCode(error) === "ENOENT") {
+        return new Error("Could not run git — is it installed and on your PATH?");
+    }
+    return error instanceof Error ? error : new Error("Could not run git.");
+}

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { runConfigure } from "./commands/configure.js";
+import { runDeclare } from "./commands/declare.js";
+import { runObserve } from "./commands/observe.js";
+import { RequestError } from "./transport.js";
+const STATUS_BAD_REQUEST = 400;
+const STATUS_UNAUTHORIZED = 401;
+const STATUS_FORBIDDEN = 403;
+const STATUS_NOT_FOUND = 404;
+const STATUS_CONFLICT = 409;
+const STATUS_RATE_LIMITED = 429;
+async function main() {
+    const [, , command = "", ...argv] = process.argv;
+    try {
+        switch (command) {
+            case "declare":
+                await runDeclare(argv);
+                break;
+            case "observe":
+                await runObserve(argv);
+                break;
+            case "configure":
+                await runConfigure(argv);
+                break;
+            default:
+                process.stderr.write("Usage: gatebolt <declare|observe|configure> [options]\n");
+                process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        process.stderr.write(`${formatError(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+function formatError(error) {
+    if (error instanceof RequestError) {
+        return messageForStatus(error);
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return "Unexpected error.";
+}
+function messageForStatus(error) {
+    switch (error.status) {
+        case STATUS_BAD_REQUEST:
+            return "Invalid request — check the declared values and try again.";
+        case STATUS_UNAUTHORIZED:
+            return "Unauthorized — the API key is invalid or has hit its rate limit.";
+        case STATUS_FORBIDDEN:
+            return "Forbidden — the repository slug does not match this API key.";
+        case STATUS_NOT_FOUND:
+            return "Not found — no matching change for this key and repository.";
+        case STATUS_CONFLICT:
+            return "Conflict — this change was already observed with different files.";
+        case STATUS_RATE_LIMITED:
+            return "Rate limited — try again later.";
+        default:
+            return error.message;
+    }
+}
+void main();

package/dist/json.js

@@ -0,0 +1,3 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/profiles.js

@@ -0,0 +1,128 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isRecord } from "./json.js";
+const POINTER_FILE = ".gatebolt";
+const CONFIG_FILE_MODE = 0o600;
+function configPath() {
+    return (nonEmpty(process.env.GATEBOLT_CONFIG) ??
+        join(homedir(), ".gatebolt", "config.json"));
+}
+export function parseConfig(raw) {
+    if (!isRecord(raw) || !isRecord(raw.profiles)) {
+        return null;
+    }
+    const profiles = {};
+    for (const [name, value] of Object.entries(raw.profiles)) {
+        const profile = parseProfile(value);
+        if (!profile)
+            return null;
+        profiles[name] = profile;
+    }
+    const config = { profiles };
+    if (typeof raw.default === "string") {
+        config.default = raw.default;
+    }
+    return config;
+}
+function parseProfile(value) {
+    if (!isRecord(value))
+        return null;
+    const { url, repo, key } = value;
+    if (typeof repo !== "string" || typeof key !== "string") {
+        return null;
+    }
+    if (url !== undefined && typeof url !== "string") {
+        return null;
+    }
+    return url === undefined ? { repo, key } : { url, repo, key };
+}
+export function selectProfileName(config, inputs) {
+    const explicit = nonEmpty(inputs.name) ?? nonEmpty(inputs.env) ?? nonEmpty(inputs.pointer);
+    if (explicit)
+        return explicit;
+    const names = Object.keys(config.profiles);
+    if (names.length === 1)
+        return names[0] ?? null;
+    return config.default ?? null;
+}
+export async function resolveProfile(opts) {
+    const config = await loadConfig();
+    if (!config)
+        return null;
+    const explicit = nonEmpty(opts.name) ?? nonEmpty(process.env.GATEBOLT_PROFILE);
+    const pointer = await readPointer(opts.root);
+    const name = selectProfileName(config, {
+        name: opts.name,
+        env: process.env.GATEBOLT_PROFILE,
+        pointer,
+    });
+    if (!name)
+        return null;
+    const profile = config.profiles[name];
+    if (profile)
+        return profile;
+    if (!explicit && name === pointer)
+        return null;
+    throw new Error(`Profile "${name}" is not in ${configPath()}. Run \`gatebolt configure --profile ${name}\`.`);
+}
+export function profileLoader(opts) {
+    let cached;
+    return () => (cached ??= resolveProfile(opts));
+}
+export async function readConfigForWrite() {
+    const config = await loadConfig();
+    if (config)
+        return config;
+    return { profiles: {} };
+}
+export async function writeConfig(config) {
+    const path = configPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(config, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: CONFIG_FILE_MODE,
+    });
+    await chmod(path, CONFIG_FILE_MODE);
+    return path;
+}
+async function loadConfig() {
+    let raw;
+    try {
+        raw = await readFile(configPath(), "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+    const config = parseConfig(safeJsonParse(raw));
+    if (!config) {
+        throw new Error(`${configPath()} is malformed. Fix or remove it, then retry.`);
+    }
+    return config;
+}
+async function readPointer(root) {
+    try {
+        return nonEmpty((await readFile(join(root, POINTER_FILE), "utf8")).trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeJsonParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function nonEmpty(value) {
+    if (!value)
+        return undefined;
+    return value;
+}
+function isNotFound(error) {
+    return isRecord(error) && error.code === "ENOENT";
+}

package/dist/session.js

@@ -0,0 +1,50 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isRecord } from "./json.js";
+const SESSION_FILE = "session.json";
+const PENDING_FILE = "pending-declare.json";
+function sessionDir(gitDir) {
+    return join(gitDir, "gatebolt");
+}
+async function writeJson(gitDir, file, data) {
+    await mkdir(sessionDir(gitDir), { recursive: true });
+    await writeFile(join(sessionDir(gitDir), file), JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+async function readJson(gitDir, file, parse) {
+    try {
+        const data = JSON.parse(await readFile(join(sessionDir(gitDir), file), "utf8"));
+        return isRecord(data) ? parse(data) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function clearJson(gitDir, file) {
+    return rm(join(sessionDir(gitDir), file), { force: true });
+}
+export function writeSession(gitDir, session) {
+    return writeJson(gitDir, SESSION_FILE, session);
+}
+export function readSession(gitDir) {
+    return readJson(gitDir, SESSION_FILE, ({ changeId, baseSha, branch }) => typeof changeId === "string" && typeof baseSha === "string"
+        ? {
+            changeId,
+            baseSha,
+            branch: typeof branch === "string" ? branch : undefined,
+        }
+        : null);
+}
+export function clearSession(gitDir) {
+    return clearJson(gitDir, SESSION_FILE);
+}
+export function writePendingDeclare(gitDir, pending) {
+    return writeJson(gitDir, PENDING_FILE, pending);
+}
+export function readPendingDeclare(gitDir) {
+    return readJson(gitDir, PENDING_FILE, ({ correlationId, intentKey }) => typeof correlationId === "string" && typeof intentKey === "string"
+        ? { correlationId, intentKey }
+        : null);
+}
+export function clearPendingDeclare(gitDir) {
+    return clearJson(gitDir, PENDING_FILE);
+}

package/dist/transport.js

@@ -0,0 +1,72 @@
+import { isRecord } from "./json.js";
+const REQUEST_TIMEOUT_MS = 30_000;
+export class RequestError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "RequestError";
+    }
+}
+export async function postChange(connection, procedure, input) {
+    let response;
+    try {
+        response = await fetch(`${connection.baseUrl}/api/trpc/${procedure}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${connection.key}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ json: input }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw connectionError(connection.baseUrl, error);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError)) {
+            throw connectionError(connection.baseUrl, error);
+        }
+        body = null;
+    }
+    if (!response.ok) {
+        throw toRequestError(response.status, body);
+    }
+    return extractResult(body);
+}
+function connectionError(baseUrl, error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+        return new RequestError(`Timed out waiting for ${baseUrl}.`, 0, "TIMEOUT");
+    }
+    return new RequestError(`Could not reach ${baseUrl}.`, 0, "NETWORK");
+}
+function toRequestError(status, body) {
+    const parsed = parseTrpcError(body);
+    return new RequestError(parsed?.message ?? `Request failed with status ${status}.`, status, parsed?.code ?? "UNKNOWN");
+}
+export function extractResult(body) {
+    const result = isRecord(body) ? body.result : undefined;
+    const data = isRecord(result) ? result.data : undefined;
+    if (isRecord(data) && data.json !== undefined) {
+        return data.json;
+    }
+    throw new RequestError("Unexpected response from server.", 0, "MALFORMED");
+}
+function parseTrpcError(body) {
+    const error = isRecord(body) ? body.error : undefined;
+    const json = isRecord(error) ? error.json : undefined;
+    if (!isRecord(json))
+        return null;
+    const data = json.data;
+    return {
+        message: typeof json.message === "string" ? json.message : undefined,
+        code: isRecord(data) && typeof data.code === "string" ? data.code : undefined,
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@gatebolt/cli",
+  "version": "0.2.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",
+    "ai-agents",
+    "provenance",
+    "audit",
+    "reconciliation",
+    "claude-code",
+    "git",
+    "cli"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gatebolt/gatebolt-cli.git"
+  },
+  "type": "module",
+  "bin": {
+    "gatebolt": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "recipes"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:it": "vitest run --config vitest.it.config.ts"
+  }
+}

package/recipes/claude-code/README.md

@@ -0,0 +1,64 @@
+# GateBolt × Claude Code — declare → observe recipe
+
+Files you copy into the repo your agent works in so a Claude Code session runs
+the GateBolt loop on its own: the agent **declares** the files it plans to touch
+before editing, and each turn's diff is **observed** and reconciled when the turn
+ends. Drives the [`gatebolt` CLI](../../README.md) — read that for what `declare`
+and `observe` do.
+
+## What's in here
+
+| File                        | Copies to                      | Role                                                |
+| --------------------------- | ------------------------------ | --------------------------------------------------- |
+| `settings.json`             | `<repo>/.claude/settings.json` | Wires the `PreToolUse` guard + `Stop` observe hook  |
+| `hooks/gatebolt-guard.sh`   | `<repo>/.claude/hooks/`        | Strict mode: deny `Edit`/`Write` until declared     |
+| `hooks/gatebolt-observe.sh` | `<repo>/.claude/hooks/`        | `Stop`: run `gatebolt observe` when a turn ends     |
+| `hooks/pre-push`            | `<repo>/.git/hooks/pre-push`   | Backstop: refuse to push an un-observed declaration |
+
+Merge the `hooks` block if the repo already has a `.claude/settings.json`.
+
+## Setup
+
+```sh
+# 1. Copy the recipe in.
+cp hooks/gatebolt-*.sh <repo>/.claude/hooks/
+cp settings.json       <repo>/.claude/settings.json
+cp hooks/pre-push      <repo>/.git/hooks/pre-push
+chmod +x <repo>/.claude/hooks/gatebolt-*.sh <repo>/.git/hooks/pre-push
+
+# 2. Save a GateBolt profile for this repo once — paste the key when prompted.
+#    The hooks call `gatebolt` with no flags; the profile is resolved automatically.
+npx @gatebolt/cli configure --profile <repo-slug> \
+  --url https://your-gatebolt.app --repo <repo-slug>
+
+# 3. Launch Claude Code.
+export GATEBOLT_ENFORCE="strict"           # or omit for lenient
+export GATEBOLT_CLI="npx @gatebolt/cli"    # optional — omit if `gatebolt` is on PATH
+cd <repo> && claude
+```
+
+**Prereqs:** `git`, `jq`, and the [`@gatebolt/cli`](../../README.md) client
+(`npm i -g @gatebolt/cli`). `GATEBOLT_CLI` is a command _prefix_ the hooks append
+to, defaulting to `gatebolt`; set it to `npx @gatebolt/cli` if you didn't install
+globally.
+
+## The two modes (`GATEBOLT_ENFORCE`)
+
+- **`strict`** — the guard **denies** every `Edit`/`Write` until a declaration
+  exists (holds even under `--dangerously-skip-permissions`) and tells the agent
+  to run `gatebolt declare` first. That `Bash` call isn't blocked, so the agent
+  declares, then edits go through.
+- **`lenient`** (default) — no block; declaring is an instructed step (e.g. a
+  line in the repo's `CLAUDE.md`). The pre-push backstop guarantees nothing lands
+  undeclared.
+
+## Notes and limits
+
+- **One turn ≈ one change.** `Stop` fires every turn, so `observe` reconciles and
+  clears the session each turn; strict mode re-declares next turn.
+- **Rate limit.** Two API calls per change, and the default key limit is low
+  (10/day today, surfacing as `401` when hit). Use a fresh key when iterating.
+- **Backstop is v1.** Catches only an open, un-observed declaration (the
+  Esc-interrupt case), not work that was never declared — a follow-up.
+- **Watch over-broad declarations.** Declaring `src/**` to dodge the block kills
+  the drift signal, like an empty declaration. The deny asks for specific paths.

package/recipes/claude-code/hooks/gatebolt-guard.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# GateBolt strict-mode PreToolUse guard — blocks Edit/Write until a declaration
+# exists for this change. Opt-in via GATEBOLT_ENFORCE=strict.
+set -u
+
+# Drain stdin so the hook's pipe doesn't block; we don't need the payload.
+cat >/dev/null
+
+[ "${GATEBOLT_ENFORCE:-lenient}" = "strict" ] || exit 0
+
+project_dir="${CLAUDE_PROJECT_DIR:-$PWD}"
+git_dir=$(git -C "$project_dir" rev-parse --git-dir 2>/dev/null) || exit 0
+case "$git_dir" in
+  /*) ;;
+  *) git_dir="$project_dir/$git_dir" ;;
+esac
+
+# session.json exists = already declared → allow the edit.
+[ -f "$git_dir/gatebolt/session.json" ] && exit 0
+
+cli="${GATEBOLT_CLI:-gatebolt}"
+reason="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> ...]
+
+GBOLT_KEY, GBOLT_URL and GBOLT_REPO are already set in your environment. Once it
+prints \"Declared change …\", retry the edit."
+
+# JSON deny holds even under --dangerously-skip-permissions; without jq we fall
+# back to exit-2, which re-prompts but isn't guaranteed under bypass.
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg r "$reason" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $r
+    }
+  }'
+  exit 0
+fi
+
+printf '%s\n' "$reason" >&2
+exit 2

package/recipes/claude-code/hooks/gatebolt-observe.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# GateBolt Stop hook — runs `gatebolt observe` to reconcile the diff when a turn
+# ends. Advisory; never blocks the turn.
+set -u
+
+# Drain stdin; observe reads its target from the session file.
+cat >/dev/null
+
+cd "${CLAUDE_PROJECT_DIR:-$PWD}" || exit 0
+
+git_dir=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+case "$git_dir" in
+  /*) ;;
+  *) git_dir="$PWD/$git_dir" ;;
+esac
+
+# Stop fires every turn; only reconcile when a declaration is actually open.
+[ -f "$git_dir/gatebolt/session.json" ] || exit 0
+
+cli="${GATEBOLT_CLI:-gatebolt}"
+# GATEBOLT_CLI is a command prefix; word-splitting is intentional.
+# shellcheck disable=SC2086
+$cli observe 2>&1 || true
+exit 0

package/recipes/claude-code/hooks/pre-push

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# GateBolt pre-push backstop — refuses to push while a declaration is still open
+# but un-observed (the Esc-interrupt case Stop misses). Needs gatebolt's env
+# (GBOLT_KEY / GBOLT_URL / GATEBOLT_CLI) exported in the shell you push from.
+set -u
+
+git_dir=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+case "$git_dir" in
+  /*) ;;
+  *) git_dir="$PWD/$git_dir" ;;
+esac
+
+[ -f "$git_dir/gatebolt/session.json" ] || exit 0
+
+cli="${GATEBOLT_CLI:-gatebolt}"
+echo "GateBolt: an un-observed declaration is still open; reconciling before push…" >&2
+# shellcheck disable=SC2086
+if ! $cli observe >&2; then
+  echo "GateBolt: observe failed — refusing to push unreconciled work." >&2
+  echo "Resolve the error above (or run '$cli observe' yourself), then push again." >&2
+  exit 1
+fi
+exit 0

package/recipes/claude-code/settings.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/gatebolt-guard.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/gatebolt-observe.sh"
+          }
+        ]
+      }
+    ]
+  }
+}