baesian 0.0.0-stage → 1.0.1

package/dist/cli.js

@@ -0,0 +1,831 @@
+import { spawn } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { agentName, harnessSession, modelSessions, personalInstructions } from "./agents.js";
+import { ciPin, runProgram, workflowBody, workflowSteps } from "./ci.js";
+import { Told, cite, citeIn, unmark, unmarkJson } from "./cite.js";
+import { CONFIG_PATH, stagedSnapshot } from "./facts.js";
+import { parseDoc } from "./frontmatter.js";
+import { describeReport, detectStaged, evaluate } from "./gate.js";
+import { personalProblems, runHook } from "./hooks.js";
+import { scanHistory } from "./merges.js";
+import { initShared, initSharedMode, setUpPersonal } from "./modes.js";
+import { notifyFiled } from "./notify.js";
+import { openRepo } from "./git.js";
+import { parseTrailers } from "./trailers.js";
+import { serveMcp } from "./mcp.js";
+import { attachOp, deckWaitIds, duplicateLines, failureLines, fileOp, inboxOp, listOp, replyOp, reviseOp, ruleOp, showOp, templateOp, topicsOp, verdictsHeadline, waitAllOp, waitOp, withdrawOp, } from "./ops.js";
+import { DEFAULT_SERVICE, Offline, firstCommitToLink, linkAck, linkRepo, machineName, newProjectId, projectPage, readGrant, removeGrant, revokeGrant, signInMachine, writeGrant, } from "./login.js";
+import { q } from "./quote.js";
+import { Origin } from "./schema.js";
+import { findRunningServer, serverUrl, startServer } from "./server.js";
+import { blank, cmd, dim, failed, fields, head, id, indent, lit, literal, next, note, render, renderFor, settingsOf, strong, table, text, warning, } from "./style.js";
+import { aroundFiling, linkProblem, spareKeys, syncRelay, waitWithRelay } from "./sync.js";
+import { describeVerify, fileConflicts, verify } from "./verify.js";
+import { PossibleDuplicate, Store, ValidationError } from "./store.js";
+import { TRUST_ENV } from "./trust.js";
+import { cleanVaultPath, vaultPathProblem, writeNotes } from "./vault.js";
+import { VERSION } from "./version.js";
+import { DEFAULT_TIMEOUT_MS, SLICE_MS, WaitCancelled } from "./wait.js";
+/** Exit code when a card may duplicate an open card or a resolved decision. */
+export const EXIT_POSSIBLE_DUPLICATE = 3;
+/** Baesian's version, as `baesian --version` prints it: package.json's, kept in src/version.ts. */
+export { VERSION };
+/** How long `baesian inbox --quiet`, a harness's hook, waits for the relay: a hook must stay quick, and never fail. */
+export const QUIET_SYNC_MS = 5000;
+/** The command line that re-runs this CLI, for hooks when `baesian` isn't on PATH (D48). */
+export function selfCommand(argv1 = process.argv[1]) {
+    if (!argv1)
+        return [];
+    // Resolve first: under `npm link` or a global install, argv[1] is the bin symlink (`…/bin/baesian`).
+    let script;
+    try {
+        script = realpathSync(argv1);
+    }
+    catch {
+        return [];
+    }
+    if (!script.endsWith(".js"))
+        return []; // running from source through tsx: rely on PATH
+    return [process.execPath, script];
+}
+/**
+ * Read stdin as a stream. `readFileSync(0)` fails with EAGAIN when the pipe's writer hasn't written
+ * yet (`baesian template | baesian file`), so it can't be used here.
+ */
+async function readStdin() {
+    if (process.stdin.isTTY)
+        throw new Told("no card given: pass a file, or pipe one in", [{ command: "baesian file card.md" }]);
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+const defaultIo = {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+    stdin: readStdin,
+    cwd: process.cwd(),
+    terminal: { out: process.stdout, err: process.stderr },
+};
+function seconds(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        throw new InvalidArgumentError("expected a number of seconds");
+    return n;
+}
+function port(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 65535)
+        throw new InvalidArgumentError("expected a port number");
+    return n;
+}
+/** Open an address in the default browser; if that fails, the printed address is enough. */
+function openInBrowser(url) {
+    const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        spawn(command, args, { detached: true, stdio: "ignore" }).on("error", () => { }).unref();
+    }
+    catch {
+        // no browser to open
+    }
+}
+/** A draft with `--secret-reason` on it, which files a card that looks like it holds a secret, in a hosted repo (B-jfkv9). */
+function withSecretReason(meta, reason) {
+    return reason === undefined ? meta : { ...meta, secret_reason: reason };
+}
+async function readInput(path, io) {
+    return !path || path === "-" ? await io.stdin() : readFileSync(resolve(io.cwd, path), "utf8");
+}
+const files = (n) => `${n} file${n === 1 ? "" : "s"}`;
+const mergesOf = (n) => (n === 1 ? "1 merge" : `${n} merges`);
+/**
+ * What the history scan recorded (B-dezkk): a headline, then each merge, oldest first: the branches, its commit, its
+ * day, and what it brought. A commit's subject is never shown.
+ */
+function scanLines(scan) {
+    const known = scan.known ? `; ${mergesOf(scan.known)} it found ${scan.known === 1 ? "was" : "were"} recorded already` : "";
+    if (!scan.found.length)
+        return [head("done", `git's history holds no merge that isn't recorded already${known}`)];
+    const what = (cards, commits) => [cards ? `${cards} card${cards === 1 ? "" : "s"}` : "", commits ? `${commits} commit${commits === 1 ? "" : "s"} citing cards` : ""].filter(Boolean).join(" and ") || "its deck";
+    return [
+        head("done", `recorded ${mergesOf(scan.found.length)} from git's history that no hook saw${known}`),
+        ...table(undefined, scan.found.map((f) => [`${f.branch} merged into ${f.into}`, id(f.commit.slice(0, 7)), dim(f.at.slice(0, 10)), what(f.cards.length, f.commits.length)])),
+    ];
+}
+/** The command's lines, as each of the two streams gets them: plain, or as a terminal shows them (B-eyrt5, B-qszqr). */
+function output(io, settings) {
+    const env = io.env ?? process.env;
+    const write = (stream, lines) => {
+        const how = renderFor(io.terminal?.[stream], env, settings);
+        for (const l of render(Array.isArray(lines) ? lines : [lines], how))
+            io[stream](l);
+    };
+    return {
+        say: (lines) => write("out", lines),
+        tell: (lines) => write("err", lines),
+        /** What the relay said, on standard error, so a command's output is its own. */
+        notes: (ns) => write("err", ns.map((n) => text(n))),
+        how: (stream) => renderFor(io.terminal?.[stream], env, settings),
+    };
+}
+export function buildProgram(io = defaultIo, state = { code: 0 }, settings = {}) {
+    // Help text cites Baesian's decisions only with --verbose (B-728jd).
+    const d = (s) => unmark(s, settings.verbose);
+    const { say, tell, notes, how } = output(io, settings);
+    const program = new Command()
+        .name("baesian")
+        .description("Swipe review for agent decisions. Agents file cards; a person answers them in the client.")
+        .version(VERSION, "-V, --version", "print Baesian's version")
+        .option("--agent <name>", d(`who is running this (default: $BAESIAN_AGENT, else the harness's own name, else 'agent'${citeIn("D102")})`))
+        .option("--verbose", "also say which of Baesian's own design decisions a message rests on")
+        .option("--color", "colour and symbols, even through a pipe or an agent's harness")
+        .option("--no-color", "plain text, as an agent reads it, even on a terminal")
+        // Throw instead of calling process.exit, and write through io; subcommands inherit both. A usage error prints a
+        // short error and where to get help (`main`), not the whole help.
+        .exitOverride()
+        .configureOutput({ writeOut: (s) => io.out(s.trimEnd()), writeErr: (s) => io.err(s.trimEnd()) });
+    const store = () => Store.open(io.cwd);
+    const json = (value) => io.out(JSON.stringify(value, unmarkJson, 2));
+    const notify = (card) => {
+        try {
+            (io.notify ?? notifyFiled)(card);
+        }
+        catch (e) {
+            tell(warning(`notification failed (the card is filed): ${e instanceof Error ? e.message : String(e)}`));
+        }
+    };
+    // The sessions the command runs in, so a card it files records its model (B-k0w7d).
+    const actor = () => ({ agent: agentName(program.opts().agent), notify, sessions: modelSessions(io.env ?? process.env) });
+    /** Print an operation's lines, or with `--json` its data (P18: what the MCP tool returns as structured content). */
+    const print = (op, asJson) => (asJson ? json(op.data) : say(op.lines));
+    const http = () => io.http ?? {};
+    /**
+     * A filing command (M9d): in a linked repo, pull first and push after (`aroundFiling()`); what the relay said goes to
+     * standard error, so the output is the command's own, as before.
+     */
+    const filing = async (s, op, asJson) => {
+        const { value, notes: said } = await aroundFiling(s, op, http());
+        print(value, asJson);
+        notes(said);
+    };
+    // Personal mode (B-4rwyz): every command but the hooks', the MCP server's, `init` (which fixes it) and a harness's quiet
+    // inbox (which says it once a session) says what's wrong with the clone's setup, such as a gate that's off because the
+    // clone's .git/config no longer includes Baesian's setting.
+    program.hook("preAction", (_program, command) => {
+        const name = command.name();
+        if (name === "hook" || name === "mcp" || name === "init" || (name === "inbox" && command.opts().quiet))
+            return;
+        let problems = [];
+        try {
+            problems = personalProblems(store());
+        }
+        catch {
+            // not a repo, or not set up: the command says so itself
+        }
+        tell(problems.map((p) => warning(p)));
+    });
+    program.commandsGroup("Setting up:");
+    program
+        .command("init")
+        .description("set up Baesian in this repo: the live layer (.git/baesian/), the record (.baesian/), the gate's block in the repo's hooks and the AGENTS.md instructions; or with --personal, for this clone alone, committing nothing")
+        .option("--personal", d(`use Baesian in this clone alone, in a repo whose collaborators don't${cite("B-4rwyz")}: nothing is committed, and the repo's hooks and AGENTS.md are left as they are`))
+        .option("--shared", "shared mode, which plain init sets up; in a personal clone, switch to it: this branch's record, the hooks' block and AGENTS.md are written into the repo, for you to commit")
+        .option("--vault <path>", "an Obsidian vault for the vault adapter, relative to the repo root (shared mode)")
+        .option("--no-agents", "don't write the instructions block in AGENTS.md")
+        .option("--no-hooks", "don't install the git gate")
+        .action((opts) => {
+        if (opts.personal && opts.shared)
+            throw new ValidationError("--personal and --shared: choose one");
+        const s = store();
+        const vault = opts.vault === undefined ? undefined : cleanVaultPath(opts.vault);
+        if (vault !== undefined) {
+            const problem = vaultPathProblem(s.repo.toplevel, vault);
+            if (problem)
+                throw new ValidationError(problem);
+        }
+        const o = { ...(vault !== undefined ? { vault } : {}), agents: opts.agents, hooks: opts.hooks, fallback: io.hookFallback ?? selfCommand() };
+        // B-4rwyz: a personal clone stays personal, unless --shared switches it; plain init in any other clone is shared mode.
+        const personal = opts.personal || (!opts.shared && s.personal);
+        say(personal ? setUpPersonal(s, o) : opts.shared ? initShared(store, o) : initSharedMode(s, o));
+    });
+    program
+        .command("serve")
+        .description(d(`serve the client on 127.0.0.1 and open it; one server per repo. In a repo linked to the hosted service, open the project's page on the website instead${cite("D143")}`))
+        .option("--port <n>", "listen on this port (by default the last server's, if it's free, or one the system picks)", port)
+        .option("--no-open", "don't open the browser")
+        .option("--poll", "check the live layer every second instead of watching it, for shared storage")
+        .action(async (opts) => {
+        const s = store();
+        // D143 (B-k216t): in a linked repo, every answer comes from the website, signed; the local client doesn't start.
+        const link = s.config();
+        if (link.service && link.project) {
+            const problem = linkProblem(s, link);
+            if (problem) {
+                tell(failed(`not serving: ${problem}`));
+                state.code = 1;
+                return;
+            }
+            const page = projectPage(link.service, link.project);
+            say([head("done", `this repo is linked to ${link.service}: its cards are answered on the website, signed in with your passkey, not here`), ...fields([{ label: "page", value: page }])]);
+            if (opts.open)
+                openInBrowser(page);
+            return;
+        }
+        const running = await findRunningServer(s);
+        if (running) {
+            say(head("done", `already serving this repo: ${serverUrl(running)}`));
+            if (opts.open)
+                openInBrowser(serverUrl(running));
+            return;
+        }
+        const server = await startServer(s, { ...(opts.port ? { port: opts.port } : {}), poll: opts.poll ?? false });
+        say([
+            head("done", `serving ${s.repo.toplevel} at ${server.url}`),
+            indent(2, text(dim(`watching the live layer by ${server.watchMode() === "poll" ? "polling every second" : "file events, with a rescan every 30 seconds"}; Ctrl-C to stop`))),
+        ]);
+        if (opts.open)
+            openInBrowser(server.url);
+        await new Promise((done) => {
+            process.once("SIGINT", done);
+            process.once("SIGTERM", done);
+        });
+        await server.close();
+        say(head("done", "stopped"));
+    });
+    program
+        .command("login")
+        .description(d(`sign this machine in to the hosted service for this repo's project, linking the repo first if it isn't${cite("B-62qnz")}`))
+        .option("--service <url>", `the service's address, for a repo that isn't linked yet (default: $BAESIAN_SERVICE, else ${DEFAULT_SERVICE})`)
+        .option("--machine <name>", "this machine's name, as the website shows it (default: its hostname)")
+        .action(async (opts) => {
+        const s = store();
+        s.requireInit();
+        const c = s.config();
+        const asked = opts.service ?? (c.service ? undefined : (io.env ?? process.env).BAESIAN_SERVICE);
+        if (asked !== undefined && !Origin.safeParse(asked).success)
+            throw new ValidationError(`--service: the service's address, an origin such as https://baesian.example, with no path (got ${JSON.stringify(asked)})`);
+        if (c.service && asked && asked !== c.service) {
+            throw new ValidationError(s.personal
+                ? `this clone is linked to ${c.service}, not ${asked}: to move it, change the service and project in its config, .git/baesian/config.json (personal mode${citeIn("B-4rwyz")})`
+                : `this repo is linked to ${c.service}, not ${asked}: to move it, change the service and project in .baesian/config.json, a change the commit gate asks a card or an ack for${cite("B-w4g6c")}`);
+        }
+        // B-f2mfb: with none named, the hosted service. Its approval page names it, and takes a passkey, before any card
+        // leaves this machine; someone running their own names it once, and the config keeps it.
+        const service = c.service ?? asked ?? DEFAULT_SERVICE;
+        // Linking (B-62qnz, B-5gnea): a repo with no project, or a copy of another repo's (its history starts elsewhere),
+        // gets a project of its own; one whose config lacks its first commit has it recorded.
+        const copy = c.project !== undefined && c.first_commit !== undefined && linkProblem(s, c) !== undefined;
+        const link = c.project === undefined || copy
+            ? { service, project: newProjectId(), first_commit: firstCommitToLink(s.repo.toplevel) }
+            : c.first_commit === undefined
+                ? { service, project: c.project, first_commit: firstCommitToLink(s.repo.toplevel) }
+                : undefined;
+        const project = link?.project ?? c.project;
+        if (!link) {
+            const held = (() => {
+                try {
+                    return readGrant(project);
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            if (held?.service === service) {
+                say([head("done", `this machine is signed in already, to project ${project} on ${service}, as ${held.machine}`), next("baesian logout", "first, to sign in again")]);
+                return;
+            }
+        }
+        const fresh = link && link.project !== c.project;
+        if (fresh && !c.service) {
+            say([head(undefined, strong(`linking this ${s.personal ? "clone" : "repo"} to ${service}`), ", the hosted service"), indent(2, text(dim("to use another, run "), cmd("baesian login --service <url>"), dim(" instead")))]);
+        }
+        else if (fresh)
+            say(head(undefined, strong(`linking this ${s.personal ? "clone" : "repo"} to ${service}`)));
+        if (copy)
+            say(note(`this checkout is a copy of another repo, not that repo${cite("B-5gnea")}: linking it to a project of its own`));
+        const grant = await signInMachine({
+            ...http(),
+            service,
+            project,
+            machine: opts.machine ?? machineName(),
+            ...(io.sleep ? { sleep: io.sleep } : {}),
+            onCode: (code) => {
+                // B-zqkwk: a new project is named on that page, by the person; this repo's own name is never sent.
+                const asks = fresh ? "It asks you to name the project, then for your passkey." : "It asks for your passkey.";
+                say([
+                    text("Open this page, and check it shows the code ", strong(code.user_code), ":"),
+                    indent(2, literal(code.verification_uri_complete ?? code.verification_uri)),
+                    indent(2, text(dim(`${asks} The code lasts ${Math.round(code.expires_in / 60)} minutes.`))),
+                    text(dim("waiting for it to be approved…")),
+                ]);
+            },
+        });
+        writeGrant(grant);
+        if (link)
+            linkRepo(s, link);
+        // B-dezkk: a repo linked here records, once, the merges its history shows that no hook saw (made before it had
+        // Baesian's merge hooks), so they go up with the first sync. Linking never fails for it.
+        let scanned;
+        let unscanned;
+        if (link) {
+            try {
+                scanned = scanHistory(s, { write: true });
+            }
+            catch (e) {
+                unscanned = e instanceof Error ? e.message.split("\n")[0] : String(e);
+            }
+        }
+        // The first sync: the relay's files come down, and everything an agent wrote here goes up (B-6k0rk). A repo with a
+        // history of cards sends hundreds of files, so it says how many before it starts.
+        const relay = await syncRelay(s, { ...http(), sending: (n) => say(text(dim(`sending ${files(n)} to ${service}…`))) });
+        const linkedIn = s.personal
+            ? `linked in its own config, .git/baesian/config.json: personal mode commits nothing, so there's nothing to commit${cite("B-62qnz", "B-4rwyz")}`
+            : `linked in ${CONFIG_PATH}${cite("B-62qnz", "B-5gnea")}`;
+        say([
+            head("done", `signed in: ${grant.machine} can file cards and hear answers in this project, never answer them`),
+            ...fields([
+                { label: "project", value: project, ...(link ? { why: linkedIn } : {}) },
+                !!scanned?.found.length && { label: "history", value: mergesOf(scanned.found.length), why: `from git's history, made before this repo had Baesian's merge hooks: recorded once${cite("B-dezkk")}` },
+                relay.state === "synced" && { label: "relay", value: `sent ${files(relay.pushed.length)}, received ${relay.pulled.length}` },
+                { label: "answer", value: projectPage(service, project) },
+            ]),
+        ]);
+        if (unscanned)
+            tell([warning(`couldn't read git's history for merges no hook saw (${unscanned})`), next("baesian sync --history", "to try again")]);
+        notes(relay.notes);
+        if (link && !s.personal) {
+            // The link is a gate fact (B-w4g6c): a command to commit it with its ack, ready to run, the trailer its own paragraph.
+            say(next(`git add ${CONFIG_PATH} && git commit -m "Link this repo to Baesian" -m "${linkAck(service, link.project)}"`, "commit the link, with the ack the commit gate asks for where cards go"));
+        }
+    });
+    program
+        .command("logout")
+        .description("revoke this machine's grant for this repo's project, and delete its tokens")
+        .action(async () => {
+        const s = store();
+        s.requireInit();
+        const { project } = s.config();
+        if (!project)
+            throw new ValidationError("this repo isn't linked to the service, so there's nothing to sign out of");
+        let grant;
+        try {
+            grant = readGrant(project);
+        }
+        catch {
+            removeGrant(project);
+            say([head("attention", `deleted this machine's unreadable grant file for project ${project}`), indent(2, text("Revoke the machine on the website's Machines page."))]);
+            return;
+        }
+        if (!grant) {
+            say(head("done", `this machine isn't signed in to project ${project}`));
+            return;
+        }
+        let reached = true;
+        try {
+            await revokeGrant(grant, http());
+        }
+        catch (e) {
+            if (!(e instanceof Offline))
+                throw e;
+            reached = false;
+            notes([`relay: ${e.message}`]);
+        }
+        removeGrant(project);
+        say(reached
+            ? head("done", `signed out: revoked this machine's grant for project ${project}, and deleted its tokens`)
+            : [
+                head("attention", `deleted this machine's tokens for project ${project}, but couldn't revoke its grant`),
+                indent(2, text("Revoke it on the website's Machines page, or it lapses after 30 days unused.")),
+            ]);
+    });
+    program
+        .command("ci")
+        .description(d(`in a linked repo: the lines CI's BAESIAN_TRUST pins, read from the service, and the workflow steps that run baesian verify${cite("B-pt52b")}`))
+        .option("--github", "also set the repository variable BAESIAN_TRUST with gh, after printing it")
+        .option("--json", "print the result as JSON")
+        .action(async (opts) => {
+        const s = store();
+        s.requireInit();
+        // B-4rwyz: CI checks each commit against its committed record, and personal mode commits none.
+        if (s.personal) {
+            throw new ValidationError(`this clone uses Baesian in personal mode${cite("B-4rwyz")}: nothing of Baesian's is committed, so CI has no record to verify, and no pin to set. To have CI check the repo's decisions, switch it to shared mode, commit, then run \`baesian ci\`.`, [{ command: "baesian init --shared", why: "switch to shared mode" }]);
+        }
+        const c = s.config();
+        if (!c.service || !c.project)
+            throw new ValidationError("this repo isn't linked to the hosted service", [{ command: "baesian login", why: "first, then baesian ci" }]);
+        // The keys come from the service, through this pull, never from the committed record, which a commit can change.
+        const relay = await syncRelay(s, { ...http(), push: false });
+        notes(relay.notes);
+        if (relay.state === "signed-out")
+            throw new ValidationError(`this machine isn't signed in to project ${c.project} on ${c.service}`, [{ command: "baesian login", why: "first, then baesian ci" }]);
+        if (relay.state === "stopped")
+            throw new ValidationError("this checkout doesn't sync with the project its config names, so it can't read the project's keys (above)");
+        if (relay.state !== "synced")
+            throw new ValidationError(`couldn't sync with ${c.service}, and CI's keys must come from it: run \`baesian ci\` again once it's reachable`);
+        // B-x47ek: the service's spare key, which it never signs with, pinned beside its key so CI passes if it switches.
+        const spare = await spareKeys(c.service, http());
+        if (spare.problem)
+            notes([`relay: ${spare.problem}, so the pin has no spare key${cite("B-x47ek")}: run \`baesian ci\` again later to add it`]);
+        const pin = ciPin(s, c.service, c.project, spare.keys);
+        if ("problem" in pin)
+            throw new ValidationError(pin.problem);
+        if (pin.skipped.length)
+            notes(pin.skipped.map((k) => `left out ${k.file}: ${k.why}`));
+        if (opts.json)
+            json({ ...pin, steps: workflowSteps(VERSION).join("\n") });
+        else {
+            const page = new URL("/account", pin.site).href;
+            const count = pin.passkeys.length === 1 ? "1 passkey" : `${pin.passkeys.length} passkeys`;
+            const lines = [
+                head(undefined, strong(`CI's pin for project ${c.project}`), `, read from ${c.service}`),
+                indent(2, warning(`that's the service ${CONFIG_PATH} names${cite("B-pt52b")}. If it isn't the one you meant, stop here: a commit can change the config.`)),
+                blank,
+                text(strong("1."), ` Set the repository variable ${TRUST_ENV} to these ${pin.lines.length} lines, the project's${cite("B-mar8x")}, the service's key${pin.spare.length ? `, its spare (${pin.spare.join(", ")})` : ""} and ${count} (on GitHub: Settings, Secrets and variables, Actions, Variables), or run `, cmd("baesian ci --github"), ":"),
+                blank,
+                ...pin.lines.map(literal),
+                blank,
+                ...(pin.spare.length
+                    ? [
+                        indent(3, text(`The spare, ${pin.spare.join(", ")}, is a key the service keeps offline and never signs with${cite("B-x47ek")}: pinned now, CI keeps passing if the service ever has to replace its key with it.`)),
+                        blank,
+                    ]
+                    : []),
+            ];
+            if (pin.passkeys.length) {
+                const whose = pin.passkeys.map((p) => `${p.handle}'s, added ${p.enrolled.slice(0, 10)}`).join("; ");
+                lines.push(indent(3, text(`Check ${pin.passkeys.length === 1 ? "the passkey is" : "each passkey is"} yours (${whose}): compare its line with the one the website showed when you added it, and with your account page, ${page}. Leave out a line that isn't yours.`)));
+            }
+            else {
+                lines.push(indent(3, warning(`no passkey yet: CI counts an answer on a hard card only with a passkey it pins${cite("D139", "D159")}. Add one on your account page, ${page}, and run `, cmd("baesian ci"), " again.")));
+            }
+            lines.push(blank, text(strong("2."), " Add these steps to a workflow that runs on pushes to your main branch and on pull requests, as one job's steps:"), blank, ...workflowBody(VERSION).map(literal));
+            say(lines);
+        }
+        if (opts.github) {
+            // Only after the lines are shown (B-pt52b). gh reads the variable's value from its input.
+            const r = (io.run ?? runProgram)("gh", ["variable", "set", TRUST_ENV], { input: `${pin.lines.join("\n")}\n`, cwd: s.repo.toplevel });
+            if (r.missing) {
+                tell([failed(`gh isn't on PATH, so ${TRUST_ENV} wasn't set: set it by hand, or install GitHub's CLI (https://cli.github.com)`), next("baesian ci --github", "again, once gh is installed")]);
+                state.code = 1;
+            }
+            else if (r.status !== 0) {
+                tell(failed(`gh variable set ${TRUST_ENV} failed${r.stderr.trim() ? `: ${r.stderr.trim()}` : ""}`));
+                state.code = 1;
+            }
+            else
+                (opts.json ? tell : say)(head("done", `set the repository variable ${TRUST_ENV} with gh: ${pin.lines.length} lines`));
+        }
+    });
+    program
+        .command("sync")
+        .description("in a linked repo, sync with the relay; then copy new verdicts and ledger entries into this branch's record (.baesian/), and write the vault's notes")
+        .option("--history", d(`first, record the merges git's history shows that no hook saw: made before this repo had Baesian's merge hooks, or where it isn't installed. Linking a repo does this once${cite("B-dezkk")}`))
+        .action(async (opts) => {
+        const s = store();
+        s.requireInit();
+        // B-dezkk: the history scan, as at first link, so what it records goes up with this sync.
+        if (opts.history)
+            say(scanLines(scanHistory(s, { write: true })));
+        // M9d: pull the relay's log, and push what it doesn't have, before the record is brought up to date.
+        const relay = await syncRelay(s, http());
+        if (relay.state === "synced")
+            say(head("done", `synced with the relay: received ${files(relay.pulled.length)}, sent ${relay.pushed.length}`));
+        notes(relay.notes);
+        // Personal mode (B-4rwyz) has no record and no vault: the live layer is all there is.
+        if (s.personal)
+            return say(head("done", `personal mode: nothing to bring into a record, since this clone commits none${cite("B-4rwyz")}`));
+        const added = s.syncRecord();
+        say(added.length ? [head("done", `added ${files(added.length)} to the record (.baesian/)`), ...indent(2, added.map((p) => text(p)))] : head("done", "the record is up to date"));
+        // M6 (D170): the vault's notes too, for verdicts that came after the branch's last commit. Not staged.
+        const written = writeNotes(s);
+        tell(written.warnings.map((w) => warning(w)));
+        if (written.vault && !written.unusable) {
+            const n = written.written.length;
+            say(n ? [head("done", `wrote ${n === 1 ? "1 note" : `${n} notes`} in the vault`), ...indent(2, written.written.map((p) => text(p)))] : head("done", "the vault's notes are up to date"));
+        }
+    });
+    program
+        .command("mcp")
+        .description("serve the agent commands as MCP tools over stdio, for a harness to start (the plugin registers it)")
+        .action(async () => {
+        // Only protocol messages go to the output; the server opens the store on every call, in the harness's directory.
+        await serveMcp({ cwd: io.cwd, ...(program.opts().agent ? { agent: program.opts().agent } : {}) });
+    });
+    program.commandsGroup("Filing and answers:");
+    program
+        .command("template")
+        .description("print a card draft to fill in")
+        .option("--json", "print it as JSON")
+        .action((opts) => print(templateOp(), opts.json));
+    program
+        .command("topics")
+        .description("list the topics in use, to reuse rather than invent near-duplicates")
+        .option("--json", "print them as JSON")
+        .action((opts) => print(topicsOp(store()), opts.json));
+    program
+        .command("file")
+        .description("file a decision card from a Markdown file (or stdin)")
+        .argument("[path]", "the card draft; '-' or omitted reads stdin")
+        .option("--new", "file even if an open card or a resolved decision looks like the same decision")
+        .option("--secret-reason <text>", d(`in a hosted repo, file a card that looks like it holds a secret anyway, saying why; kept on the card${cite("B-jfkv9")}`))
+        .option("--json", "print the filed card as JSON")
+        .action(async (path, opts) => {
+        const { meta, body } = parseDoc(await readInput(path, io));
+        const s = store();
+        await filing(s, () => fileOp(s, withSecretReason(meta, opts.secretReason), body, { ...actor(), force: opts.new ?? false }), opts.json);
+    });
+    program
+        .command("wait")
+        .description("wait for the reviewer's verdict on a card, or on several; the exit code says what to do next")
+        .argument("[ids...]", d(`the cards: with several, it returns when every one is answered, or sooner when one comes back to you${cite("B-xnae9")}`))
+        .option("--deck <id>", "wait on your cards in this deck that are still with the reviewer, with any IDs given")
+        .option("--until-answered", "no time limit: return only when the cards are answered, or one comes back, for a run in the background that wakes you when it ends")
+        .option("--timeout <seconds>", "how long to wait in all, across runs, before falling back; with --until-answered, how long the reviewer sees you waiting", seconds, DEFAULT_TIMEOUT_MS / 1000)
+        .option("--slice <seconds>", d(`how long this run lasts before it exits 7 to be run again${cite("D101")}`), seconds, SLICE_MS / 1000)
+        .option("--no-presence", "wait the full timeout even if the client says the reviewer is away")
+        .option("--json", "print the outcome as JSON")
+        .action(async (ids, opts) => {
+        if (!ids.length && opts.deck === undefined)
+            throw new Told("name a card to wait on, or several, or a deck with --deck", [{ command: "baesian list", why: "the cards still with the reviewer" }]);
+        const agent = agentName(program.opts().agent);
+        // Ctrl-C stops the wait and removes its markers, since the agent has stopped waiting (P18).
+        const stop = new AbortController();
+        const cancel = () => stop.abort();
+        process.once("SIGINT", cancel);
+        try {
+            const s = store();
+            const options = {
+                agent,
+                timeoutMs: opts.timeout * 1000,
+                sliceMs: opts.slice * 1000,
+                usePresence: opts.presence,
+                untilAnswered: opts.untilAnswered ?? false,
+                signal: stop.signal,
+                ...io.waitClock,
+            };
+            // One card waits as ever; several, or a deck's, wait together (B-xnae9). The deck's cards are read after the first
+            // sync, so an answer given while the agent was away is counted. An answer it gives is marked delivered: `inbox`
+            // and the hooks shouldn't hand it over again. In a linked repo it listens on the relay's socket, and the waiting
+            // markers go up as a heartbeat (M9d, B-bv49e).
+            const one = ids.length === 1 && opts.deck === undefined;
+            const { value: op, notes: said } = await waitWithRelay(s, (o) => (one ? waitOp(s, ids[0], o) : waitAllOp(s, [...ids, ...(opts.deck === undefined ? [] : deckWaitIds(s, opts.deck, agent))], o)), options, http());
+            print(op, opts.json);
+            notes(said);
+            state.code = op.data.exit;
+        }
+        finally {
+            process.off("SIGINT", cancel);
+        }
+    });
+    program
+        .command("inbox")
+        .description("verdicts on this branch's cards since you last looked")
+        .option("--peek", "don't mark them as seen")
+        .option("--json", "print as JSON")
+        .option("--quiet", "for a harness hook: print nothing when there's nothing new, or the repo doesn't use Baesian")
+        .option("--session <id>", "for a harness hook: the session reading, which keeps its own place, so every session on the branch hears each verdict once")
+        .action(async (opts) => {
+        // A session starting in a repo without Baesian, or one not set up, isn't an error for a hook.
+        let op;
+        let starting = [];
+        try {
+            const s = store();
+            // M9d: in a linked repo, pull first, and push what's waiting to go up. A hook's run is brief and silent.
+            if (s.isInitialised()) {
+                const given = io.http ?? {};
+                const synced = await syncRelay(s, opts.quiet ? { ...given, signal: given.signal ?? AbortSignal.timeout(QUIET_SYNC_MS) } : given).catch(() => undefined);
+                if (!opts.quiet)
+                    notes(synced?.notes ?? []);
+            }
+            // A hook names its session; an agent's own command runs in one too, which the harness says (B-ghhym).
+            const session = opts.session ?? harnessSession(io.env ?? process.env);
+            // Personal mode (B-4rwyz): AGENTS.md says nothing of Baesian, so a harness's hook hands the agent its instructions
+            // at a session's first read, with anything wrong with the clone's setup.
+            if (opts.quiet && !opts.json && session && s.isInitialised() && s.personal && !s.sessionKnown(session)) {
+                starting = [...personalInstructions().split("\n").map(literal), ...personalProblems(s).map((p) => text(`Baesian: ${p}`))];
+            }
+            op = inboxOp(s, { advance: !opts.peek, ...(session ? { session } : {}) });
+        }
+        catch (e) {
+            if (opts.quiet)
+                return;
+            throw e;
+        }
+        if (opts.json)
+            return json(op.data);
+        say(starting);
+        if (!op.data.length && opts.quiet)
+            return;
+        // A harness's hook hands the agent these lines under a heading of their own, which says where they came from.
+        if (opts.quiet)
+            say([text(`Baesian: ${verdictsHeadline(op.data.length)}, since you last looked (`, cmd("baesian inbox"), ")"), ...op.lines.slice(1)]);
+        else
+            say(op.lines);
+    });
+    program
+        .command("list")
+        .description("list cards that still need the reviewer (or all of them)")
+        .option("--all", "include resolved, withdrawn and superseded cards")
+        .option("--branch", "only this branch's cards")
+        .option("--json", "print as JSON")
+        .action((opts) => print(listOp(store(), opts), opts.json));
+    program
+        .command("show")
+        .description("show a card, its status and its verdicts")
+        .argument("<id>", "the card")
+        .option("--json", "print as JSON")
+        .action((cardId, opts) => print(showOp(store(), cardId), opts.json));
+    program
+        .command("revise")
+        .description("file the next revision of a returned card: your reply to the reviewer")
+        .argument("<id>", "the card")
+        .argument("[path]", "the revised card; '-' or omitted reads stdin")
+        .option("--secret-reason <text>", d(`in a hosted repo, file a revision that looks like it holds a secret anyway, saying why${cite("B-jfkv9")}`))
+        .option("--json", "print the new revision as JSON")
+        .action(async (cardId, path, opts) => {
+        const { meta, body } = parseDoc(await readInput(path, io));
+        const s = store();
+        await filing(s, () => reviseOp(s, cardId, withSecretReason(meta, opts.secretReason), body, actor()), opts.json);
+    });
+    program
+        .command("reply")
+        .description(d(`reply once to an answer that went against your pick: a fact the reviewer lacked, or a check${cite("D89")}`))
+        .argument("<id>", "the card")
+        .argument("<text>", "the fact or the check, in a line; not your pick again")
+        .option("--json", "print the reply's revision as JSON")
+        .action(async (cardId, reply, opts) => {
+        const s = store();
+        await filing(s, () => replyOp(s, cardId, reply, actor()), opts.json);
+    });
+    program
+        .command("rule")
+        .description(d(`draft the rule the reviewer asked for on a decision; it goes to them as a card${cite("D16", "D110")}`))
+        .argument("<id>", "the decision")
+        .argument("<text>", "the rule, in a line")
+        .option("--covers <patterns...>", "the gate facts it answers, as gate reports name them: dep:pytest-*, schema:migrations/*")
+        .option("--json", "print the draft's card as JSON")
+        .action(async (cardId, rule, opts) => {
+        const s = store();
+        await filing(s, () => ruleOp(s, cardId, rule, opts.covers ?? [], actor()), opts.json);
+    });
+    program
+        .command("attach")
+        .description("wait on an existing card instead of filing a duplicate")
+        .argument("<id>", "the card")
+        .option("--json", "print the attachment as JSON")
+        .action(async (cardId, opts) => {
+        const s = store();
+        await filing(s, () => attachOp(s, cardId, agentName(program.opts().agent)), opts.json);
+    });
+    program
+        .command("withdraw")
+        .description("withdraw your own card")
+        .argument("<id>", "the card")
+        .requiredOption("--reason <text>", "why it's no longer needed")
+        .option("--json", "print the withdrawal as JSON")
+        .action(async (cardId, opts) => {
+        const s = store();
+        await filing(s, () => withdrawOp(s, cardId, opts.reason, agentName(program.opts().agent)), opts.json);
+    });
+    program
+        .command("deck")
+        .description("create a deck; its body is the briefing")
+        .argument("<id>", "a lowercase slug, e.g. storage-layer")
+        .requiredOption("--title <text>", "what the deck decides")
+        .option("--from <path>", "use a document (a plan, design note, issue) as the briefing; '-' reads stdin")
+        .option("--note <wikilink...>", "vault notes that give context")
+        .action(async (deckId, opts) => {
+        // A briefing piped in records no `from`: a harness's plan lives outside the repo, and its path would show the
+        // machine's layout in the record (as D105 found for worktrees).
+        const from = opts.from && opts.from !== "-" ? resolve(io.cwd, opts.from) : undefined;
+        const body = opts.from ? await readInput(opts.from, io) : "";
+        const s = store();
+        const create = () => {
+            const deck = s.createDeck({ id: deckId, title: opts.title, ...(from ? { from } : {}), ...(opts.note ? { context_notes: opts.note } : {}) }, body);
+            return {
+                lines: [head("done", "created deck ", id(deck.meta.id), " ", q(deck.meta.title)), indent(2, text("File cards into it with ", lit(`deck: ${deck.meta.id}`), " in their frontmatter."))],
+                data: deck,
+            };
+        };
+        await filing(s, create, false);
+    });
+    program.commandsGroup("The commit gate:");
+    program
+        .command("check")
+        .description("preview the commit gate on the staged changes: the decisions found, and what covers them")
+        .option("--message <file>", "check the trailers in this commit message too")
+        .option("--json", "print the report as JSON")
+        .action((opts) => {
+        const s = store();
+        const message = opts.message ? readFileSync(resolve(io.cwd, opts.message), "utf8") : "";
+        const report = evaluate(s, detectStaged(s, stagedSnapshot(s.repo.toplevel)), parseTrailers(message, s.repo.toplevel));
+        // The exit code is the same with --json: found by rehearse's agent, whose graders read the JSON.
+        state.code = report.ok ? 0 : 1;
+        if (opts.json)
+            return json(report);
+        say(describeReport(report, { for: "check", message: opts.message !== undefined }));
+        if (s.personal && report.facts.length) {
+            say(note(`personal mode${cite("B-4rwyz")}: the commit-msg hook takes these trailers out of the message once it has checked them, into this clone's ledger`));
+        }
+    });
+    program
+        .command("verify")
+        .description("CI: check every commit since --base against its committed record; --merge adds the merge gate")
+        .option("--base <ref>", "the branch being merged into (default: origin/$GITHUB_BASE_REF in GitHub Actions)")
+        .option("--merge", "also require every cited card to be resolved or deferred, and no conflicting decisions")
+        .option("--file-conflicts", "file a conflict card for each conflict (local only: needs the live layer)")
+        .option("--json", "print the result as JSON")
+        .action((opts) => {
+        const base = opts.base ?? (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : undefined);
+        if (!base)
+            throw new Told("verify needs the branch the work merges into", [{ command: "baesian verify --base origin/main", why: "or whichever branch it is" }]);
+        try {
+            if (store().personal)
+                tell(note(`this clone uses Baesian in personal mode${cite("B-4rwyz")}: its decisions aren't committed, so verify, which reads each commit's own record, sees none of them`));
+        }
+        catch {
+            // CI's checkout has no live layer: it's never personal
+        }
+        const repo = openRepo(io.cwd);
+        const result = verify(repo, base, { merge: Boolean(opts.merge || opts.fileConflicts) });
+        if (opts.json)
+            json(result);
+        else
+            say(describeVerify(result));
+        if (opts.fileConflicts && result.merge?.conflicts.length) {
+            const s = store();
+            for (const card of fileConflicts(s, result.merge.conflicts)) {
+                notify(card);
+                say(head("done", "filed conflict card ", id(card.meta.id), " ", q(card.meta.title)));
+            }
+        }
+        state.code = result.ok ? 0 : 1;
+    });
+    program
+        .command("hook", { hidden: true })
+        .description("run a git hook (called by the hooks `baesian init` installs)")
+        .argument("<name>", "pre-commit, commit-msg, post-commit, post-merge, post-rewrite or pre-push")
+        .argument("[args...]", "the hook's arguments")
+        .action(async (name, args) => {
+        const s = store();
+        // Personal mode's post-rewrite hands Baesian the commits it rewrote, on standard input (B-4rwyz); shared mode's
+        // doesn't. pre-push hands it the refs being pushed (B-h7rsv).
+        let input = "";
+        if ((name === "post-rewrite" && s.personal) || name === "pre-push") {
+            try {
+                input = await io.stdin();
+            }
+            catch {
+                // no input
+            }
+        }
+        state.code = await runHook(s, name, args, { out: io.out, err: io.err, how: how("err") }, http(), input);
+    });
+    // A usage error (an unknown option, a missing argument) prints a short error and where to get help (`main`), not the
+    // whole help: each command notes that it was the one.
+    for (const c of [program, ...program.commands]) {
+        c.configureOutput({
+            outputError: (message) => {
+                state.usage = { command: c === program ? "" : c.name(), message: message.trim() };
+            },
+        });
+    }
+    return program;
+}
+/** A usage error, as Commander says it, made short: what was wrong, a suggestion if it has one, and where to get help. */
+function usageLines(usage) {
+    const [first, ...more] = usage.message.replace(/^error: /, "").split("\n");
+    const suggestion = more.join(" ").trim();
+    return [failed(first, suggestion ? ` ${suggestion.replace(/^\((.*)\)$/, "($1)").replace("(Did you", "(did you")}` : ""), next(`baesian ${usage.command ? `${usage.command} ` : ""}--help`, usage.command ? "its options" : "the commands")];
+}
+export async function main(argv = process.argv, io = defaultIo) {
+    const state = { code: 0 };
+    const settings = settingsOf(argv.slice(2));
+    const { tell } = output(io, settings);
+    try {
+        await buildProgram(io, state, settings).parseAsync(argv);
+        return state.code;
+    }
+    catch (e) {
+        // Commander has printed help and the version itself; a usage error it noted, for this to print short.
+        if (e instanceof CommanderError) {
+            if (state.usage && e.exitCode !== 0)
+                tell(usageLines(state.usage));
+            return e.exitCode;
+        }
+        if (e instanceof PossibleDuplicate) {
+            tell(duplicateLines(e));
+            return EXIT_POSSIBLE_DUPLICATE;
+        }
+        // Ctrl-C during `wait`: its marker is gone, so the reviewer no longer sees the agent waiting.
+        if (e instanceof WaitCancelled) {
+            tell([failed(e.message), next(`baesian wait ${e.id}`, `to wait on ${e.id.includes(" ") ? "them" : "it"} again`)]);
+            return 130;
+        }
+        tell(failureLines(e));
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map