@gatebolt/cli 0.3.1 → 0.5.0

package/dist/profiles.js

@@ -1,8 +1,9 @@
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { isUuid } from "./contracts.js";
 import { isRecord } from "./json.js";
-const POINTER_FILE = ".gatebolt";
+export const REPO_LINK_FILE = ".gatebolt";
 const CONFIG_FILE_MODE = 0o600;
 function configPath() {
     return (nonEmpty(process.env.GATEBOLT_CONFIG) ??
@@ -28,14 +29,15 @@ export function parseConfig(raw) {
 function parseProfile(value) {
     if (!isRecord(value))
         return null;
-    const { url, repo, key } = value;
-    if (typeof repo !== "string" || typeof key !== "string") {
+    const { url, key } = value;
+    if (typeof key !== "string")
         return null;
-    }
-    if (url !== undefined && typeof url !== "string") {
+    if (url !== undefined && typeof url !== "string")
         return null;
-    }
-    return url === undefined ? { repo, key } : { url, repo, key };
+    const profile = { key };
+    if (url !== undefined)
+        profile.url = url;
+    return profile;
 }
 export function selectProfileName(config, inputs) {
     const explicit = nonEmpty(inputs.name) ?? nonEmpty(inputs.env) ?? nonEmpty(inputs.pointer);
@@ -51,21 +53,25 @@ export async function resolveProfile(opts) {
     if (!config)
         return null;
     const explicit = nonEmpty(opts.name) ?? nonEmpty(process.env.GATEBOLT_PROFILE);
-    const pointer = await readPointer(opts.root);
+    const pointer = await readLinkedProfile(opts.root);
+    const preference = configured(config, nonEmpty(opts.preferred)) ?? pointer;
     const name = selectProfileName(config, {
         name: opts.name,
         env: process.env.GATEBOLT_PROFILE,
-        pointer,
+        pointer: preference,
     });
     if (!name)
         return null;
     const profile = config.profiles[name];
     if (profile)
-        return profile;
-    if (!explicit && name === pointer)
+        return { name, ...profile };
+    if (!explicit && name === preference)
         return null;
     throw new Error(`Profile "${name}" is not in ${configPath()}. Run \`gatebolt configure --profile ${name}\`.`);
 }
+function configured(config, name) {
+    return name && config.profiles[name] ? name : undefined;
+}
 export function profileLoader(opts) {
     let cached;
     return () => (cached ??= resolveProfile(opts));
@@ -102,14 +108,43 @@ async function loadConfig() {
     }
     return config;
 }
-async function readPointer(root) {
+async function readLinkedProfile(root) {
     try {
-        return nonEmpty((await readFile(join(root, POINTER_FILE), "utf8")).trim());
+        const link = await readRepoLink(root);
+        return link?.profile;
     }
     catch {
         return undefined;
     }
 }
+export async function readRepoLink(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, REPO_LINK_FILE), "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+    const data = safeJsonParse(raw);
+    if (!isRecord(data) ||
+        typeof data.repositoryId !== "string" ||
+        !isUuid(data.repositoryId)) {
+        throw new Error(`${join(root, REPO_LINK_FILE)} is malformed — it should hold {"repositoryId": "<uuid>"}. ` +
+            "Run `gatebolt link` from the repo root to rewrite it, then commit it.");
+    }
+    const link = { repositoryId: data.repositoryId };
+    if (typeof data.profile === "string") {
+        link.profile = data.profile;
+    }
+    return link;
+}
+export async function writeRepoLink(root, link) {
+    const path = join(root, REPO_LINK_FILE);
+    await writeFile(path, JSON.stringify(link, null, 2) + "\n", "utf8");
+    return path;
+}
 function safeJsonParse(raw) {
     try {
         return JSON.parse(raw);

package/dist/rest.js

@@ -0,0 +1,49 @@
+const AUTH_BASE_PATH = "/api/auth";
+const REQUEST_TIMEOUT_MS = 30_000;
+export async function authFetch(baseUrl, path, request) {
+    let response;
+    try {
+        response = await fetch(buildUrl(baseUrl, path, request.query), {
+            method: request.method,
+            headers: buildHeaders(request),
+            body: request.body === undefined ? undefined : JSON.stringify(request.body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw connectionError(baseUrl, error);
+    }
+    return { status: response.status, json: await readJson(response) };
+}
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(`${baseUrl}${AUTH_BASE_PATH}${path}`);
+    for (const [name, value] of Object.entries(query ?? {})) {
+        url.searchParams.set(name, value);
+    }
+    return url.toString();
+}
+function buildHeaders(request) {
+    const headers = {};
+    if (request.body !== undefined)
+        headers["content-type"] = "application/json";
+    if (request.token)
+        headers.authorization = `Bearer ${request.token}`;
+    return headers;
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function connectionError(baseUrl, error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+        return new Error(`Timed out waiting for ${baseUrl}.`);
+    }
+    return new Error(`Could not reach ${baseUrl}.`);
+}

package/dist/session.js

@@ -26,11 +26,12 @@ 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"
+    return readJson(gitDir, SESSION_FILE, ({ changeId, baseSha, branch, profile }) => typeof changeId === "string" && typeof baseSha === "string"
         ? {
             changeId,
             baseSha,
             branch: typeof branch === "string" ? branch : undefined,
+            profile: typeof profile === "string" ? profile : undefined,
         }
         : null);
 }

package/dist/transport.js

@@ -3,11 +3,15 @@ const REQUEST_TIMEOUT_MS = 30_000;
 export class RequestError extends Error {
     status;
     code;
-    constructor(message, status, code) {
+    procedure;
+    fieldErrors;
+    constructor(message, status, code, details) {
         super(message);
         this.status = status;
         this.code = code;
         this.name = "RequestError";
+        this.procedure = details.procedure;
+        this.fieldErrors = details.fieldErrors ?? [];
     }
 }
 export async function postChange(connection, procedure, input) {
@@ -24,7 +28,7 @@ export async function postChange(connection, procedure, input) {
         });
     }
     catch (error) {
-        throw connectionError(connection.baseUrl, error);
+        throw connectionError(connection.baseUrl, error, procedure);
     }
     let body;
     try {
@@ -32,32 +36,38 @@ export async function postChange(connection, procedure, input) {
     }
     catch (error) {
         if (!(error instanceof SyntaxError)) {
-            throw connectionError(connection.baseUrl, error);
+            throw connectionError(connection.baseUrl, error, procedure);
         }
         body = null;
     }
     if (!response.ok) {
-        throw toRequestError(response.status, body);
+        throw toRequestError(response.status, body, procedure);
     }
-    return extractResult(body);
+    return extractResult(body, procedure);
 }
-function connectionError(baseUrl, error) {
+function connectionError(baseUrl, error, procedure) {
     if (error instanceof Error && error.name === "TimeoutError") {
-        return new RequestError(`Timed out waiting for ${baseUrl}.`, 0, "TIMEOUT");
+        return new RequestError(`Timed out waiting for ${baseUrl}.`, 0, "TIMEOUT", {
+            procedure,
+        });
     }
-    return new RequestError(`Could not reach ${baseUrl}.`, 0, "NETWORK");
+    return new RequestError(`Could not reach ${baseUrl}.`, 0, "NETWORK", {
+        procedure,
+    });
 }
-function toRequestError(status, body) {
+function toRequestError(status, body, procedure) {
     const parsed = parseTrpcError(body);
-    return new RequestError(parsed?.message ?? `Request failed with status ${status}.`, status, parsed?.code ?? "UNKNOWN");
+    return new RequestError(parsed?.message ?? `Request failed with status ${status}.`, status, parsed?.code ?? "UNKNOWN", { procedure, fieldErrors: parsed?.fieldErrors ?? [] });
 }
-export function extractResult(body) {
+export function extractResult(body, procedure) {
     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");
+    throw new RequestError("Unexpected response from server.", 0, "MALFORMED", {
+        procedure,
+    });
 }
 function parseTrpcError(body) {
     const error = isRecord(body) ? body.error : undefined;
@@ -68,5 +78,15 @@ function parseTrpcError(body) {
     return {
         message: typeof json.message === "string" ? json.message : undefined,
         code: isRecord(data) && typeof data.code === "string" ? data.code : undefined,
+        fieldErrors: parseFieldErrors(data),
     };
 }
+function parseFieldErrors(data) {
+    const zodError = isRecord(data) ? data.zodError : undefined;
+    const fieldErrors = isRecord(zodError) ? zodError.fieldErrors : undefined;
+    if (!isRecord(fieldErrors))
+        return [];
+    return Object.values(fieldErrors)
+        .flat()
+        .filter((message) => typeof message === "string");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatebolt/cli",
-  "version": "0.3.1",
+  "version": "0.5.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",
@@ -22,8 +22,7 @@
     "gatebolt": "./dist/index.js"
   },
   "files": [
-    "dist",
-    "recipes"
+    "dist"
   ],
   "engines": {
     "node": ">=20"
@@ -40,6 +39,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"
   }
 }

package/recipes/claude-code/README.md

@@ -1,64 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-#!/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

@@ -1,24 +0,0 @@
-#!/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

@@ -1,23 +0,0 @@
-#!/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

@@ -1,25 +0,0 @@
-{
-  "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"
-          }
-        ]
-      }
-    ]
-  }
-}