@codedology/code-forge 0.1.0

package/src/cli/block.mjs

@@ -0,0 +1,262 @@
+/**
+ * `code-forge block open|attempt|rebase|claim|close|stop` (plan §4.9). The skill calls
+ * `block open` before every spawn in every engine; it prints the brief pointer (≤ 200 bytes).
+ *
+ *   block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file>
+ *              [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <forecast>]
+ *   block attempt <id> --run <r>
+ *   block rebase <id> --run <r> [--head <ref>]
+ *   block claim <id> <path> --run <r>
+ *   block close <id> --run <r> [--worker-pid <pid>]
+ *   block stop <id> --run <r> --reason <text>
+ *   block waive <id> <finding-id> --run <r> --file <path> --reason <text>   (human-only, §4.9)
+ *
+ * `block close [--transcript <file>] [--no-require-reviews]` also runs B12b's review rows
+ * (`review/gate-check.mjs`): a signed `review.approved` row for the current content hash of every
+ * changed owned file (deletions included) — `--no-require-reviews` is the human's way out, is
+ * forbidden to coders (`mergeForbidden`), and leaves a signed `gate.reviews_waived {by: human}`
+ * row before the close (never a silent skip); late findings ruled; `review_cap` findings waived; no
+ * `rule_break`, plus the transcript grep. The transcript is `--transcript`, else the block's
+ * `transcript` in the run record, else `.code-forge/runs/<run>/<block>.log`; none ⇒ a signed
+ * `gate.transcript_missing` row and a WARN line (never a silent pass, never a refusal). An id the
+ * run does not know is `unknown_block` before any check runs. B20: every changed owned file of
+ * tier `high` (§7.1: `proof.tiers.high.paths`, a recorded `risk ≥ 2`, or `security_sensitive`)
+ * needs a signed, proven red→green `proof` row (`checkBlockProof`), else `unproven <file>`; the
+ * human's way out is `block waive <id> proof --file <path>`. The high paths are the union of the
+ * `.code-forge.yml` at the block's base and the current one (`highPathsAt`); either that exists
+ * but does not load or validate refuses the close (a typo must never drop a high path), and a
+ * base that is missing or not a commit of the workspace refuses it too (`git-failed`).
+ *
+ * `--acceptance` is a YAML/JSON list of `{clause, tests: [test ids…]}`. `block close` runs B8's
+ * rows of the gate (worker pin, MACs, orphans); the gate rows owned by later blocks join it
+ * through `closeBlock`'s `extraChecks`.
+ */
+
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYAML } from 'yaml';
+import { appendRow, readAllRows } from '../ledger/write.mjs';
+import { attemptBlock, claimPath, closeBlock, openBlock, rebaseBlock, stopBlock } from '../state/block.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { findOverlap } from '../state/registry.mjs';
+import { readRun, writeSigned } from '../state/run.mjs';
+import { loadKey } from '../state/signer.mjs';
+import { blockFileSet, reviewGateCheck, waiveFinding } from '../review/gate-check.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { DEFAULT_CONFIG_FILENAME, loadProjectConfig } from '../config/load.mjs';
+import { validateConfig } from '../config/validate.mjs';
+import { migrateConfig } from '../config/migrate.mjs';
+import { exec } from '../util/exec.mjs';
+import { gitChildEnv } from '../worker/ticket.mjs';
+
+const USAGE =
+  'usage: code-forge block open <id> --run <r> --level L<n> --owned <paths…> --acceptance <file> [--brief <file>] [--attempt <n>] [--base <sha>] [--lines <n>]\n' +
+  '       code-forge block attempt|rebase|close <id> --run <r> · block claim <id> <path> --run <r> · block stop <id> --run <r> --reason <text>\n' +
+  '       code-forge block waive <id> <finding-id> --run <r> --file <path> --reason <text>\n';
+
+const SUBCOMMANDS = ['open', 'attempt', 'rebase', 'claim', 'close', 'stop', 'waive'];
+const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', 'lines', 'head', 'worker-pid', 'reason', 'file', 'transcript'];
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, probe?: import('../state/run.mjs').StartTimeProbe}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runBlock(args, deps = {}) {
+  const { stdout = process.stdout, stderr = process.stderr, probe } = deps;
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+  const [sub, ...rest] = args;
+  if (!SUBCOMMANDS.includes(sub)) {
+    err(USAGE);
+    return 2;
+  }
+  try {
+    const { flags, positionals } = parseFlags(rest, { values: FLAG_VALUES, multi: ['owned'], booleans: ['no-require-reviews'] });
+    const [id, extra] = positionals;
+    const runId = typeof flags.run === 'string' ? flags.run : undefined;
+    if (!id || !runId) throw new StateError('usage', 'a block id and --run are required');
+    if (sub === 'open' && (typeof flags.acceptance !== 'string' || !Array.isArray(flags.owned) || typeof flags.level !== 'string')) {
+      throw new StateError('usage', 'block open needs --level, --owned and --acceptance');
+    }
+    if (sub === 'claim' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block claim needs exactly one path');
+    if ((sub === 'stop' || sub === 'waive') && typeof flags.reason !== 'string') throw new StateError('usage', `block ${sub} needs --reason`);
+    if (sub === 'waive' && (!extra || positionals.length !== 2)) throw new StateError('usage', 'block waive needs exactly one finding id');
+    if (sub === 'waive' && typeof flags.file !== 'string') throw new StateError('usage', 'block waive needs --file <path> (a finding id is scoped to one file)');
+    const record = await readRun(runId);
+    const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
+
+    if (sub === 'open') {
+      const acceptance = parseYAML(await readFile(/** @type {string} */ (flags.acceptance), 'utf8'), { prettyErrors: false });
+      let brief;
+      if (typeof flags.brief === 'string') {
+        const absolute = await realpath(flags.brief);
+        const relative = path.relative(record.workspace, absolute);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) throw new StateError('usage', '--brief must be a file inside the workspace');
+        brief = { path: relative, content: await readFile(absolute) };
+      }
+      const { block, pointer } = await openBlock({
+        runId,
+        id,
+        level: /** @type {string} */ (flags.level),
+        owned: /** @type {string[]} */ (flags.owned),
+        acceptance,
+        attempt: intFlag(flags.attempt, 'attempt'),
+        base: typeof flags.base === 'string' ? flags.base : undefined,
+        lines: intFlag(flags.lines, 'lines') ?? null,
+        brief,
+        writeRow,
+      });
+      out(`block ${id} open · ${block.level} · attempt ${block.attempt} · base ${block.base_sha.slice(0, 12)}\n`);
+      out(`${pointer ?? 'brief: none given (--brief <file>)'}\n`);
+      return 0;
+    }
+    if (sub === 'attempt') {
+      out(`block ${id} attempt ${await attemptBlock({ runId, id, writeRow })}\n`);
+      return 0;
+    }
+    if (sub === 'rebase') {
+      const moved = await rebaseBlock({ runId, id, head: typeof flags.head === 'string' ? flags.head : undefined, writeRow });
+      out(`block ${id} rebased ${moved.old_base.slice(0, 12)} → ${moved.new_base.slice(0, 12)}\n`);
+      return 0;
+    }
+    if (sub === 'claim') {
+      await claimPath({ runId, id, file: extra, writeRow });
+      out(`block ${id} claimed ${extra}\n`);
+      return 0;
+    }
+    if (sub === 'stop') {
+      await stopBlock({ runId, id, reason: /** @type {string} */ (flags.reason), writeRow });
+      out(`block ${id} stopped\n`);
+      return 0;
+    }
+    if (sub === 'waive') {
+      await waiveFinding({ runId, id, finding: extra, reason: /** @type {string} */ (flags.reason), file: /** @type {string} */ (flags.file), writeRow });
+      out(`block ${id} waived ${extra} in ${flags.file} (by: human)\n`);
+      return 0;
+    }
+    if (sub === 'close') {
+      const entry = record.blocks?.[id];
+      if (!entry) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
+      const rows = (await readAllRows(record.project)).filter((row) => row.run === runId);
+      const reviewsWaived = flags['no-require-reviews'] === true;
+      const reviews = reviewGateCheck(async () => {
+        const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
+        if (transcript === null) {
+          await writeSigned(runId, writeRow, { event: 'gate.transcript_missing', block: id });
+          err(`WARN block ${id}: no coder transcript found (--transcript, run record, .code-forge/runs/${runId}/${id}.log); the transcript grep did not run\n`);
+        }
+        // the human's way out of the per-file review check leaves a signed audit row before the close
+        if (reviewsWaived) await writeSigned(runId, writeRow, { event: 'gate.reviews_waived', block: id, by: 'human' });
+        // B20: the high paths come first — a base the workspace does not know refuses the close here
+        const highPaths = await highPathsAt(record.workspace, entry.base_sha);
+        const fileSet = await blockFileSet({ repoRoot: record.workspace, base: entry.base_sha, owned: entry.owned_files, matchOwned: (f) => findOverlap(entry.owned_files, [f]) !== null });
+        return {
+          block: id,
+          runId,
+          rows,
+          key: await loadKey(runId),
+          transcript,
+          files: reviewsWaived ? [] : fileSet,
+          // B20: high-tier files need a proven red→green row; `--no-require-reviews` does not lift it
+          proofFiles: fileSet,
+          highPaths,
+        };
+      });
+      const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks: [reviews] });
+      (result.ok ? out : err)(`block ${id} ${result.status}${result.event ? ` (${result.event})` : ''}${result.reason ? `: ${result.reason}` : ''}\n`);
+      return result.ok ? 0 : 1;
+    }
+  } catch (thrown) {
+    err(`block ${sub ?? ''}: ${thrown?.message ?? String(thrown)}\n`);
+    return thrown instanceof StateError && thrown.code === 'usage' ? 2 : 1;
+  }
+  err(USAGE);
+  return 2;
+}
+
+/**
+ * The block's coder transcript: `--transcript`, else the run record's `blocks.<id>.transcript`
+ * (workspace-relative), else `.code-forge/runs/<run>/<id>.log`; null when none exists.
+ * @param {Record<string, any>} record @param {string} id @param {string | null} given
+ * @returns {Promise<string | null>}
+ */
+async function findTranscript(record, id, given) {
+  if (given !== null) return readFile(given, 'utf8');
+  const recorded = record.blocks?.[id]?.transcript;
+  const candidates = [
+    ...(typeof recorded === 'string' && recorded.length > 0 ? [path.resolve(record.workspace, recorded)] : []),
+    path.join(record.workspace, '.code-forge', 'runs', record.run_id, `${id}.log`),
+  ];
+  for (const file of candidates) {
+    try {
+      return await readFile(file, 'utf8');
+    } catch (thrown) {
+      if (/** @type {any} */ (thrown)?.code !== 'ENOENT') throw thrown;
+    }
+  }
+  return null;
+}
+
+/**
+ * The key paths of a config's validation errors (never values).
+ * @param {Record<string, any>} config @param {string} where
+ * @returns {string[]} `proof.tiers.high.paths`
+ * @throws {StateError} `bad-config`
+ */
+function validHighPaths(config, where) {
+  const result = validateConfig(config);
+  if (!result.valid) {
+    const at = [...new Set(result.errors.map((e) => (typeof e.path === 'string' ? e.path : e.rule)))].join(', ');
+    throw new StateError('bad-config', `${where} is invalid (${result.errors.length} error(s) at ${at}) — run code-forge validate`);
+  }
+  const paths = config?.proof?.tiers?.high?.paths;
+  return Array.isArray(paths) ? paths.filter((p) => typeof p === 'string') : [];
+}
+
+/**
+ * B20: `proof.tiers.high.paths` for the close — the UNION of the `.code-forge.yml` committed at
+ * the block's base (read with `git show <base>:.code-forge.yml`, argv only, GIT_* stripped) and
+ * the one in the working tree, so a coder that edits or deletes the high paths in its block can
+ * only ever add to them. Fails closed on the base: a base that is not a non-empty string, or that
+ * `git rev-parse --verify` does not know as a commit, refuses the close (`git-failed`), and so does
+ * any git call that times out, fails to spawn or exits non-zero. The base config counts as absent
+ * ONLY when a clean `git ls-tree <base> -- .code-forge.yml` lists nothing; the current config may
+ * be absent too. A side that exists but does not load or validate refuses the close (key paths
+ * only, never values).
+ * @param {string} workspace @param {string | undefined} base
+ * @returns {Promise<string[]>}
+ * @throws {StateError} `bad-config`, `git-failed`
+ */
+export async function highPathsAt(workspace, base) {
+  if (typeof base !== 'string' || base.length === 0 || base.startsWith('-')) throw new StateError('git-failed', 'the block has no base commit — the close cannot read the base config');
+  const paths = new Set();
+  const loaded = await loadProjectConfig(workspace);
+  if (loaded.ok && loaded.config) for (const p of validHighPaths(loaded.config, DEFAULT_CONFIG_FILENAME)) paths.add(p);
+  else if (loaded.error !== 'not-found') throw new StateError('bad-config', `${DEFAULT_CONFIG_FILENAME} does not load (${loaded.error ?? 'no config'}) — run code-forge validate`);
+
+  const git = { cwd: workspace, env: gitChildEnv(), timeoutMs: 30000 };
+  const known = await exec(['git', 'rev-parse', '--verify', '--quiet', `${base}^{commit}`], git);
+  if (known.result !== 'ok') throw new StateError('git-failed', 'the block base is not a commit of the workspace — the close cannot read the base config');
+  const listed = await exec(['git', 'ls-tree', base, '--', DEFAULT_CONFIG_FILENAME], git);
+  if (listed.result !== 'ok') throw new StateError('git-failed', `git could not check for ${DEFAULT_CONFIG_FILENAME} at the block base`);
+  if (listed.stdout.trim().length === 0) return [...paths]; // a clean git said the base has no config
+  const spec = `${base}:${DEFAULT_CONFIG_FILENAME}`;
+  const shown = await exec(['git', 'show', spec], git);
+  if (shown.result !== 'ok') throw new StateError('git-failed', `git could not read ${DEFAULT_CONFIG_FILENAME} at the block base`);
+  const where = `${DEFAULT_CONFIG_FILENAME} at the block base`;
+  let parsed;
+  try {
+    parsed = migrateConfig(parseYAML(shown.stdout, { prettyErrors: false }));
+  } catch {
+    throw new StateError('bad-config', `${where} does not load — run code-forge validate`);
+  }
+  for (const p of validHighPaths(parsed, where)) paths.add(p);
+  return [...paths];
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function block(args) {
+  return runBlock(args);
+}

package/src/cli/doctor.mjs

@@ -0,0 +1,74 @@
+/**
+ * `code-forge doctor [--quick] [--json] [--cwd <dir>]` (plan §2.3; block B13b).
+ *
+ * Prints one row per check (`<STATUS> <label>: <detail>`) on stdout, or with `--json` ONE JSON
+ * document `{ok, counts, rows}`; a one-line summary goes to stderr. Exit 0 when no row FAILs,
+ * 1 when one does, 2 on a usage error. The full run adopts a private temp root for its probes
+ * (every child it spawns is registered there) and removes it before exiting.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { runDoctor } from '../doctor/index.mjs';
+import { counts, exitCode, renderJSON, renderText } from '../doctor/rows.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { runRoot, setRunRoot } from '../util/tmp.mjs';
+
+const USAGE = 'usage: code-forge doctor [--quick] [--json] [--cwd <dir>]\n';
+
+/**
+ * @param {string[]} args
+ * @param {import('../doctor/index.mjs').DoctorDeps & {stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @param {boolean} [adopt] - the real verb: adopt one temp root so exec registers every probe
+ *   child there (in-process callers keep their own run root).
+ * @returns {Promise<number>}
+ */
+export async function runDoctorCli(args, deps = {}, adopt = false) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  let parsed;
+  try {
+    parsed = parseFlags(args, { values: ['cwd'], booleans: ['quick', 'json'] });
+  } catch (err) {
+    writeSafe(stderr, `doctor: ${err.message}\n${USAGE}`);
+    return 2;
+  }
+  if (parsed.positionals.length > 0) {
+    writeSafe(stderr, USAGE);
+    return 2;
+  }
+  const { flags } = parsed;
+  const cwd = path.resolve(typeof flags.cwd === 'string' ? flags.cwd : process.cwd());
+  /** @type {string | undefined} */
+  let root;
+  if (adopt && !flags.quick) {
+    const loaded = await loadProjectConfig(cwd);
+    const tmpRoot = loaded.ok && typeof loaded.config?.tmp?.root === 'string' ? loaded.config.tmp.root : undefined;
+    try {
+      root = runRoot(`doctor-${process.pid}-${randomBytes(3).toString('hex')}`, { root: tmpRoot });
+      setRunRoot(root);
+    } catch {
+      root = undefined; // runDoctor reports the missing temp root as a FAIL row
+    }
+  }
+  try {
+    const rows = await runDoctor({ cwd, quick: flags.quick === true, ...(root ? { runRootDir: root } : {}) }, deps);
+    writeSafe(stdout, flags.json ? renderJSON(rows) : renderText(rows));
+    const c = counts(rows);
+    writeSafe(stderr, `doctor: ${c.OK} ok, ${c.WARN} warn, ${c.FAIL} fail\n`);
+    return exitCode(rows);
+  } finally {
+    if (root) {
+      setRunRoot(null);
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function doctor(args) {
+  return runDoctorCli(args, {}, true);
+}

package/src/cli/facts.mjs

@@ -0,0 +1,124 @@
+/**
+ * `code-forge facts --brief <file> [--sources <path>…] [--out <file>] [--run <id>] [--timeout <s>]`
+ * (plan §3.8 step 1–3; block B9b). Builds the facts sheet: claim tokens, one L0 read-only delegate
+ * session (run in a read-only snapshot of the project at HEAD plus the in-project `--sources`,
+ * B9b.1), validation, render. Default `--out`: `<project.plans_dir | plans>/<brief name>.facts.md`.
+ * Exit codes: 0 written, 1 the session failed, the answer was refused, a file vanished mid-run or
+ * the run raised a `SessionError`, 2 usage (only pre-run argument errors: flags, config, an
+ * unreadable `--brief` / `--sources`, a bad `--run` id), 3 L0 and every fallback unavailable
+ * (`exitCodeFor`).
+ */
+
+import { accessSync, constants, statSync } from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { buildFacts, FactsError } from '../session/facts.mjs';
+import { runRootFor, SessionError } from '../session/spawn.mjs';
+import { intFlag, parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
+import { exitCodeFor } from './spawn.mjs';
+
+/**
+ * @param {string} file @param {{fileOnly?: boolean}} [opts] - `fileOnly`: a directory does not count.
+ * @returns {boolean} a readable file (or directory, unless `fileOnly`).
+ */
+function readable(file, { fileOnly = false } = {}) {
+  try {
+    accessSync(file, constants.R_OK);
+    const st = statSync(file);
+    return fileOnly ? st.isFile() : st.isFile() || st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+const USAGE = 'usage: code-forge facts --brief <file> [--sources <path>...] [--out <file>] [--run <id>] [--timeout <seconds>]\n';
+
+/**
+ * @param {string[]} args
+ * @param {import('../session/spawn.mjs').SessionDeps & {stdout?: {write: (s: string) => unknown}, cwd?: string}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runFactsVerb(args, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const cwd = deps.cwd ?? process.cwd();
+  try {
+    const { flags, positionals } = parseFlags(args, { values: ['brief', 'out', 'run', 'timeout'], multi: ['sources'] });
+    if (positionals.length > 0 || typeof flags.brief !== 'string') {
+      writeSafe(stderr, USAGE);
+      return 2;
+    }
+    const loaded = await loadProjectConfig(cwd);
+    if (!loaded.ok) {
+      writeSafe(stderr, `facts: ${loaded.message}\n`);
+      return 2;
+    }
+    const cfg = /** @type {Record<string, any>} */ (loaded.config);
+    const briefPath = path.resolve(cwd, flags.brief);
+    const plansDir = path.resolve(cwd, cfg.project?.plans_dir ?? 'plans');
+    const outPath = typeof flags.out === 'string' ? path.resolve(cwd, flags.out) : path.join(plansDir, `${path.basename(briefPath, path.extname(briefPath))}.facts.md`);
+    const sources = Array.isArray(flags.sources) ? flags.sources.map((s) => path.resolve(cwd, s)) : [];
+    // --brief must be a regular file; a --sources path may be a file or a directory
+    if (!readable(briefPath, { fileOnly: true })) {
+      writeSafe(stderr, 'facts: --brief cannot be read\n');
+      return 2;
+    }
+    for (const source of sources) {
+      if (!readable(source)) {
+        writeSafe(stderr, 'facts: --sources path cannot be read\n');
+        return 2;
+      }
+    }
+    const timeout = intFlag(flags.timeout, 'timeout');
+    const run = typeof flags.run === 'string' ? flags.run : undefined;
+    // pre-run argument checks: a bad --run id or an unusable project state is usage (exit 2)
+    const runRoot = run ? runRootFor(run, cfg?.tmp?.root) : undefined;
+    const slug = slugFor(cfg, cwd);
+    let result;
+    try {
+      result = await buildFacts(
+        { cfg, briefPath, sources, outPath, run, runRoot, slug, projectDir: cwd, timeoutMs: timeout === undefined ? undefined : timeout * 1000 },
+        { ...deps, stderr },
+      );
+    } catch (err) {
+      if (err instanceof FactsError) {
+        writeSafe(stderr, `facts: ${err.message}\n`);
+        return 1;
+      }
+      if (err instanceof SessionError) {
+        // raised by the run, not by the arguments: a session failure (3 only when it says unavailable)
+        writeSafe(stderr, `facts: ${err.message}\n`);
+        return exitCodeFor({ status: err.code === 'unavailable' ? 'unavailable' : 'failed' });
+      }
+      const e = /** @type {NodeJS.ErrnoException} */ (err);
+      if (e.code === 'ENOENT' || e.code === 'EACCES' || e.code === 'EISDIR') {
+        // the inputs were readable files a moment ago (checked above): this is a run failure, not usage
+        const kind = e.path === briefPath ? 'the brief' : sources.includes(e.path ?? '') ? 'a source' : 'a working file';
+        writeSafe(stderr, `facts: ${kind} could not be read while building the sheet (${e.code})\n`);
+        return 1;
+      }
+      throw err;
+    }
+    if (result.status !== 'ok') {
+      writeSafe(stderr, `facts: ${result.status}${result.reason ? ` (${result.reason})` : ''}\n`);
+      return exitCodeFor(result);
+    }
+    const facts = result.facts ?? [];
+    writeSafe(stdout, `${JSON.stringify({ out: outPath, claims: result.claims.length, verified: facts.filter((f) => f.tag === 'VERIFIED').length })}\n`);
+    return 0;
+  } catch (err) {
+    if (err instanceof StateError || err instanceof SessionError) {
+      writeSafe(stderr, `facts: ${/** @type {Error} */ (err).message}\n`);
+      return 2;
+    }
+    throw err;
+  }
+}
+
+/** @param {string[]} args */
+export default async function factsVerb(args) {
+  return runFactsVerb(args);
+}