@gatebolt/cli 0.3.1 → 0.4.0

package/README.md

@@ -16,11 +16,14 @@ npx @gatebolt/cli declare …
 
 Requires Node ≥ 20 and `git` on your `PATH`.
 
+`gatebolt --help` lists the commands and `gatebolt <command> --help` details one;
+`gatebolt --version` prints the version of the CLI itself.
+
 ## 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`):
+slug** to record the work against. Store them once as a named **profile** in
+`~/.gatebolt/config.json` (written owner-only, `0600`):
 
 ```
 gatebolt configure --profile payments-api \
@@ -60,7 +63,7 @@ to `<git-dir>/gatebolt/session.json`. The repository must have at least one comm
 | `--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                                                      |
+| `--agent-version <v>`   | no       | Agent/tool version (`--version` prints the CLI's own version)           |
 | `--launched-by <email>` | no       | Who launched the agent                                                  |
 | `--profile <name>`      | no       | Profile to resolve `key`/`url`/`repo` from                              |
 
@@ -101,7 +104,10 @@ gatebolt observe
 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
+would fold in unrelated work, so re-run `declare`. It never blocks on ambiguity, though: git
+records nothing that separates the agent's commits from a colleague's, so when commits have
+landed since `declare` — or a merge is in progress — `observe` **says so in a `Note` and
+reconciles anyway**, leaving you to judge whose work the diff contains. 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.
 

package/dist/commands/configure.js

@@ -1,5 +1,6 @@
 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";
@@ -33,11 +34,30 @@ function requireFlag(value, flag) {
     return value;
 }
 async function promptForKey() {
-    const rl = createInterface({ input: stdin, output: stdout });
+    let muted = false;
+    const output = new Writable({
+        write(chunk, encoding, done) {
+            if (!muted)
+                stdout.write(chunk, encoding);
+            done();
+        },
+    });
+    // `terminal` moves echoing from the tty to readline, which is what makes it
+    // suppressible; muting the stream alone leaves the tty echoing in canonical
+    // mode. Off a tty nothing echoes anyway, and leaving it off keeps readline's
+    // cursor escapes out of piped output.
+    const rl = createInterface({
+        input: stdin,
+        output,
+        terminal: stdin.isTTY === true,
+    });
     try {
-        return await rl.question("API key: ");
+        const answer = rl.question("API key: ");
+        muted = true;
+        return await answer;
     }
     finally {
         rl.close();
+        stdout.write("\n");
     }
 }

package/dist/commands/declare.js

@@ -20,7 +20,7 @@ export async function runDeclare(argv) {
             vendor: { type: "string" },
             name: { type: "string" },
             model: { type: "string" },
-            version: { type: "string" },
+            "agent-version": { type: "string" },
             "launched-by": { type: "string" },
             file: { type: "string", multiple: true },
         },
@@ -38,8 +38,9 @@ export async function runDeclare(argv) {
         name: requireFlag(values.name, "--name"),
         model: requireFlag(values.model, "--model"),
     };
-    if (values.version)
-        agent.version = values.version;
+    const agentVersion = values["agent-version"];
+    if (agentVersion)
+        agent.version = agentVersion;
     const launchedBy = values["launched-by"];
     if (launchedBy && !isValidEmail(launchedBy)) {
         throw new Error(`Invalid --launched-by '${launchedBy}'. Expected an email address.`);

package/dist/commands/observe.js

@@ -2,7 +2,7 @@ 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 { commitExists, commitsSinceBase, diffNameStatus, diffNumstat, isAncestor, isReconcilableBase, listUntracked, mergeInProgress, repoContext, } from "../git.js";
 import { isRecord } from "../json.js";
 import { profileLoader } from "../profiles.js";
 import { clearPendingDeclare, clearSession, readSession } from "../session.js";
@@ -50,7 +50,8 @@ export async function runObserve(argv) {
     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([
+    const [notes, nameStatus, numstat, untracked] = await Promise.all([
+        attributionNotes(base),
         diffNameStatus(base),
         diffNumstat(base),
         listUntracked(),
@@ -64,7 +65,7 @@ export async function runObserve(argv) {
     if (!isReconciliation(result)) {
         throw new Error("Unexpected response from server.");
     }
-    printVerdict(result);
+    printVerdict(result, notes);
     if (observingSessionChange) {
         await clearSession(dir);
         await clearPendingDeclare(dir);
@@ -87,7 +88,26 @@ export function isReconciliation(value) {
         Array.isArray(value.missing) &&
         Array.isArray(value.reasons));
 }
-function printVerdict(result) {
+// Never blocked on: observe is advisory, and only the person at the keyboard
+// knows whose commits these are.
+export async function attributionNotes(base) {
+    const notes = [];
+    if (await mergeInProgress()) {
+        notes.push("A merge is in progress; the diff includes the merged branch.");
+    }
+    // isReconcilableBase also accepts an in-place amend/squash, where base shares
+    // HEAD's parent but isn't its ancestor — and there base..HEAD would count the
+    // agent's own rewritten commit (the very work being reconciled) as foreign.
+    if (await isAncestor(base)) {
+        const commits = await commitsSinceBase(base);
+        if (commits > 0) {
+            const plural = commits === 1 ? "commit" : "commits";
+            notes.push(`${commits} ${plural} landed since declare; GateBolt cannot tell whose.`);
+        }
+    }
+    return notes;
+}
+function printVerdict(result, notes) {
     const lines = [
         `Change  ${result.changeId}`,
         `Drift   ${result.driftLevel} (${result.driftScore})`,
@@ -96,5 +116,11 @@ function printVerdict(result) {
     for (const reason of result.reasons) {
         lines.push(`  ${reason}`);
     }
+    for (const note of notes) {
+        lines.push(`Note    ${note}`);
+    }
+    if (notes.length > 0) {
+        lines.push("        Files above may include work from elsewhere.");
+    }
     process.stdout.write(`${lines.join("\n")}\n`);
 }

package/dist/diff.js

@@ -1,3 +1,4 @@
+const PARSER_BUG_HINT = "This is likely a GateBolt bug — please report it.";
 export function observedFilesFromGit(nameStatusOutput, numstatOutput, untrackedOutput) {
     const counts = parseNumstat(numstatOutput);
     const observed = parseNameStatus(nameStatusOutput).map((entry) => {
@@ -44,7 +45,7 @@ function parseNumstat(output) {
         const firstTab = head.indexOf("\t");
         const secondTab = head.indexOf("\t", firstTab + 1);
         if (firstTab < 0 || secondTab < 0) {
-            throw new Error(`malformed numstat record: ${head}`);
+            throw new Error(`Could not read the line counts in this repository's diff — git returned an unexpected record: "${head}". ${PARSER_BUG_HINT}`);
         }
         const additions = head.slice(0, firstTab);
         const deletions = head.slice(firstTab + 1, secondTab);
@@ -72,7 +73,7 @@ function statusToAction(status) {
         case "D":
             return "deleted";
         default:
-            throw new Error(`unsupported git status: ${status}`);
+            throw new Error(`Could not read this repository's diff — git reported the file status "${status}", which GateBolt does not recognise. ${PARSER_BUG_HINT}`);
     }
 }
 function splitFields(output) {
@@ -89,7 +90,7 @@ function createReader(fields) {
         take: () => {
             const value = fields[index];
             if (value === undefined) {
-                throw new Error("unexpected end of git output");
+                throw new Error(`Could not read this repository's diff — git's output ended sooner than expected. ${PARSER_BUG_HINT}`);
             }
             index += 1;
             return value;

package/dist/errors.js

@@ -0,0 +1,33 @@
+import { RequestError } from "./transport.js";
+const STATUS_BAD_REQUEST = 400;
+const STATUS_UNAUTHORIZED = 401;
+const STATUS_NOT_FOUND = 404;
+const STATUS_CONFLICT = 409;
+const STATUS_RATE_LIMITED = 429;
+export function formatError(error) {
+    if (error instanceof RequestError) {
+        return messageForStatus(error);
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return "Unexpected error.";
+}
+export function messageForStatus(error) {
+    switch (error.status) {
+        case STATUS_BAD_REQUEST:
+            return "Invalid request — check the declared values and try again.";
+        // The server collapses a missing/invalid key and a spent rate limit into one
+        // 401, so this cannot name which without guessing.
+        case STATUS_UNAUTHORIZED:
+            return "Unauthorized — the API key is invalid or has hit its rate limit.";
+        case STATUS_NOT_FOUND:
+            return "Not found — no change matches this API key. `observe` must use the same key that ran `declare`; if the key was rotated in between, re-run `gatebolt declare`.";
+        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;
+    }
+}

package/dist/git.js

@@ -85,7 +85,8 @@ export async function isReconcilableBase(base, declaredBranch) {
         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.
+    // to distinguish them. A same-branch reset onto a sibling still passes: it is
+    // shaped exactly like an amend, and git records nothing that separates them.
     if (!declaredBranch || (await currentBranch()) !== declaredBranch) {
         return false;
     }
@@ -95,6 +96,13 @@ export async function isReconcilableBase(base, declaredBranch) {
     ]);
     return baseParent !== null && baseParent === headParent;
 }
+export async function commitsSinceBase(base) {
+    const output = await git(["rev-list", "--count", `${base}..HEAD`]);
+    return Number(output.trim());
+}
+export function mergeInProgress() {
+    return commitExists("MERGE_HEAD");
+}
 export function diffNameStatus(base) {
     return git(["diff", "--name-status", "-M", "-z", base]);
 }

package/dist/help.js

@@ -0,0 +1,94 @@
+import { readFile } from "node:fs/promises";
+import { DEFAULT_BASE_URL } from "./config.js";
+import { AGENT_VENDORS } from "./contracts.js";
+import { isRecord } from "./json.js";
+export const USAGE = "Usage: gatebolt <declare|observe|configure> [options]";
+const ROOT_HELP = `gatebolt — the GateBolt agent client. An agent declares the files it intends to
+touch before it edits, then observes the actual diff when the work lands;
+GateBolt reconciles the two and scores the drift.
+
+${USAGE}
+
+Commands:
+  declare     Record the files the agent intends to touch, before it edits.
+  observe     Derive the diff from git and reconcile it against the declaration.
+  configure   Save a per-repo profile (url, repo, key) to ~/.gatebolt/config.json.
+
+Options:
+  -h, --help    Show this help, or the help of a command.
+  --version     Print the version of this CLI.
+
+Run \`gatebolt <command> --help\` for the options of a command.
+`;
+const DECLARE_HELP = `Usage: gatebolt declare --task <text> --vendor <vendor> --name <name>
+                        --model <id> --file <path> [--file <path> ...] [options]
+
+Records the files the agent intends to touch, before it edits. Snapshots the
+current commit as the base and writes the change id under <git-dir>/gatebolt/
+for \`gatebolt observe\` to pick up. The repository must have at least one commit.
+
+Required:
+  --task <text>           What the agent is doing.
+  --vendor <vendor>       One of: ${AGENT_VENDORS.join(", ")}.
+  --name <name>           Agent name, e.g. "Claude Code".
+  --model <id>            Agent model id.
+  --file <path>           A file the agent plans to touch. Repeat for each file.
+
+Options:
+  --agent-version <ver>   Version of the agent — not of this CLI.
+  --launched-by <email>   Email of the person who launched the agent.
+  --profile <name>        Profile to read url, repo and key from.
+  --key <key>             API key. Overrides the profile.
+  --url <url>             GateBolt URL. Overrides the profile.
+  --repo <slug>           Repo slug. Overrides the profile.
+  -h, --help              Show this help.
+`;
+const OBSERVE_HELP = `Usage: gatebolt observe [options]
+
+Derives the diff from git since the declared base commit and posts it to
+GateBolt, which reconciles it against the declaration and scores the drift.
+Observes the change recorded by \`gatebolt declare\` unless --change-id is given.
+
+Options:
+  --change-id <uuid>   Change to observe. Defaults to the declared change.
+  --base <commit>      Commit to diff against. Defaults to the declared base.
+  --profile <name>     Profile to read url and key from.
+  --key <key>          API key. Overrides the profile.
+  --url <url>          GateBolt URL. Overrides the profile.
+  -h, --help           Show this help.
+`;
+const CONFIGURE_HELP = `Usage: gatebolt configure --repo <slug> [options]
+
+Saves a profile to ~/.gatebolt/config.json, owner-readable only. Prompts for the
+API key unless --key is given; what you type is not echoed.
+
+Required:
+  --repo <slug>      Slug of the repo this agent works in, created on the first
+                     declare. Normalized to lowercase-hyphens.
+
+Options:
+  --profile <name>   Profile name. Defaults to the repo slug.
+  --url <url>        GateBolt URL. Defaults to ${DEFAULT_BASE_URL}.
+  --key <key>        API key. Skips the prompt, for scripting.
+  -h, --help         Show this help.
+
+Set GATEBOLT_CONFIG to keep the config somewhere other than the default path.
+`;
+const COMMAND_HELP = new Map([
+    ["declare", DECLARE_HELP],
+    ["observe", OBSERVE_HELP],
+    ["configure", CONFIGURE_HELP],
+]);
+export function isCommand(command) {
+    return COMMAND_HELP.has(command);
+}
+export function helpFor(command) {
+    return COMMAND_HELP.get(command) ?? ROOT_HELP;
+}
+export async function cliVersion() {
+    const raw = await readFile(new URL("../package.json", import.meta.url), "utf8");
+    const pkg = JSON.parse(raw);
+    return isRecord(pkg) && typeof pkg.version === "string"
+        ? pkg.version
+        : "unknown";
+}

package/dist/index.js

@@ -2,61 +2,48 @@
 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;
+import { formatError } from "./errors.js";
+import { cliVersion, helpFor, isCommand, USAGE } from "./help.js";
 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;
-        }
+        await dispatch(command, argv);
     }
     catch (error) {
         process.stderr.write(`${formatError(error)}\n`);
         process.exitCode = 1;
     }
 }
-function formatError(error) {
-    if (error instanceof RequestError) {
-        return messageForStatus(error);
+async function dispatch(command, argv) {
+    // The commands' parseArgs is strict, so it would reject these as unknown
+    // options: they have to be answered before argv reaches one.
+    if (wantsHelp(command, argv)) {
+        process.stdout.write(helpFor(command));
+        return;
     }
-    if (error instanceof Error) {
-        return error.message;
+    if (command === "--version") {
+        process.stdout.write(`${await cliVersion()}\n`);
+        return;
     }
-    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.";
+    switch (command) {
+        case "declare":
+            return runDeclare(argv);
+        case "observe":
+            return runObserve(argv);
+        case "configure":
+            return runConfigure(argv);
         default:
-            return error.message;
+            process.stderr.write(`${USAGE}\nRun \`gatebolt --help\` for details.\n`);
+            process.exitCode = 1;
+            return;
     }
 }
+function wantsHelp(command, argv) {
+    if (isHelpFlag(command))
+        return true;
+    return isCommand(command) && argv.some(isHelpFlag);
+}
+function isHelpFlag(arg) {
+    return arg === "--help" || arg === "-h";
+}
 void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatebolt/cli",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -40,6 +40,6 @@
     "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"
+    "test:it": "pnpm build && vitest run --config vitest.it.config.ts"
   }
 }