@codedology/code-forge 0.1.0

package/src/cli/proof.mjs

@@ -0,0 +1,316 @@
+/**
+ * `code-forge proof tier|export|lock|unlock|baseline|restore` (plan §7, §4.7). Prints one JSON
+ * object (redacted) per call. Exit codes: 0 done, 1 refused (`proof.busy`, not the holder, bad
+ * ref…), 2 usage or a subcommand that has not landed.
+ *
+ *   proof tier --file <path> --risk <0-3> [--security] [--cwd <dir>]
+ *   proof export <block> --run <r> [--remove]
+ *   proof lock <block> --run <r>
+ *   proof unlock <block> --run <r>
+ *   proof baseline            (held on Q16 — block B10c)
+ *   proof restore <block> --run <r>   (the red→green journal, B10b: restores the block's export
+ *                             and the workspace; refuses with exit 1 when neither holds a journal)
+ *   proof red-green <block> --run <r> --test <file[::case]> [--mechanism revert|assertion-deletion]
+ *                             (B17: one red→green proof through `runRedGreen`, measured in a
+ *                             freshly built export — or in the workspace under `proof lock`,
+ *                             which this block must hold; exit 0 proven, 1 not proven or refused).
+ *                             The signed row carries `covers` (B20): the reverted sources, or
+ *                             the test file for `assertion-deletion`.
+ *
+ * `export` reads `proof.export.{link_dirs,copy_untracked}` from the workspace's `.code-forge.yml`
+ * (defaults §1.3) and writes a signed `proof` row `isolation: export`; `lock`/`unlock` write
+ * `isolation: lock` rows (B6 writer, B8 signer).
+ */
+
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_CONFIG_FILENAME, loadProjectConfig } from '../config/load.mjs';
+import { validateConfig } from '../config/validate.mjs';
+import { appendRow } from '../ledger/write.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { redactJSON, writeSafe } from '../util/redact.mjs';
+import { DEFAULT_COPY_UNTRACKED, DEFAULT_LINK_DIRS, buildExport, exportDirFor, recordProof, removeExport } from '../proof/export.mjs';
+import { acquireProofLock, lockHolder, releaseProofLock } from '../proof/lock.mjs';
+import { MECHANISMS, readJournal, restoreJournal, runRedGreen } from '../proof/red-green.mjs';
+import { tierFor } from '../proof/tiers.mjs';
+import { blockFileSet, repoRelativePath } from '../review/gate-check.mjs';
+import { findOverlap } from '../state/registry.mjs';
+
+const USAGE =
+  'usage: code-forge proof tier --file <path> --risk <0-3> [--security] [--cwd <dir>]\n' +
+  '       code-forge proof export <block> --run <r> [--remove] · proof lock|unlock <block> --run <r>\n' +
+  '       code-forge proof restore <block> --run <r>\n' +
+  '       code-forge proof red-green <block> --run <r> --test <file[::case]> [--mechanism revert|assertion-deletion]\n';
+
+/** A test file by path convention: never reverted as a "source" by the `revert` mechanism. */
+const TEST_PATH = /(?:^|\/)(?:test|tests|__tests__|spec)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|Test\.php$/;
+
+/** The JavaScript-family test files the filtered command below knows how to run. */
+const NODE_TEST_FILE = /\.(?:mjs|cjs|js)$/;
+
+/**
+ * `--test` as a repo-relative POSIX path: `./` segments dropped, never absolute, never escaping
+ * the repository with `..`, nothing under `.code-forge/`.
+ * @param {string} raw @returns {string}
+ * @throws {StateError} `usage`
+ */
+function normalizeTestPath(raw) {
+  if (raw.length === 0 || path.isAbsolute(raw) || raw.includes('\\') || raw.includes('\0')) throw new StateError('usage', '--test must be a repo-relative path');
+  const normalized = path.posix.normalize(raw);
+  if (normalized === '.' || normalized === '..' || normalized.startsWith('../')) throw new StateError('usage', '--test must stay inside the repository (no .. escape)');
+  if (normalized === '.code-forge' || normalized.startsWith('.code-forge/')) throw new StateError('usage', '--test cannot be under .code-forge/');
+  return normalized;
+}
+
+/**
+ * @param {string} dir - the work dir the test runs in @param {string} file - normalized, repo-relative
+ * @throws {StateError} `usage` when `file` is not a regular file under `dir`
+ */
+async function assertTestFile(dir, file) {
+  const st = await lstat(path.join(dir, file)).catch(() => null);
+  if (!st?.isFile()) throw new StateError('usage', `--test ${file} is not a file in ${dir}`);
+}
+
+/**
+ * The test command filtered to one test: `node --test [--test-name-pattern ^<case>$] <file>`, run
+ * with the Node that runs this CLI. Other stacks (Pest, Vitest…) have no filtered command here yet.
+ * @param {string} file @param {string | undefined} testCase
+ * @returns {string[]}
+ * @throws {StateError} `unsupported-test`
+ */
+function filteredTestArgv(file, testCase) {
+  if (!NODE_TEST_FILE.test(file)) throw new StateError('unsupported-test', 'only node:test files (.mjs, .cjs, .js) have a filtered test command in this version');
+  const pattern = testCase === undefined ? [] : ['--test-name-pattern', `^${testCase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`];
+  return [process.execPath, '--test', ...pattern, file];
+}
+
+const NOT_LANDED = {
+  baseline: 'proof baseline: held on Q16 (block B10c) — the gate enforces red→green only',
+};
+
+/** @param {Record<string, any>} config @returns {string[]} */
+const highPathsOf = (config) => (Array.isArray(config?.proof?.tiers?.high?.paths) ? config.proof.tiers.high.paths : []);
+
+/**
+ * The project config. `{}` (the §1.3 defaults apply) ONLY when no `.code-forge.yml` exists; a file
+ * that exists but does not load or validate is refused — a typo must never silently drop
+ * `proof.tiers.high.paths` (a tier downgrade), the `proof.isolation: lock` guard or the export
+ * lists. The message names the problem kind and key paths only, never values.
+ * @param {string} cwd
+ * @returns {Promise<Record<string, any>>}
+ * @throws {StateError} `bad-config`
+ */
+async function configAt(cwd) {
+  const loaded = await loadProjectConfig(cwd);
+  if (!loaded.ok && loaded.error === 'not-found') return {};
+  if (!loaded.ok || !loaded.config) {
+    throw new StateError('bad-config', `${DEFAULT_CONFIG_FILENAME} does not load (${loaded.error ?? 'no config'}) — run code-forge validate`);
+  }
+  const result = validateConfig(loaded.config);
+  if (!result.valid) {
+    const where = [...new Set(result.errors.map((e) => (typeof e.path === 'string' ? e.path : e.rule)))].join(', ');
+    throw new StateError('bad-config', `${DEFAULT_CONFIG_FILENAME} is invalid (${result.errors.length} error(s) at ${where}) — run code-forge validate`);
+  }
+  return loaded.config;
+}
+
+/**
+ * Build the block's measurement export and write its signed `proof` row (`step: export`).
+ * @param {{runId: string, record: Record<string, any>, blockId: string, block: Record<string, any>, config: Record<string, any>, writeRow: (row: Record<string, any>) => Promise<unknown>}} opts
+ */
+async function exportAndRecord({ runId, record, blockId, block, config, writeRow }) {
+  const exp = await buildExport({
+    cwd: record.workspace,
+    blockId,
+    baseSha: block.base_sha,
+    owned: block.owned_files,
+    linkDirs: config?.proof?.export?.link_dirs ?? DEFAULT_LINK_DIRS,
+    copyUntracked: config?.proof?.export?.copy_untracked ?? DEFAULT_COPY_UNTRACKED,
+  });
+  await recordProof({
+    runId,
+    writeRow,
+    row: { block: blockId, isolation: 'export', step: 'export', base_sha: exp.base, restored: exp.restored, untracked: exp.untracked },
+  });
+  return exp;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runProof(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 [sub, ...rest] = args;
+
+  if (typeof sub === 'string' && Object.hasOwn(NOT_LANDED, sub)) {
+    err(`${NOT_LANDED[/** @type {'baseline'} */ (sub)]}\n`);
+    return 2;
+  }
+  try {
+    if (sub === 'tier') {
+      const { flags, positionals } = parseFlags(rest, { values: ['file', 'risk', 'cwd'], booleans: ['security'] });
+      if (positionals.length > 0 || typeof flags.file !== 'string' || typeof flags.risk !== 'string') {
+        throw new StateError('usage', 'proof tier needs --file and --risk');
+      }
+      if (!/^[0-3]$/.test(flags.risk)) throw new StateError('usage', '--risk must be 0, 1, 2 or 3');
+      const config = await configAt(typeof flags.cwd === 'string' ? flags.cwd : process.cwd());
+      const result = tierFor({ file: flags.file, risk: Number(flags.risk), securitySensitive: flags.security === true, highPaths: highPathsOf(config) });
+      out({ file: flags.file, ...result });
+      return 0;
+    }
+
+    if (sub === 'restore') {
+      const { flags, positionals } = parseFlags(rest, { values: ['run'] });
+      const [blockId, extra] = positionals;
+      if (!blockId || extra !== undefined || typeof flags.run !== 'string') throw new StateError('usage', 'proof restore needs one block id and --run');
+      const record = await readRun(flags.run);
+      // The runner journals in the directory it measured in: the block's export, or the
+      // workspace itself under the proof lock.
+      const dirs = [exportDirFor(record.workspace, blockId), record.workspace];
+      const restored = [];
+      for (const workDir of dirs) {
+        if ((await readJournal(workDir)) === null) continue;
+        restored.push({ dir: workDir, files: (await restoreJournal({ workDir })).restored });
+      }
+      if (restored.length === 0) throw new StateError('no-journal', `no red→green journal for block ${blockId} — nothing to restore`);
+      out({ restored });
+      return 0;
+    }
+
+    if (sub === 'export' || sub === 'lock' || sub === 'unlock') {
+      const { flags, positionals } = parseFlags(rest, { values: ['run'], booleans: sub === 'export' ? ['remove'] : [] });
+      const [blockId, extra] = positionals;
+      if (!blockId || extra !== undefined || typeof flags.run !== 'string') throw new StateError('usage', `proof ${sub} needs one block id and --run`);
+      const runId = flags.run;
+      const record = await readRun(runId);
+      const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
+
+      if (sub === 'lock') {
+        out({ locked: await acquireProofLock({ runId, blockId, writeRow }) });
+        return 0;
+      }
+      if (sub === 'unlock') {
+        await releaseProofLock({ runId, blockId, writeRow });
+        out({ unlocked: blockId });
+        return 0;
+      }
+
+      const block = record.blocks?.[blockId];
+      if (block?.status !== 'open') throw new StateError('no-block', `block ${blockId} is not open in run ${runId}`);
+      if (flags.remove === true) {
+        await removeExport({ cwd: record.workspace, blockId });
+        out({ removed: blockId });
+        return 0;
+      }
+      const config = await configAt(record.workspace);
+      if (config?.proof?.isolation === 'lock') throw new StateError('isolation-lock', 'proof.isolation is lock — use proof lock instead of an export');
+      out(await exportAndRecord({ runId, record, blockId, block, config, writeRow }));
+      return 0;
+    }
+
+    if (sub === 'red-green') {
+      const { flags, positionals } = parseFlags(rest, { values: ['run', 'test', 'mechanism'] });
+      const [blockId, extra] = positionals;
+      if (!blockId || extra !== undefined || typeof flags.run !== 'string' || typeof flags.test !== 'string') {
+        throw new StateError('usage', 'proof red-green needs one block id, --run and --test <file[::case]>');
+      }
+      const mechanism = flags.mechanism;
+      if (mechanism !== undefined && !MECHANISMS.includes(/** @type {any} */ (mechanism))) throw new StateError('usage', `--mechanism must be one of ${MECHANISMS.join(', ')}`);
+      const sep = flags.test.indexOf('::');
+      const testCase = sep < 0 ? undefined : flags.test.slice(sep + 2);
+      if (testCase === '') throw new StateError('usage', '--test <file>::<case> needs a case name after ::');
+      const file = normalizeTestPath(sep < 0 ? flags.test : flags.test.slice(0, sep));
+      const argv = filteredTestArgv(file, testCase);
+      const runId = flags.run;
+      const record = await readRun(runId);
+      const block = record.blocks?.[blockId];
+      if (block?.status !== 'open') throw new StateError('no-block', `block ${blockId} is not open in run ${runId}`);
+      await assertTestFile(record.workspace, file);
+      const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: record.project });
+      const config = await configAt(record.workspace);
+      const isolation = config?.proof?.isolation === 'lock' ? 'lock' : 'export';
+      if (isolation === 'lock' && (await lockHolder(runId)) !== blockId) {
+        throw new StateError('proof.busy', `proof.isolation is lock — run code-forge proof lock ${blockId} --run ${runId} first`);
+      }
+      // `revert` puts every changed non-test owned file back to base; `assertion-deletion` touches only the test.
+      const changed = await blockFileSet({
+        repoRoot: record.workspace,
+        base: block.base_sha,
+        owned: block.owned_files,
+        matchOwned: (f) => findOverlap(block.owned_files, [f]) !== null,
+      });
+      const sources = mechanism === 'assertion-deletion' ? [] : changed.map((c) => c.file).filter((f) => f !== file && !TEST_PATH.test(f));
+      if (mechanism === 'revert' && sources.length === 0) {
+        throw new StateError('usage', `block ${blockId} changed no non-test source file to revert — use --mechanism assertion-deletion`);
+      }
+      const exp = isolation === 'export' ? await exportAndRecord({ runId, record, blockId, block, config, writeRow }) : null;
+      if (exp) await assertTestFile(exp.dir, file); // the test must also be where it runs (owned, or tracked at base)
+      const result = await runRedGreen({
+        workDir: exp ? exp.dir : record.workspace,
+        repoDir: record.workspace,
+        base: block.base_sha,
+        argv,
+        test: { file, ...(testCase === undefined ? {} : { case: testCase }), characterization: mechanism === 'assertion-deletion' },
+        sources,
+        isolation,
+        print: (line) => err(`${line}\n`),
+      });
+      // B20: the signed row names what the proof covers — the block gate reads `covers` per
+      // high-tier file. `revert` covers the sources it put back to base; `assertion-deletion`
+      // covers only the test file itself (its `::case` label is never part of a path). Every entry
+      // is normalized exactly as the gate normalizes its changed files (`repoRelativePath`).
+      const covers = [...new Set((result.mechanism === 'revert' ? sources : [file]).map((f) => repoRelativePath(f)))].sort();
+      // A result with no red phase (refused before the tree was touched) is never proven: the row
+      // still lands, `proven: false` and `red_kind: null`, and the verb exits 1.
+      const red = result.red ?? null;
+      const proven = result.proven === true && red !== null;
+      await recordProof({
+        runId,
+        writeRow,
+        row: {
+          block: blockId,
+          isolation,
+          step: 'red-green',
+          test: result.label,
+          mechanism: result.mechanism,
+          red_kind: red?.red_kind ?? null,
+          red: red?.verdict ?? null,
+          green: result.green ?? null,
+          proven,
+          failed: red?.failed ?? null,
+          covers,
+        },
+      });
+      out({
+        block: blockId,
+        test: result.label,
+        mechanism: result.mechanism,
+        isolation,
+        red: red?.verdict ?? null,
+        red_kind: red?.red_kind ?? null,
+        green: result.green ?? null,
+        proven,
+        ...(exp ? { export: { dir: exp.dir, restored: exp.restored, untracked: exp.untracked } } : {}),
+      });
+      return proven ? 0 : 1;
+    }
+  } catch (thrown) {
+    const code = thrown instanceof StateError ? thrown.code : 'error';
+    err(`proof ${sub}: ${thrown?.message ?? String(thrown)}\n`);
+    return code === 'usage' ? 2 : 1;
+  }
+
+  err(USAGE);
+  return 2;
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function proof(args) {
+  return runProof(args);
+}

