@codedology/code-forge 0.1.0

package/src/cli/gates.mjs

@@ -0,0 +1,280 @@
+/**
+ * `code-forge gates detect|run|secret-scan|safe-edit|scope|acceptance|transcript-grep` (plan
+ * §2.2, §4.6, §8.6). Every subcommand prints one JSON object (redacted — `redactJSON`) to stdout
+ * and returns a process exit code: `0` gate green/check passed, `1` gate red/check failed,
+ * `2` usage error.
+ *
+ *   gates detect --cwd <dir>
+ *   gates run --cwd <dir> [--slug <slug>] [--timeout-ms <n>] [--run <r> --block <id>]
+ *     (with --run/--block the gates run behind the proof lock, `runGatesGuarded`: another block
+ *     holding the lock ⇒ `{"result":"proof.busy","holder":…}` and exit 1)
+ *   gates secret-scan --cwd <dir> --file <path> [--file <path> ...]
+ *   gates safe-edit --cwd <dir> --base <sha>
+ *   gates scope --cwd <dir> --base <sha>
+ *   gates acceptance --clauses <file.json> --tap <file>
+ *   gates transcript-grep --file <path>
+ */
+
+import { readFile } from 'node:fs/promises';
+import { writeSafe, redactJSON } from '../util/redact.mjs';
+import { appendRow } from '../ledger/write.mjs';
+import { loadProjectConfig } from '../config/load.mjs';
+import { detectGates } from '../gates/detect.mjs';
+import { runGates } from '../gates/run.mjs';
+import { runGatesGuarded } from '../proof/lock.mjs';
+import { scanFiles } from '../gates/secret-scan.mjs';
+import { checkSafeEdit } from '../gates/safe-edit.mjs';
+import { computeFileSet } from '../gates/scope.mjs';
+import { checkAcceptance, parseTapPassed } from '../gates/acceptance.mjs';
+import { checkTranscript } from '../gates/transcript-grep.mjs';
+
+/**
+ * Auto-detected gates (`detectGates`), overridden per-key by an on-disk `.code-forge.yml`'s
+ * `gates.{test,lint,types,format}` when that key is explicitly present — a project that already
+ * confirmed/edited its gates at `init` step 7 (plan §2 step 7) is authoritative over the table.
+ * A missing/unparseable config file is not an error here: detection alone is a valid answer.
+ * @param {string} cwd
+ * @returns {Promise<import('../gates/detect.mjs').DetectedGates>}
+ */
+async function resolveGates(cwd) {
+  const detected = detectGates(cwd);
+  const loaded = await loadProjectConfig(cwd);
+  const configured = loaded.ok && loaded.config?.gates && typeof loaded.config.gates === 'object' ? loaded.config.gates : null;
+  if (!configured) return detected;
+  return {
+    stack: detected.stack,
+    test: 'test' in configured ? configured.test : detected.test,
+    lint: 'lint' in configured ? configured.lint : detected.lint,
+    types: 'types' in configured ? configured.types : detected.types,
+    format: 'format' in configured ? configured.format : detected.format,
+  };
+}
+
+/**
+ * `production.markers`/`production.names` from an on-disk config, merged into the forbidden list
+ * `transcript-grep` scans with — absent/unparseable config yields no extra tokens.
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+async function resolveProductionMarkers(cwd) {
+  const loaded = await loadProjectConfig(cwd);
+  if (!loaded.ok || !loaded.config?.production) return [];
+  const { markers, names } = loaded.config.production;
+  return [...(Array.isArray(markers) ? markers : []), ...(Array.isArray(names) ? names : [])];
+}
+
+/**
+ * @param {string[]} args @param {string} flag
+ * @returns {{ok: true, value: string|undefined} | {ok: false}} see `ledger.mjs`'s twin helper —
+ *   `ok: false` means the flag WAS given with no usable value (missing, or the next token is
+ *   itself another flag), which a caller must treat as a usage error rather than a silent default.
+ */
+function readOptionalFlag(args, flag) {
+  const i = args.indexOf(flag);
+  if (i < 0) return { ok: true, value: undefined };
+  const next = args[i + 1];
+  if (next === undefined || next.startsWith('--')) return { ok: false };
+  return { ok: true, value: next };
+}
+
+/** @param {string[]} args @param {string} flag @returns {string|undefined} */
+function flagValue(args, flag) {
+  const result = readOptionalFlag(args, flag);
+  return result.ok ? result.value : undefined;
+}
+
+/**
+ * Resolve `--cwd`, defaulting to `process.cwd()` ONLY when the flag is absent entirely. A flag
+ * given with no usable value (`--cwd` at the end of argv, or immediately followed by another
+ * flag) is a usage error, not a silent fallback to the wrong directory — every subcommand that
+ * reads files or runs commands against a project root depends on this (finding: `--cwd` used to
+ * go through `flagValue(...) ?? process.cwd()`, which cannot tell "absent" from "malformed" apart
+ * and silently ran gates in the wrong directory for the latter).
+ * @param {string[]} args @param {(s: string) => void} err @param {string} label
+ * @returns {{ok: true, value: string} | {ok: false}}
+ */
+function resolveCwd(args, err, label) {
+  const flag = readOptionalFlag(args, '--cwd');
+  if (!flag.ok) {
+    err(`${label}: --cwd requires a value\n`);
+    return { ok: false };
+  }
+  return { ok: true, value: flag.value ?? process.cwd() };
+}
+
+/** @param {string[]} args @param {string} flag @returns {string[]} every value of a repeatable flag. */
+function repeatedFlagValues(args, flag) {
+  const values = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === flag && i + 1 < args.length) values.push(args[i + 1]);
+  }
+  return values;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runGatesVerb(args, deps = {}) {
+  const { stdout = process.stdout, stderr = process.stderr } = deps;
+  const out = (/** @type {object} */ value) => writeSafe(stdout, `${redactJSON(value)}\n`);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+  const usage = () =>
+    err('usage: code-forge gates detect|run|secret-scan|safe-edit|scope|acceptance|transcript-grep --cwd <dir> [...]\n');
+
+  const [sub] = args;
+
+  try {
+    if (sub === 'detect') {
+      const cwdArg = resolveCwd(args, err, 'gates detect');
+      if (!cwdArg.ok) return 2;
+      out(await resolveGates(cwdArg.value));
+      return 0;
+    }
+
+    if (sub === 'run') {
+      const cwdArg = resolveCwd(args, err, 'gates run');
+      if (!cwdArg.ok) return 2;
+      const cwd = cwdArg.value;
+
+      const timeoutFlag = readOptionalFlag(args, '--timeout-ms');
+      if (!timeoutFlag.ok) {
+        err('gates run: --timeout-ms requires a value\n');
+        return 2;
+      }
+      const timeoutMs = timeoutFlag.value !== undefined ? Number(timeoutFlag.value) : undefined;
+      if (timeoutMs !== undefined && !(Number.isFinite(timeoutMs) && timeoutMs > 0)) {
+        err(`gates run: --timeout-ms must be a finite number > 0, got "${timeoutFlag.value}"\n`);
+        return 2;
+      }
+
+      // `--slug` has no sensible default (unlike `--cwd`): given-but-malformed must refuse, not
+      // silently run the gates while dropping every ledger row on the floor.
+      const slugFlag = readOptionalFlag(args, '--slug');
+      if (!slugFlag.ok) {
+        err('gates run: --slug requires a value\n');
+        return 2;
+      }
+      const slug = slugFlag.value;
+
+      const runFlag = readOptionalFlag(args, '--run');
+      const blockFlag = readOptionalFlag(args, '--block');
+      if (!runFlag.ok || !blockFlag.ok || (runFlag.value === undefined) !== (blockFlag.value === undefined)) {
+        err('gates run: --run <id> and --block <id> go together, each with a value\n');
+        return 2;
+      }
+
+      const gates = await resolveGates(cwd);
+      let ran;
+      if (runFlag.value !== undefined && blockFlag.value !== undefined) {
+        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates, cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+        if (guarded.result === 'proof.busy') {
+          out({ result: 'proof.busy', holder: /** @type {{holder: string}} */ (guarded).holder });
+          return 1;
+        }
+        ran = /** @type {{value: {results: any[], allOk: boolean}}} */ (guarded).value;
+      } else {
+        ran = await runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+      }
+      const { results, allOk } = ran;
+
+      if (slug) {
+        for (const result of results) {
+          if (!result.skipped && !result.ok) {
+            await appendRow({ event: 'gate.red', gate: result.gate, code: result.code }, { slug });
+          }
+        }
+        await appendRow({ event: 'gate.done', stack: gates.stack, all_ok: allOk }, { slug });
+      }
+      out({ stack: gates.stack, results, allOk });
+      return allOk ? 0 : 1;
+    }
+
+    if (sub === 'secret-scan') {
+      const cwdArg = resolveCwd(args, err, 'gates secret-scan');
+      if (!cwdArg.ok) return 2;
+      const files = repeatedFlagValues(args, '--file');
+      if (files.length === 0) {
+        err('gates secret-scan: at least one --file <path> is required\n');
+        return 2;
+      }
+      const hits = await scanFiles(cwdArg.value, files);
+      out({ hits, count: hits.length });
+      return hits.length === 0 ? 0 : 1;
+    }
+
+    if (sub === 'safe-edit') {
+      const cwdArg = resolveCwd(args, err, 'gates safe-edit');
+      if (!cwdArg.ok) return 2;
+      const base = flagValue(args, '--base');
+      if (!base) {
+        err('gates safe-edit: --base <sha> is required\n');
+        return 2;
+      }
+      const result = await checkSafeEdit({ cwd: cwdArg.value, base });
+      out(result);
+      return result.ok ? 0 : 1;
+    }
+
+    if (sub === 'scope') {
+      const cwdArg = resolveCwd(args, err, 'gates scope');
+      if (!cwdArg.ok) return 2;
+      const base = flagValue(args, '--base');
+      if (!base) {
+        err('gates scope: --base <sha> is required\n');
+        return 2;
+      }
+      const fileSet = await computeFileSet({ cwd: cwdArg.value, base });
+      out(fileSet);
+      return 0;
+    }
+
+    if (sub === 'acceptance') {
+      const clausesPath = flagValue(args, '--clauses');
+      const tapPath = flagValue(args, '--tap');
+      if (!clausesPath || !tapPath) {
+        err('gates acceptance: --clauses <file.json> and --tap <file> are required\n');
+        return 2;
+      }
+      const clauses = JSON.parse(await readFile(clausesPath, 'utf8'));
+      const tapOutput = await readFile(tapPath, 'utf8');
+      const { passed, failed } = parseTapPassed(tapOutput);
+      const result = checkAcceptance(clauses, passed, failed);
+      out(result);
+      return result.ok ? 0 : 1;
+    }
+
+    if (sub === 'transcript-grep') {
+      const filePath = flagValue(args, '--file');
+      if (!filePath) {
+        err('gates transcript-grep: --file <path> is required\n');
+        return 2;
+      }
+      // --cwd is OPTIONAL here (only used to pull in production.markers/names) — absent entirely
+      // means "no config lookup", but given-with-no-value is still a usage error, not silently
+      // treated the same as absent.
+      const cwdFlag = readOptionalFlag(args, '--cwd');
+      if (!cwdFlag.ok) {
+        err('gates transcript-grep: --cwd requires a value\n');
+        return 2;
+      }
+      const text = await readFile(filePath, 'utf8');
+      const extraTokens = cwdFlag.value ? await resolveProductionMarkers(cwdFlag.value) : [];
+      const result = checkTranscript(text, { extraTokens });
+      out(result);
+      return result.ok ? 0 : 1;
+    }
+  } catch (thrown) {
+    err(`gates ${sub}: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+
+  usage();
+  return 2;
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function gates(args) {
+  return runGatesVerb(args);
+}

package/src/cli/help.mjs

@@ -0,0 +1,48 @@
+/**
+ * `code-forge help` (also reached via `--help`/`-h`/no verb, aliased by `bin/code-forge.mjs`).
+ * Lists every discovered verb, one per line, each indented by exactly two spaces so a test (or a
+ * script) can count them reliably: `/^ {2}\S+$/`.
+ */
+
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * A verb file's basename must match this. Duplicated (not imported) from `bin/code-forge.mjs` —
+ * both B0-owned files must stay in sync since there is no shared-util file in B0's scope to hold
+ * this once.
+ */
+const VERB_FILE_PATTERN = /^[a-z][a-z0-9-]*\.mjs$/;
+
+/**
+ * Fallback discovery used only when this verb is called without the router's `context.verbs`
+ * (i.e. not through `bin/code-forge.mjs` — covered by the "help() with no context" test in
+ * `test/router.test.mjs`, so this path is exercised, not dead code).
+ * @returns {Promise<string[]>}
+ */
+async function discoverVerbs() {
+  const entries = await readdir(__dirname, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && VERB_FILE_PATTERN.test(entry.name))
+    .map((entry) => entry.name.slice(0, -'.mjs'.length))
+    .sort();
+}
+
+/**
+ * @param {string[]} _args
+ * @param {{verbs?: string[]}} [context] - the router already knows the verb list; reuse it when
+ *   present instead of reading the directory a second time.
+ * @returns {Promise<number>}
+ */
+export default async function help(_args, context = {}) {
+  const verbs = context.verbs ?? (await discoverVerbs());
+  process.stdout.write('Usage: code-forge <verb> [args]\n\n');
+  process.stdout.write('Verbs:\n');
+  for (const verb of verbs) {
+    process.stdout.write(`  ${verb}\n`);
+  }
+  return 0;
+}

package/src/cli/init.mjs

@@ -0,0 +1,14 @@
+/**
+ * `code-forge init` — the setup wizard (plan §2; block B13a). The wizard lives in
+ * `src/install/wizard/`; this verb only hands it the process's argv and streams.
+ */
+
+import { runInit } from '../install/wizard/run.mjs';
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function init(args) {
+  return runInit(args);
+}

package/src/cli/jev.mjs

@@ -0,0 +1,175 @@
+/**
+ * `code-forge jev ask <question-id> --state <file>` (plan §3.2, B3's row in §10.3). A direct,
+ * single-question call to Jev — the debugging/manual-use entry point, not the orchestrator's own
+ * decision pipeline (that lives inside B9's session runner and B12's review engine, which import
+ * `src/decide/**` directly rather than shelling out to this verb).
+ *
+ *   jev ask <id> --state <file.json> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]
+ *
+ * Resolves the Jev key through B2's chain (`resolveKey`, earlier batch — the seam rule allows a
+ * Wave 1 module to import a block in an earlier batch statically), asks Jev, runs the answer
+ * through `thresholds.decide()`, and appends one `{event: 'decision', ...}` row through B6's
+ * writer (also an earlier batch) — the shape `ledger/calibration.mjs` already expects:
+ * `decision_id`, `question`, `confidence` (plan §6.3's calibration buckets read exactly these).
+ *
+ * Never prints the key: it only ever reaches the `Authorization` header inside `askJev`, and
+ * `resolveKey` has already registered it with `redact()` before this module sees it.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { loadConfigFile, DEFAULT_CONFIG_FILENAME } from '../config/load.mjs';
+import path from 'node:path';
+import { buildQuestionPayload, isKnownQuestion, isQuestionDisabled } from '../decide/questions.mjs';
+import { askJev as realAskJev } from '../decide/jev-client.mjs';
+import { decide } from '../decide/thresholds.mjs';
+import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
+import { appendRow as realAppendRow } from '../ledger/write.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge jev ask <question-id> --state <file> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]\n';
+
+/**
+ * @param {string[]} args @param {string} flag
+ * @returns {{ok: true, value: string|undefined} | {ok: false}} same "flag given with no usable
+ *   value is a usage error" contract as `ledger.mjs`'s `readOptionalFlag` — a bare `--slug --cwd x`
+ *   must never silently read `--cwd` as `--slug`'s value.
+ */
+function readOptionalFlag(args, flag) {
+  const i = args.indexOf(flag);
+  if (i < 0) return { ok: true, value: undefined };
+  const next = args[i + 1];
+  if (next === undefined || next.startsWith('--')) return { ok: false };
+  return { ok: true, value: next };
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} deps
+ * @param {import('../keys/store.mjs').KeyStore} [deps.store]
+ * @param {typeof loadConfigFile} [deps.loadConfig]
+ * @param {typeof realAskJev} [deps.askJev]
+ * @param {typeof realAppendRow} [deps.appendRow]
+ * @param {{write: (s: string) => unknown}} [deps.stdout]
+ * @param {{write: (s: string) => unknown}} [deps.stderr]
+ * @param {NodeJS.ProcessEnv} [deps.env]
+ * @param {() => number} [deps.now]
+ * @param {() => string} [deps.makeId]
+ * @returns {Promise<number>}
+ */
+export async function runJev(args, deps = {}) {
+  const {
+    store,
+    loadConfig = loadConfigFile,
+    askJev: ask = realAskJev,
+    appendRow: write = realAppendRow,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    env = process.env,
+    now = Date.now,
+    makeId = randomUUID,
+  } = deps;
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  const [sub, id] = args;
+  if (sub !== 'ask' || typeof id !== 'string' || id.startsWith('--')) {
+    err(USAGE);
+    return 2;
+  }
+  if (!isKnownQuestion(id)) {
+    err(`jev ask: unknown question id "${id}"\n`);
+    return 2;
+  }
+
+  const stateFlag = readOptionalFlag(args, '--state');
+  const cwdFlag = readOptionalFlag(args, '--cwd');
+  const slugFlag = readOptionalFlag(args, '--slug');
+  const keyRefFlag = readOptionalFlag(args, '--key-ref');
+  if (!stateFlag.ok || !cwdFlag.ok || !slugFlag.ok || !keyRefFlag.ok || !stateFlag.value) {
+    err(USAGE);
+    return 2;
+  }
+  const cwd = cwdFlag.value ?? process.cwd();
+
+  let state;
+  try {
+    state = JSON.parse(await readFile(path.resolve(cwd, stateFlag.value), 'utf8'));
+  } catch (thrown) {
+    err(`jev ask: could not read --state file: ${thrown?.code ?? thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+
+  const configPath = path.join(cwd, DEFAULT_CONFIG_FILENAME);
+  const loaded = await loadConfig(configPath);
+  let cfg = {};
+  if (loaded.ok) {
+    cfg = loaded.config;
+  } else if (loaded.error !== 'not-found') {
+    err(`jev ask: ${loaded.message}\n`);
+    return 1;
+  }
+
+  if (isQuestionDisabled(id, cfg)) {
+    err(`jev ask: question "${id}" is disabled by system1.disable\n`);
+    return 1;
+  }
+
+  const keyStore = store ?? (await createDefaultKeyStore(env));
+  const keyRef = keyRefFlag.value ?? cfg?.keys?.jev;
+  let resolved;
+  try {
+    resolved = await resolveKey('jev', { store: keyStore, ref: keyRef, env, now: now() });
+  } catch (thrown) {
+    err(`jev ask: ${thrown?.message ?? String(thrown)}\n`);
+    return 2;
+  }
+  if (resolved.value === null) {
+    for (const reason of resolved.errors) {
+      err(`jev ask: ${reason}\n`);
+    }
+    err('jev ask: no Jev key resolved (set one with "code-forge keys set jev")\n');
+    return 1;
+  }
+
+  const questions = buildQuestionPayload([id], cfg);
+  const result = await ask({ state, questions, key: resolved.value });
+  if (!result.ok) {
+    const failure = /** @type {import('../decide/jev-client.mjs').JevFailure} */ (result);
+    err(`jev ask: request failed (${failure.kind}${failure.status ? `, status ${failure.status}` : ''})\n`);
+    return 1;
+  }
+
+  const answer = result.answers[id];
+  if (!answer) {
+    err(`jev ask: Jev did not answer question "${id}"\n`);
+    return 1;
+  }
+  const decision = decide(id, answer, cfg);
+  const slug = slugFlag.value ?? cfg?.project?.slug ?? 'code-forge';
+  const decisionId = makeId();
+
+  await write(
+    {
+      event: 'decision',
+      decision_id: decisionId,
+      question: id,
+      answer: decision.value,
+      stage: decision.stage,
+      confidence: decision.confidence,
+      margin: decision.margin,
+      source: 'jev',
+      tokens_in: result.usage?.input_tokens,
+      tokens_out: result.usage?.output_tokens,
+    },
+    { slug },
+  );
+
+  out(`${JSON.stringify({ decision_id: decisionId, question: id, answer, decision }, null, 2)}\n`);
+  return 0;
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function jev(args) {
+  return runJev(args, {});
+}

package/src/cli/keys.mjs

@@ -0,0 +1,170 @@
+/**
+ * `code-forge keys set|list|test|remove` (plan §8.1). No subcommand ever prints a key value:
+ * `list` shows name, source, backend and expiry from the store's index; `test` reports where a
+ * key resolved from. Every write goes through `writeSafe`, so even a value that slipped into a
+ * message would be masked once the chain registered it.
+ *
+ *   keys list
+ *   keys set <name> [--op <op://ref>]    hidden prompt, or read once from 1Password and cache 8 h
+ *   keys test <name> [--ref <ref>]       resolve through the chain (no prompt)
+ *   keys remove <name>
+ *
+ * Every name is validated before any store call, on every subcommand.
+ */
+
+import { writeSafe } from '../util/redact.mjs';
+import { isOpRef } from '../keys/onepassword.mjs';
+import { assertKeyName, createDefaultKeyStore, parseRef, readOpAndCache, resolveKey } from '../keys/store.mjs';
+
+const USAGE = 'usage: code-forge keys list | set <name> [--op <ref>] | test <name> [--ref <ref>] | remove <name>\n';
+
+/** The one flag each subcommand accepts (list and remove take none). */
+const FLAGS = /** @type {Record<string, string|null>} */ ({ list: null, set: '--op', test: '--ref', remove: null });
+
+/**
+ * @param {number|null} exp
+ * @param {number} now
+ * @returns {string}
+ */
+export function formatExpiry(exp, now) {
+  if (exp === null) {
+    return 'never';
+  }
+  return exp <= now ? 'expired' : new Date(exp).toISOString();
+}
+
+/**
+ * Strict parse: `<sub> [<name>] [<flag> <value>]`, in that order. A flag with no value, a value
+ * that looks like a flag, a name that looks like a flag, an unknown flag or an extra argument is
+ * a usage error — never silently reinterpreted.
+ * @param {string[]} args
+ * @returns {{sub: string, name?: string, flagArg?: string} | null}
+ */
+export function parseKeysArgs(args) {
+  const [sub, ...rest] = args;
+  if (typeof sub !== 'string' || !Object.hasOwn(FLAGS, sub)) {
+    return null;
+  }
+  if (sub === 'list') {
+    return rest.length === 0 ? { sub } : null;
+  }
+  const [name, flagName, flagArg, ...extra] = rest;
+  if (typeof name !== 'string' || name.startsWith('-') || extra.length > 0) {
+    return null;
+  }
+  if (flagName === undefined) {
+    return { sub, name };
+  }
+  if (flagName !== FLAGS[sub] || typeof flagArg !== 'string' || flagArg.length === 0 || flagArg.startsWith('-')) {
+    return null;
+  }
+  return { sub, name, flagArg };
+}
+
+/** @param {string} name */
+async function askHidden(name) {
+  const { password, isCancel } = await import('@clack/prompts');
+  const typed = await password({ message: `Value for key "${name}" (input hidden)` });
+  return isCancel(typed) ? null : String(typed);
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} deps
+ * @param {import('../keys/store.mjs').KeyStore} deps.store
+ * @param {{write: (s: string) => unknown}} [deps.stdout]
+ * @param {{write: (s: string) => unknown}} [deps.stderr]
+ * @param {(name: string) => Promise<string|null>} [deps.ask]
+ * @param {typeof import('../keys/onepassword.mjs').opRead} [deps.opRead]
+ * @param {NodeJS.ProcessEnv} [deps.env]
+ * @param {number} [deps.now]
+ * @returns {Promise<number>}
+ */
+export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, env = process.env, now = Date.now() }) {
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  const parsed = parseKeysArgs(args);
+  if (!parsed) {
+    err(USAGE);
+    return 2;
+  }
+  const { sub, name, flagArg } = parsed;
+  try {
+    if (name !== undefined) {
+      assertKeyName(name);
+    }
+    if (sub === 'test' && flagArg !== undefined) {
+      parseRef(name, flagArg);
+    }
+  } catch (e) {
+    err(`keys: ${e.message}\n`);
+    return 2;
+  }
+  if (sub === 'set' && flagArg !== undefined && !isOpRef(flagArg)) {
+    err(`${name}: --op must be an op://vault/item/field reference\n`);
+    return 2;
+  }
+
+  if (store.warning) {
+    err(`WARN ${store.warning}\n`);
+  }
+
+  if (sub === 'list') {
+    const rows = await store.list();
+    out('NAME\tSOURCE\tBACKEND\tEXPIRES\n');
+    for (const row of rows) {
+      out(`${row.name}\t${row.source}\t${row.backend}\t${formatExpiry(row.exp, now)}\n`);
+    }
+    return 0;
+  }
+
+  if (sub === 'remove') {
+    const removed = await store.remove(name);
+    out(`removed ${name} (${removed} backend${removed === 1 ? '' : 's'})\n`);
+    return 0;
+  }
+
+  if (sub === 'test') {
+    const res = await resolveKey(name, { store, ref: flagArg, env, opRead, now });
+    for (const e of res.errors) {
+      err(`${name}: ${e}\n`);
+    }
+    if (res.value === null) {
+      err(`${name}: not found\n`);
+      return 1;
+    }
+    out(`${name}: ok source=${res.source} expires=${formatExpiry(res.exp, now)}\n`);
+    return 0;
+  }
+
+  if (flagArg !== undefined) {
+    const res = await readOpAndCache(name, flagArg, { store, opRead, now });
+    for (const e of res.errors) {
+      err(`${name}: ${e}\n`);
+    }
+    // A null value always carries at least one reason (`readOpAndCache` guarantees it).
+    if (res.value === null) {
+      return 1;
+    }
+    out(`stored ${name} in ${store.writer} (source=op, expires=${formatExpiry(res.exp, now)})\n`);
+    return 0;
+  }
+
+  const typed = await ask(name);
+  if (typeof typed !== 'string' || typed.length === 0) {
+    err(`${name}: nothing stored\n`);
+    return 1;
+  }
+  await store.put(name, typed, { source: 'user', exp: null });
+  out(`stored ${name} in ${store.writer} (source=user, expires=never)\n`);
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function keys(args) {
+  return runKeys(args, { store: await createDefaultKeyStore() });
+}