@gatebolt/cli 0.3.1 → 0.5.0

package/dist/commands/init.js

@@ -0,0 +1,221 @@
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { delimiter, dirname, isAbsolute, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { claudeCodeAdapter } from "../agents/claude-code.js";
+import { repoIdentityFromName, resolveConnection } from "../config.js";
+import { hooksPath, repoContext } from "../git.js";
+import { isRecord } from "../json.js";
+import { profileLoader, readRepoLink } from "../profiles.js";
+import { deriveIdentity, linkRepository } from "./link.js";
+const ADAPTERS = [claudeCodeAdapter];
+const ENFORCE_VALUES = ["lenient", "strict"];
+const PRE_PUSH_FILE = "pre-push";
+const PRE_PUSH_MARKER = "GateBolt pre-push backstop";
+const HOOK_MODE = 0o755;
+const ID_PREFIX_LEN = 8;
+const GITIGNORE_ENTRY = ".claude/settings.local.json";
+const NO_REMOTE = "GateBolt cannot derive this repository's identity from its `origin` remote. Re-run with --name <a-name-for-this-repo>.";
+const NO_KEY = "No GateBolt key found. Run `gatebolt login` (or `gatebolt configure`) first, then re-run `gatebolt init`.";
+const EPHEMERAL_CLI = "GateBolt is running from a temporary npx/dlx cache, so the hooks would break when the package manager prunes it. Install it durably first — `npm i -g @gatebolt/cli`, or add it as a project dependency so `gatebolt` is on PATH — then re-run `gatebolt init`. To link only, pass --no-hooks --no-pre-push.";
+export async function runInit(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            profile: { type: "string" },
+            name: { type: "string" },
+            enforce: { type: "string" },
+            "no-hooks": { type: "boolean" },
+            "no-pre-push": { type: "boolean" },
+            force: { type: "boolean" },
+        },
+    });
+    const enforce = parseEnforce(values.enforce);
+    const repo = await repoContext();
+    if (!repo) {
+        throw new Error("Not inside a git repository.");
+    }
+    const loadProfile = profileLoader({ name: values.profile, root: repo.root });
+    const connection = await connect(loadProfile);
+    const link = await ensureLink(connection, repo.root, values.name);
+    const linkOnly = Boolean(values["no-hooks"] && values["no-pre-push"]);
+    const command = linkOnly ? "" : resolveCommand(repo.root);
+    const wired = values["no-hooks"]
+        ? []
+        : await wireAgents(repo.root, command, enforce);
+    const prePush = values["no-pre-push"]
+        ? null
+        : await installPrePush(command, Boolean(values.force));
+    process.stdout.write(summary({
+        root: repo.root,
+        link,
+        wired,
+        prePush,
+        enforce: wired[0]?.result.enforce ?? enforce ?? "lenient",
+        noHooks: Boolean(values["no-hooks"]),
+    }));
+}
+export function parseEnforce(value) {
+    if (value === undefined)
+        return undefined;
+    if (ENFORCE_VALUES.includes(value)) {
+        return value;
+    }
+    throw new Error(`Invalid --enforce '${value}'. Expected one of: ${ENFORCE_VALUES.join(", ")}.`);
+}
+async function connect(loadProfile) {
+    try {
+        return await resolveConnection({}, loadProfile);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("Missing API key")) {
+            throw new Error(NO_KEY);
+        }
+        throw error;
+    }
+}
+async function ensureLink(connection, root, name) {
+    const existing = await readRepoLink(root);
+    if (existing) {
+        return { repositoryId: existing.repositoryId, existed: true };
+    }
+    const identity = name ? repoIdentityFromName(name) : await deriveIdentity();
+    if (!identity) {
+        throw new Error(NO_REMOTE);
+    }
+    const result = await linkRepository(connection, root, identity);
+    return {
+        repositoryId: result.repositoryId,
+        existed: false,
+        name: result.name,
+        slug: result.slug,
+        created: result.created,
+    };
+}
+function resolveCommand(root) {
+    const cli = fileURLToPath(new URL("../index.js", import.meta.url));
+    if (isEphemeralPath(cli)) {
+        throw new Error(EPHEMERAL_CLI);
+    }
+    if (onDurablePath("gatebolt", root))
+        return "gatebolt";
+    return `${quote(process.execPath)} ${quote(cli)}`;
+}
+// npx/dlx run from throwaway caches that get pruned, breaking any hook wired
+// here: npm marks them with an `_npx` segment, pnpm with `dlx`, yarn with `xfs-…`.
+export function isEphemeralPath(cliPath) {
+    return cliPath
+        .split(/[/\\]/)
+        .some((segment) => segment === "_npx" || segment === "dlx" || segment.startsWith("xfs-"));
+}
+export function onDurablePath(bin, root) {
+    const names = process.platform === "win32" ? [`${bin}.cmd`, `${bin}.exe`, bin] : [bin];
+    return (process.env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .filter((dir) => !isInsideRoot(dir, root))
+        .some((dir) => names.some((name) => existsSync(join(dir, name))));
+}
+function isInsideRoot(dir, root) {
+    const rel = relative(root, dir);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function quote(value) {
+    return /\s/.test(value) ? `"${value}"` : value;
+}
+async function wireAgents(root, command, enforce) {
+    const wired = [];
+    for (const adapter of ADAPTERS) {
+        const result = await adapter.wire(root, { command, enforce });
+        wired.push({ displayName: adapter.displayName, result });
+    }
+    return wired;
+}
+async function installPrePush(command, force) {
+    const path = join(await hooksPath(), PRE_PUSH_FILE);
+    const existing = await readIfExists(path);
+    const foreign = existing !== null && !existing.includes(PRE_PUSH_MARKER);
+    if (foreign && !force) {
+        return { path, status: "skipped" };
+    }
+    const script = prePushScript(command);
+    if (existing === script) {
+        return { path, status: "unchanged" };
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, script, "utf8");
+    await chmod(path, HOOK_MODE);
+    return { path, status: existing === null ? "installed" : "updated" };
+}
+export function prePushScript(command) {
+    return [
+        "#!/usr/bin/env sh",
+        `# ${PRE_PUSH_MARKER} — reconciles an open declaration before a push.`,
+        `exec ${command} hook ${PRE_PUSH_FILE}`,
+        "",
+    ].join("\n");
+}
+async function readIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function summary(parts) {
+    const lines = [
+        linkLine(parts.link),
+        ...hookLines(parts.root, parts.wired, parts.noHooks),
+        prePushLine(parts.root, parts.prePush),
+        "",
+        enforceLine(parts.enforce),
+    ];
+    if (!parts.link.existed) {
+        lines.push("Commit .gatebolt so every clone and CI job resolves the same repository.");
+    }
+    return lines.join("\n") + "\n";
+}
+function linkLine(link) {
+    if (link.existed) {
+        return `Already linked (repository ${link.repositoryId.slice(0, ID_PREFIX_LEN)}…).`;
+    }
+    const verb = link.created ? "Created" : "Linked to existing";
+    return `${verb} repository ${link.name} (${link.slug}).`;
+}
+function hookLines(root, wired, noHooks) {
+    if (noHooks)
+        return ["Skipped agent hooks (--no-hooks)."];
+    const lines = [];
+    for (const { displayName, result } of wired) {
+        const verb = result.settingsChanged ? "wired" : "already wired";
+        lines.push(`${displayName}: ${verb} → ${relative(root, result.settingsPath)}`);
+        if (result.gitignoreChanged) {
+            lines.push(`  ignored ${GITIGNORE_ENTRY} in .gitignore`);
+        }
+    }
+    return lines;
+}
+function prePushLine(root, prePush) {
+    if (prePush === null)
+        return "Skipped pre-push backstop (--no-pre-push).";
+    const rel = relative(root, prePush.path);
+    switch (prePush.status) {
+        case "installed":
+            return `Installed pre-push backstop → ${rel}`;
+        case "updated":
+            return `Updated pre-push backstop → ${rel}`;
+        case "unchanged":
+            return `Pre-push backstop already installed → ${rel}`;
+        case "skipped":
+            return `Left the existing pre-push hook untouched (${rel}); pass --force to replace it.`;
+    }
+}
+function enforceLine(enforce) {
+    return enforce === "strict"
+        ? "Enforcement: strict — edits are blocked until you declare."
+        : "Enforcement: lenient — declaring is advisory. Pass `--enforce strict` to block edits until declared.";
+}

package/dist/commands/link.js

@@ -0,0 +1,61 @@
+import { parseArgs } from "node:util";
+import { parseRemoteUrl, repoIdentityFromName, resolveConnection, } from "../config.js";
+import { remoteOriginUrl, repoContext } from "../git.js";
+import { isRecord } from "../json.js";
+import { profileLoader, writeRepoLink } from "../profiles.js";
+import { postChange } from "../transport.js";
+export async function runLink(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            key: { type: "string" },
+            url: { type: "string" },
+            profile: { type: "string" },
+            name: { type: "string" },
+        },
+    });
+    const repo = await repoContext();
+    if (!repo) {
+        throw new Error("Not inside a git repository.");
+    }
+    const { root } = repo;
+    const loadProfile = profileLoader({ name: values.profile, root });
+    const connection = await resolveConnection({ key: values.key, url: values.url }, loadProfile);
+    const identity = values.name
+        ? repoIdentityFromName(values.name)
+        : ((await deriveIdentity()) ?? raiseNoRemote());
+    const result = await linkRepository(connection, root, identity);
+    const verb = result.created ? "Created" : "Linked to existing";
+    process.stdout.write(`${verb} repository ${result.name} (${result.slug}).\n` +
+        "Wrote .gatebolt — commit it so every clone and CI job resolves the same repository.\n");
+}
+export async function deriveIdentity() {
+    const url = await remoteOriginUrl();
+    return url ? parseRemoteUrl(url) : null;
+}
+export async function linkRepository(connection, root, identity) {
+    const input = {
+        slug: identity.slug,
+        name: identity.name,
+    };
+    const result = await postChange(connection, "repository.link", input);
+    if (!isLinkResult(result)) {
+        throw new Error("Unexpected response from server.");
+    }
+    await writeRepoLink(root, {
+        repositoryId: result.repositoryId,
+        ...(connection.profileName ? { profile: connection.profileName } : {}),
+    });
+    return result;
+}
+function raiseNoRemote() {
+    throw new Error("GateBolt cannot derive this repository's identity from its `origin` remote. " +
+        "Pass --name <a-name-for-this-repo> to name it yourself.");
+}
+export function isLinkResult(value) {
+    return (isRecord(value) &&
+        typeof value.repositoryId === "string" &&
+        typeof value.slug === "string" &&
+        typeof value.name === "string" &&
+        typeof value.created === "boolean");
+}