package/src/cli/remove.mjs

@@ -0,0 +1,76 @@
+/**
+ * `code-forge remove [<harness>] [--scope project|global]` — deletes ONLY paths recorded in
+ * `~/.code-forge/installs.json` (plan §10.3 acceptance: "`remove` deletes only the 3 recorded
+ * paths and leaves a 4th unrecorded file"). With no arguments, every recorded install is removed;
+ * `<harness>` narrows to one harness id; `--scope` further narrows to `project` or `global`.
+ */
+
+import os from 'node:os';
+import { writeSafe } from '../util/redact.mjs';
+import { installsPath, removeRecords } from '../install/link.mjs';
+
+const USAGE = 'usage: code-forge remove [<harness>] [--scope project|global]\n';
+
+/**
+ * Strict parse: `[<harness>] [--scope <project|global>]`, in that order. An unknown flag, a
+ * missing/invalid `--scope` value, a harness name that looks like a flag, or an extra argument is
+ * a usage error — never silently reinterpreted.
+ * @param {string[]} args
+ * @returns {{harness?: string, scope?: 'project'|'global'} | null}
+ */
+export function parseRemoveArgs(args) {
+  if (args.length === 0) {
+    return {};
+  }
+  let harness;
+  let rest = args;
+  if (!rest[0].startsWith('-')) {
+    [harness, ...rest] = rest;
+  }
+  if (rest.length === 0) {
+    return { harness };
+  }
+  const [flag, value, ...extra] = rest;
+  if (flag !== '--scope' || (value !== 'project' && value !== 'global') || extra.length > 0) {
+    return null;
+  }
+  // `harness` is only included when it was actually parsed — an object with an explicit
+  // `harness: undefined` key is NOT deep-equal to one that omits the key altogether.
+  return harness === undefined ? { scope: value } : { harness, scope: value };
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} deps
+ * @param {{write: (s: string) => unknown}} [deps.stdout]
+ * @param {{write: (s: string) => unknown}} [deps.stderr]
+ * @param {string} [deps.home]
+ * @returns {Promise<number>}
+ */
+export async function runRemove(args, { stdout = process.stdout, stderr = process.stderr, home = os.homedir() } = {}) {
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  const parsed = parseRemoveArgs(args);
+  if (!parsed) {
+    err(USAGE);
+    return 2;
+  }
+
+  const removed = await removeRecords({ installsFile: installsPath(home), harness: parsed.harness, scope: parsed.scope });
+  for (const record of removed) {
+    out(`removed ${record.harness} (${record.scope}) ${record.target}\n`);
+  }
+  if (removed.length === 0) {
+    out('nothing to remove\n');
+  }
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function remove(args) {
+  return runRemove(args, {});
+}

package/src/cli/report.mjs

@@ -0,0 +1,73 @@
+/**
+ * `code-forge report [--slug <slug>] [--json] [--export <dir>]` (plan §6.2, R4). Terminal output
+ * only, plus an optional `--export <dir>` that writes the same 13 sections as JSON files.
+ */
+
+import { writeSafe } from '../util/redact.mjs';
+import { buildReport } from '../ledger/report.mjs';
+import { exportReportSections } from '../ledger/export.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+
+/**
+ * @param {string[]} args @param {string} flag @returns {string|undefined}
+ * `undefined` (not the next token) when the flag is absent, is the LAST token, or the "next
+ * token" starts with `--` — otherwise `report --slug --json` would read `--json` as the slug, and
+ * `report --slug x --export` (missing a directory) would silently print instead of exporting.
+ */
+function flagValue(args, flag) {
+  const i = args.indexOf(flag);
+  if (i < 0) return undefined;
+  const next = args[i + 1];
+  return next !== undefined && !next.startsWith('--') ? next : undefined;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runReport(args, deps = {}) {
+  const { stdout = process.stdout, stderr = process.stderr } = deps;
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  const slug = flagValue(args, '--slug');
+  if (!slug) {
+    err('usage: code-forge report --slug <slug> [--json] [--export <dir>]\n');
+    return 2;
+  }
+
+  // `readAllRows`/`ledgerPath` (src/ledger/paths.mjs) already refuse a slug shaped like a path
+  // (anything outside `/^[a-z0-9][a-z0-9-]*$/` — including `..` and `/`) with a TypeError; the
+  // try/catch below turns that, and any other I/O failure, into a clean CLI message instead of a
+  // raw stack trace that skips the `writeSafe` redaction path.
+  try {
+    const rows = await readAllRows(slug);
+    const { sections } = buildReport(rows);
+
+    const exportDir = flagValue(args, '--export');
+    if (exportDir) {
+      const paths = await exportReportSections(exportDir, sections);
+      out(`exported ${paths.length} section file(s) to ${exportDir}\n`);
+      return 0;
+    }
+
+    if (args.includes('--json')) {
+      out(`${JSON.stringify(sections, null, 2)}\n`);
+      return 0;
+    }
+
+    for (const [name, data] of Object.entries(sections)) {
+      out(`== ${name} ==\n${JSON.stringify(data, null, 2)}\n`);
+    }
+    return 0;
+  } catch (err_) {
+    err(`report: ${err_?.message ?? String(err_)}\n`);
+    return 1;
+  }
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function report(args) {
+  return runReport(args);
+}

package/src/cli/resolve.mjs

@@ -0,0 +1,79 @@
+/**
+ * `code-forge resolve <L0|L1|L2|L3>` — prints what a level actually resolves to right now
+ * (plan §5.2, §10.3 B4 acceptance): `{provider, model, effort, fallback, cli}`, via B1's
+ * `resolveLevel` (the per-level `provider` override wins over the top-level `provider`, R5) plus
+ * this block's own `cliNameForProvider` (the CLI binary `engine: subprocess` would spawn).
+ *
+ * **Fix round 1 (isolated per-file review, all MINOR):**
+ *  - The result is now written with `redact.writeSafe(process.stdout, ...)` — B0's documented
+ *    "stdout path" for a machine-readable value that must NOT go through `log.info` (which prefixes
+ *    every line with `[code-forge:info] `, defeating `jq`/pipe consumers of this verb's output).
+ *  - `cli: cliNameForProvider(...) ?? null` used to still exit 0 for a provider with no CLI mapping
+ *    (possible: `resolve` does not itself call `validateConfig`, unlike `validate.mjs`, so a config
+ *    with an out-of-enum `provider` string can reach here). It now logs an error and exits 1
+ *    instead of silently printing `"cli": null`.
+ *  - `resolved.fallback` is never `undefined` — `resolveLevel` (B1, `known-ids.mjs`) always returns
+ *    a (possibly empty) frozen array, so no `?? null`/`?? []` default was ever needed here; the
+ *    test suite now locks in the exact 5-key contract for BOTH the with-fallback and
+ *    without-fallback cases, closing the test gap the review actually found.
+ */
+
+import { loadProjectConfig } from '../config/load.mjs';
+import { resolveLevel } from '../config/known-ids.mjs';
+import { cliNameForProvider } from '../engines/provider-cli.mjs';
+import { maskSecretTokens } from '../config/secret-patterns.mjs';
+import { writeSafe } from '../util/redact.mjs';
+import * as log from '../util/log.mjs';
+
+const VALID_LEVELS = Object.freeze(['L0', 'L1', 'L2', 'L3']);
+
+/**
+ * @param {string[]} args
+ * @returns {{level: "L0"|"L1"|"L2"|"L3"} | {error: string}}
+ */
+function parseArgs(args) {
+  if (args.length !== 1) {
+    return { error: `usage: resolve <${VALID_LEVELS.join('|')}>` };
+  }
+  const [level] = args;
+  if (!VALID_LEVELS.includes(level)) {
+    return { error: `unknown level "${level}" — expected one of ${VALID_LEVELS.join(', ')}` };
+  }
+  return { level: /** @type {"L0"|"L1"|"L2"|"L3"} */ (level) };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function resolve(args) {
+  const parsed = parseArgs(args);
+  if ('error' in parsed) {
+    log.error(maskSecretTokens(parsed.error));
+    return 2;
+  }
+
+  const loaded = await loadProjectConfig();
+  if (!loaded.ok) {
+    log.error(maskSecretTokens(`${loaded.error}: ${loaded.message}`));
+    return 1;
+  }
+
+  let resolved;
+  try {
+    resolved = resolveLevel(loaded.config, parsed.level);
+  } catch (err) {
+    log.error(maskSecretTokens(/** @type {Error} */ (err).message));
+    return 1;
+  }
+
+  const cli = cliNameForProvider(resolved.provider);
+  if (cli === undefined) {
+    log.error(maskSecretTokens(`resolve: provider "${resolved.provider}" (from levels.${parsed.level}) has no known CLI mapping`));
+    return 1;
+  }
+
+  const output = { provider: resolved.provider, model: resolved.model, effort: resolved.effort ?? null, fallback: resolved.fallback, cli };
+  writeSafe(process.stdout, `${JSON.stringify(output)}\n`);
+  return 0;
+}