package/dist/commands/login.js

@@ -0,0 +1,317 @@
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { DEFAULT_BASE_URL } from "../config.js";
+import { isRecord } from "../json.js";
+import { readConfigForWrite, writeConfig } from "../profiles.js";
+import { authFetch } from "../rest.js";
+import { postChange, RequestError } from "../transport.js";
+const DEVICE_CLIENT_ID = "gatebolt-cli";
+const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+const SLOW_DOWN_INCREMENT_MS = 5_000;
+const MS_PER_SECOND = 1_000;
+const HTTP_OK = 200;
+const HTTP_SERVER_ERROR = 500;
+const MAX_UNREACHABLE_POLLS = 5;
+export async function runLogin(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            url: { type: "string" },
+            "key-name": { type: "string" },
+        },
+    });
+    const baseUrl = resolveBaseUrl(values.url);
+    const requestedName = values["key-name"]?.trim();
+    const keyName = requestedName !== undefined && requestedName.length > 0
+        ? requestedName
+        : defaultKeyName();
+    const code = await requestDeviceCode(baseUrl);
+    announce(code);
+    openBrowser(code.verification_uri_complete);
+    const token = await pollForToken(baseUrl, code);
+    const orgs = await listOrganizations(baseUrl, token);
+    const { org, key } = await mintForSelectedOrg(baseUrl, token, orgs, keyName);
+    const path = await saveLoginProfile(org.slug, baseUrl, key);
+    stdout.write(`\nSaved profile "${org.slug}" to ${path}.\n` +
+        `GateBolt is connected to ${org.name}. In each repository, run \`gatebolt link\` once ` +
+        `and commit the .gatebolt it writes, so declare and observe record against it.\n`);
+}
+function resolveBaseUrl(flag) {
+    const url = flag ?? process.env.GATEBOLT_URL ?? DEFAULT_BASE_URL;
+    return url.replace(/\/+$/, "");
+}
+function defaultKeyName() {
+    const [label] = hostname().split(".");
+    const host = label && label.length > 0 ? label : "device";
+    return `gatebolt-cli ${host}`;
+}
+async function requestDeviceCode(baseUrl) {
+    const result = await authFetch(baseUrl, "/device/code", {
+        method: "POST",
+        body: { client_id: DEVICE_CLIENT_ID },
+    });
+    const code = parseDeviceCode(result.json);
+    if (result.status !== HTTP_OK || !code) {
+        throw new Error(`Could not start the login (status ${result.status}).`);
+    }
+    return code;
+}
+function announce(code) {
+    stdout.write(`\nTo authorize the GateBolt CLI, open:\n  ${code.verification_uri_complete}\n\n` +
+        `Your code: ${code.user_code}\n` +
+        `(If your browser doesn't open, visit ${code.verification_uri} and enter the code.)\n\n` +
+        "Waiting for you to approve in the browser…\n");
+}
+async function pollForToken(baseUrl, code) {
+    let intervalMs = code.interval * MS_PER_SECOND;
+    const deadline = Date.now() + code.expires_in * MS_PER_SECOND;
+    let unreachablePolls = 0;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const outcome = await pollOnce(baseUrl, code.device_code);
+        if (outcome.kind === "token")
+            return outcome.token;
+        if (outcome.kind === "fatal")
+            throw new Error(outcome.message);
+        if (outcome.kind === "unreachable") {
+            unreachablePolls += 1;
+            if (unreachablePolls >= MAX_UNREACHABLE_POLLS)
+                throw new Error(outcome.message);
+            continue;
+        }
+        unreachablePolls = 0;
+        if (outcome.kind === "slow_down")
+            intervalMs += SLOW_DOWN_INCREMENT_MS;
+    }
+    throw new Error("Timed out waiting for approval. Run `gatebolt login` again when you're ready.");
+}
+async function pollOnce(baseUrl, deviceCode) {
+    try {
+        return interpretToken(await requestToken(baseUrl, deviceCode));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: "unreachable", message };
+    }
+}
+function requestToken(baseUrl, deviceCode) {
+    return authFetch(baseUrl, "/device/token", {
+        method: "POST",
+        body: {
+            grant_type: DEVICE_GRANT_TYPE,
+            device_code: deviceCode,
+            client_id: DEVICE_CLIENT_ID,
+        },
+    });
+}
+function interpretToken(result) {
+    if (result.status === HTTP_OK) {
+        const token = accessToken(result.json);
+        return token
+            ? { kind: "token", token }
+            : {
+                kind: "fatal",
+                message: "The server returned an unexpected response.",
+            };
+    }
+    if (result.status >= HTTP_SERVER_ERROR) {
+        return {
+            kind: "unreachable",
+            message: `The server is temporarily unavailable (status ${result.status}).`,
+        };
+    }
+    switch (tokenError(result.json)) {
+        case "authorization_pending":
+            return { kind: "pending" };
+        case "slow_down":
+            return { kind: "slow_down" };
+        case "access_denied":
+            return {
+                kind: "fatal",
+                message: "Authorization was denied in the browser.",
+            };
+        case "expired_token":
+            return {
+                kind: "fatal",
+                message: "The code expired before it was approved. Run `gatebolt login` again.",
+            };
+        default:
+            return {
+                kind: "fatal",
+                message: `Authorization failed (status ${result.status}).`,
+            };
+    }
+}
+async function listOrganizations(baseUrl, token) {
+    const result = await authFetch(baseUrl, "/organization/list", {
+        method: "GET",
+        token,
+    });
+    const orgs = parseOrganizations(result.json);
+    if (result.status !== HTTP_OK || !orgs) {
+        throw new Error(`Could not list your organizations (status ${result.status}).`);
+    }
+    if (orgs.length === 0) {
+        throw new Error("Your account has no organization yet. Create one in the dashboard, then run `gatebolt login` again.");
+    }
+    return orgs;
+}
+async function mintForSelectedOrg(baseUrl, token, orgs, keyName) {
+    const org = await activateChoice(baseUrl, token, orgs);
+    const first = await tryMint(baseUrl, token, keyName);
+    if (first.kind === "key")
+        return { org, key: first.key };
+    if (first.kind === "error")
+        throw first.error;
+    if (orgs.length === 1)
+        throw notAdminError(org);
+    stdout.write(`\nYou're not an admin of ${org.slug}, so a key can't be created there.\n`);
+    const retryOrg = await activateChoice(baseUrl, token, orgs);
+    const second = await tryMint(baseUrl, token, keyName);
+    if (second.kind === "key")
+        return { org: retryOrg, key: second.key };
+    if (second.kind === "error")
+        throw second.error;
+    throw notAdminError(retryOrg);
+}
+async function activateChoice(baseUrl, token, orgs) {
+    const org = await chooseOrg(orgs);
+    if (orgs.length > 1)
+        await setActiveOrg(baseUrl, token, org.id);
+    return org;
+}
+async function chooseOrg(orgs) {
+    const [first, ...rest] = orgs;
+    if (!first)
+        throw new Error("No organizations to choose from.");
+    if (rest.length === 0)
+        return first;
+    stdout.write("\nYou belong to more than one organization:\n");
+    orgs.forEach((org, index) => {
+        stdout.write(`  ${index + 1}. ${org.name} (${org.slug})\n`);
+    });
+    const answer = await prompt("Select an organization [1]: ");
+    const org = orgs[answer === "" ? 0 : Number(answer) - 1];
+    if (!org) {
+        throw new Error(`"${answer}" is not one of the listed organizations.`);
+    }
+    return org;
+}
+async function setActiveOrg(baseUrl, token, organizationId) {
+    const result = await authFetch(baseUrl, "/organization/set-active", {
+        method: "POST",
+        token,
+        body: { organizationId },
+    });
+    if (result.status !== HTTP_OK) {
+        throw new Error(`Could not select the organization (status ${result.status}).`);
+    }
+}
+async function tryMint(baseUrl, token, name) {
+    try {
+        const input = { name };
+        const result = await postChange({ key: token, baseUrl }, "agentKey.create", input);
+        return { kind: "key", key: result.key };
+    }
+    catch (error) {
+        if (error instanceof RequestError && error.code === "FORBIDDEN") {
+            return { kind: "forbidden" };
+        }
+        return { kind: "error", error };
+    }
+}
+function notAdminError(org) {
+    return new Error(`You're not an admin of ${org.name}, so you can't create an agent key there. ` +
+        "Ask an owner or admin to run `gatebolt login`, or pick an organization where you're an admin.");
+}
+async function saveLoginProfile(slug, baseUrl, key) {
+    const config = await readConfigForWrite();
+    config.profiles[slug] =
+        baseUrl === DEFAULT_BASE_URL ? { key } : { url: baseUrl, key };
+    config.default = slug;
+    return writeConfig(config);
+}
+function openBrowser(url) {
+    const opener = browserOpener();
+    try {
+        const child = spawn(opener.command, [...opener.args, url], {
+            stdio: "ignore",
+            detached: true,
+        });
+        child.on("error", noop);
+        child.unref();
+    }
+    catch {
+        // The URL is printed above, so a failed auto-open is not fatal.
+    }
+}
+function browserOpener() {
+    if (process.platform === "darwin")
+        return { command: "open", args: [] };
+    if (process.platform === "win32")
+        return { command: "cmd", args: ["/c", "start", ""] };
+    return { command: "xdg-open", args: [] };
+}
+async function prompt(question) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function noop() {
+    // Intentionally empty: a browser-open failure is swallowed.
+}
+function parseDeviceCode(json) {
+    if (!isRecord(json))
+        return null;
+    if (typeof json.device_code !== "string" ||
+        typeof json.user_code !== "string" ||
+        typeof json.verification_uri !== "string" ||
+        typeof json.verification_uri_complete !== "string" ||
+        typeof json.expires_in !== "number" ||
+        typeof json.interval !== "number") {
+        return null;
+    }
+    return {
+        device_code: json.device_code,
+        user_code: json.user_code,
+        verification_uri: json.verification_uri,
+        verification_uri_complete: json.verification_uri_complete,
+        expires_in: json.expires_in,
+        interval: json.interval,
+    };
+}
+function parseOrganizations(json) {
+    if (!Array.isArray(json))
+        return null;
+    const orgs = [];
+    for (const item of json) {
+        if (!isRecord(item))
+            return null;
+        const { id, name, slug } = item;
+        if (typeof id !== "string" ||
+            typeof name !== "string" ||
+            typeof slug !== "string") {
+            return null;
+        }
+        orgs.push({ id, name, slug });
+    }
+    return orgs;
+}
+function accessToken(json) {
+    return isRecord(json) && typeof json.access_token === "string"
+        ? json.access_token
+        : null;
+}
+function tokenError(json) {
+    return isRecord(json) && typeof json.error === "string" ? json.error : "";
+}