@codedology/code-forge 0.1.0

package/src/cli/ledger.mjs

@@ -0,0 +1,160 @@
+/**
+ * `code-forge ledger calibration|outcome|tail` (plan §6.3, C12). Every subcommand takes
+ * `--slug <slug>` explicitly: this block (B6) depends only on B0, so it has no config loader
+ * (B1) to read `project.slug` from — a later block's verb passes `--slug` through from config.
+ *
+ *   ledger calibration --slug <slug> [--question <id>]
+ *   ledger outcome --scan-git --slug <slug> [--cwd <dir>] [--days <n>]
+ *   ledger outcome --pr <n> --ci red|green|reverted --slug <slug>
+ *   ledger tail --slug <slug> [--n <count>]
+ */
+
+import { writeSafe } from '../util/redact.mjs';
+import { buildCalibration } from '../ledger/calibration.mjs';
+import { recordCiOutcome, reviewedEntriesFromRows, scanGitAndRecord } from '../ledger/outcome.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+
+/**
+ * @param {string[]} args @param {string} flag
+ * @returns {{ok: true, value: string|undefined} | {ok: false}} `ok: false` means the flag WAS
+ *   given but with no usable value (missing, or the "next token" is itself another flag) — the
+ *   caller must treat this as a usage error, not silently fall back to a default. Without this
+ *   distinction, `ledger outcome --scan-git --slug s --cwd --days 3` would read `--cwd`'s value as
+ *   absent and quietly scan `process.cwd()` instead — the wrong repo, exiting 0.
+ */
+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}
+ * For REQUIRED flags only (`--slug`, `--pr`, `--ci`): a missing value is indistinguishable from a
+ * missing flag, and both already fall through to the same "required flag absent" usage error at
+ * the call site — unlike the optional flags above, there is no silent-default to protect against.
+ */
+function flagValue(args, flag) {
+  const result = readOptionalFlag(args, flag);
+  return result.ok ? result.value : undefined;
+}
+
+/** @param {string} raw @returns {number|null} a non-negative integer, or null if `raw` isn't one. */
+function parseNonNegativeInt(raw) {
+  if (!/^\d+$/.test(raw)) return null;
+  return Number.parseInt(raw, 10);
+}
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runLedger(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 usage = () => err('usage: code-forge ledger calibration|outcome|tail --slug <slug> [...]\n');
+
+  const [sub] = args;
+  const slug = flagValue(args, '--slug');
+  if (!slug) {
+    usage();
+    return 2;
+  }
+
+  try {
+    if (sub === 'calibration') {
+      const question = readOptionalFlag(args, '--question');
+      if (!question.ok) {
+        err('ledger calibration: --question requires a value\n');
+        return 2;
+      }
+      const rows = await readAllRows(slug);
+      const answers = rows.filter((r) => r.event === 'decision' && typeof r.confidence === 'number');
+      const outcomes = rows.filter((r) => r.event === 'outcome' && r.decision_id);
+      const { buckets, unbacked, unmapped } = buildCalibration(answers, outcomes, { questionId: question.value });
+      out(`${JSON.stringify({ buckets, unbacked, unmapped }, null, 2)}\n`);
+      return 0;
+    }
+
+    if (sub === 'outcome' && args.includes('--scan-git')) {
+      const cwdFlag = readOptionalFlag(args, '--cwd');
+      if (!cwdFlag.ok) {
+        err('ledger outcome --scan-git: --cwd requires a value\n');
+        return 2;
+      }
+      const cwd = cwdFlag.value ?? process.cwd();
+
+      const daysFlag = readOptionalFlag(args, '--days');
+      if (!daysFlag.ok) {
+        err('ledger outcome --scan-git: --days requires a value\n');
+        return 2;
+      }
+      let days;
+      if (daysFlag.value !== undefined) {
+        days = Number(daysFlag.value);
+        if (!Number.isFinite(days) || days <= 0) {
+          err(`ledger outcome --scan-git: --days must be a finite number > 0, got "${daysFlag.value}"\n`);
+          return 2;
+        }
+      }
+      const rows = await readAllRows(slug);
+      const reviewed = reviewedEntriesFromRows(rows);
+      const written = await scanGitAndRecord({ cwd, reviewed, days, slug });
+      out(`scanned git: ${written.length} row(s) marked reverted\n`);
+      return 0;
+    }
+
+    if (sub === 'outcome' && flagValue(args, '--pr') && flagValue(args, '--ci')) {
+      const prArg = flagValue(args, '--pr');
+      const pr = parseNonNegativeInt(prArg);
+      if (pr === null || pr === 0) {
+        err(`ledger outcome: --pr must be a positive integer, got "${prArg}"\n`);
+        return 2;
+      }
+      const ci = flagValue(args, '--ci');
+      if (!['red', 'green', 'reverted'].includes(ci)) {
+        err(`ledger outcome: --ci must be red|green|reverted, got "${ci}"\n`);
+        return 2;
+      }
+      await recordCiOutcome({ pr, ci: /** @type {'red'|'green'|'reverted'} */ (ci), slug });
+      out(`recorded outcome for PR #${pr}: ${ci}\n`);
+      return 0;
+    }
+
+    if (sub === 'tail') {
+      const nFlag = readOptionalFlag(args, '--n');
+      if (!nFlag.ok) {
+        err('ledger tail: --n requires a value\n');
+        return 2;
+      }
+      const nArg = nFlag.value ?? '20';
+      const n = parseNonNegativeInt(nArg);
+      if (n === null) {
+        err(`ledger tail: --n must be a non-negative integer, got "${nArg}"\n`);
+        return 2;
+      }
+      const rows = await readAllRows(slug);
+      for (const row of n === 0 ? [] : rows.slice(-n)) {
+        out(`${JSON.stringify(row)}\n`);
+      }
+      return 0;
+    }
+  } catch (thrown) {
+    // Same problem `report.mjs` fixed in round 1: a corrupt ledger, an unwritable folder, or
+    // `--scan-git` outside a git repo must not leak a raw stack trace past the redaction path.
+    err(`ledger ${sub}: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+
+  usage();
+  return 2;
+}
+
+/** @param {string[]} args @returns {Promise<number>} */
+export default async function ledger(args) {
+  return runLedger(args);
+}

package/src/cli/list.mjs

@@ -0,0 +1,68 @@
+/**
+ * `code-forge list` (plan §2.1: "`code-forge list` prints what is linked where and whether the
+ * target resolves"). Two sections:
+ *  - INSTALLED — every recorded row of `~/.code-forge/installs.json`, plus a live `resolves`
+ *    check (a broken symlink, or a target someone deleted by hand, reports `no`).
+ *  - HARNESSES — the full path table (plan §2.1), with live PATH/home-dir detection and each
+ *    row's `verified` flag from `src/install/harnesses.mjs` (the Gemini row is `UNVERIFIED`).
+ *
+ * Takes no arguments; `code-forge list <anything>` is a usage error.
+ */
+
+import os from 'node:os';
+import { writeSafe } from '../util/redact.mjs';
+import { detectAll } from '../install/detect.mjs';
+import { HARNESSES } from '../install/harnesses.mjs';
+import { installsPath, readInstalls, targetResolves } from '../install/link.mjs';
+
+const USAGE = 'usage: code-forge list\n';
+
+/**
+ * @param {string[]} args
+ * @param {object} deps
+ * @param {{write: (s: string) => unknown}} [deps.stdout]
+ * @param {{write: (s: string) => unknown}} [deps.stderr]
+ * @param {string} [deps.home]
+ * @param {NodeJS.ProcessEnv} [deps.env]
+ * @returns {Promise<number>}
+ */
+export async function runList(args, { stdout = process.stdout, stderr = process.stderr, home = os.homedir(), env = process.env } = {}) {
+  const out = (/** @type {string} */ s) => writeSafe(stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(stderr, s);
+
+  if (args.length > 0) {
+    err(USAGE);
+    return 2;
+  }
+
+  const records = await readInstalls(installsPath(home));
+  out('INSTALLED\n');
+  out('HARNESS\tSCOPE\tMETHOD\tTARGET\tRESOLVES\n');
+  for (const record of records) {
+    const resolves = await targetResolves(record.target);
+    out(`${record.harness}\t${record.scope}\t${record.method}\t${record.target}\t${resolves ? 'yes' : 'no'}\n`);
+  }
+  if (records.length === 0) {
+    out('(none)\n');
+  }
+
+  const detections = await detectAll({ home, pathEnv: env.PATH });
+  out('\nHARNESSES\n');
+  out('ID\tLABEL\tDETECTED\tVERIFIED\tPROJECT PATH\n');
+  for (const harness of HARNESSES) {
+    const detection = detections.find((d) => d.id === harness.id);
+    out(
+      `${harness.id}\t${harness.label}\t${detection?.detected ? 'yes' : 'no'}\t${harness.verified ? 'yes' : 'UNVERIFIED'}\t${harness.projectSkillsDir}\n`,
+    );
+  }
+
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function list(args) {
+  return runList(args, {});
+}

package/src/cli/models.mjs

@@ -0,0 +1,131 @@
+/**
+ * `code-forge models [--refresh --from-cli-caches]` — lists the model catalog per provider (the
+ * shipped `known-ids.mjs` list, plus the project's `known_extra`, plus anything the user-level
+ * `seen-in-cache` list has picked up). `--refresh --from-cli-caches` is the opt-in C15 refresh:
+ * it reads whichever of `~/.codex/models_cache.json` / `~/.grok/models_cache.json` exist and
+ * merges their ids into the user-level cache BEFORE listing — it never writes the project's
+ * `.code-forge.yml` (plan §1.3, §2 step 3).
+ *
+ * Every line printed from file-derived text passes `maskSecretTokens` (and B0's `redact` inside
+ * `log`): a Grok cache stores an `api_key` next to every model id, and a project config is where
+ * a user pastes a key by mistake.
+ */
+
+import { KNOWN_IDS, knownIdsForProvider } from '../config/known-ids.mjs';
+import { loadProjectConfig } from '../config/load.mjs';
+import { loadSeenInCache, refreshFromCliCaches } from '../config/refresh.mjs';
+import { maskSecretTokens } from '../config/secret-patterns.mjs';
+import * as log from '../util/log.mjs';
+
+/**
+ * @param {string[]} args
+ * @returns {{refresh: boolean, fromCliCaches: boolean} | {error: string}}
+ */
+function parseArgs(args) {
+  let refresh = false;
+  let fromCliCaches = false;
+  for (const arg of args) {
+    if (arg === '--refresh') {
+      refresh = true;
+    } else if (arg === '--from-cli-caches') {
+      fromCliCaches = true;
+    } else {
+      return { error: `unknown argument: ${arg}` };
+    }
+  }
+  if (fromCliCaches && !refresh) {
+    return { error: '--from-cli-caches requires --refresh' };
+  }
+  return { refresh, fromCliCaches };
+}
+
+/**
+ * An OWN entry of a map as a string array — anything else (a number, a string, an inherited
+ * `constructor`) is `[]`, so iterating it can never throw or split a string into characters.
+ * @param {unknown} map
+ * @param {string} key
+ * @returns {string[]}
+ */
+function ownIdList(map, key) {
+  if (!map || typeof map !== 'object' || !Object.hasOwn(map, key)) {
+    return [];
+  }
+  const value = /** @type {Record<string, unknown>} */ (map)[key];
+  return Array.isArray(value) ? value.filter((id) => typeof id === 'string') : [];
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function models(args) {
+  const parsed = parseArgs(args);
+  if ('error' in parsed) {
+    log.error(maskSecretTokens(parsed.error));
+    return 2;
+  }
+
+  if (parsed.refresh) {
+    if (!parsed.fromCliCaches) {
+      // C15: `--refresh` ships as an opt-in gated by `--from-cli-caches` — there is no other
+      // refresh source in 0.1, so a bare `--refresh` is a usage error, not a silent no-op.
+      log.error('models --refresh requires --from-cli-caches (the only refresh source in 0.1)');
+      return 2;
+    }
+    let result;
+    try {
+      result = await refreshFromCliCaches();
+    } catch (err) {
+      log.error(maskSecretTokens(`refresh failed: ${/** @type {Error} */ (err).message}`));
+      return 1;
+    }
+    if (result.sourcesRead.length === 0) {
+      // 0 sources read is NOT a refresh — never claim success while doing nothing useful.
+      log.warn('no CLI caches were found to refresh from (checked ~/.codex and ~/.grok)');
+    } else {
+      log.info(
+        `refreshed from ${result.sourcesRead.length} CLI cache(s) -> ${result.cachePath} (status: seen-in-cache)`,
+      );
+    }
+    for (const skipped of result.sourcesSkipped) {
+      log.warn(maskSecretTokens(`skipped ${skipped.path}: ${skipped.reason}`));
+    }
+  }
+
+  const seenInCache = await loadSeenInCache();
+  const projectLoad = await loadProjectConfig();
+  if (!projectLoad.ok && projectLoad.error !== 'not-found') {
+    // A project config that exists but fails to load is reported (a missing one stays silent) —
+    // otherwise the user's known_extra silently vanishes from the listing.
+    log.warn(maskSecretTokens(`could not read known_extra from ${projectLoad.path}: ${projectLoad.error}: ${projectLoad.message}`));
+  }
+  const rawKnownExtra = projectLoad.ok ? projectLoad.config.known_extra : undefined;
+  const knownExtra = rawKnownExtra && typeof rawKnownExtra === 'object' && !Array.isArray(rawKnownExtra) ? rawKnownExtra : {};
+
+  // The union of every provider that appears in ANY of the three sources, not just
+  // `Object.keys(KNOWN_IDS)` — a provider that only exists in known_extra or seen-in-cache is
+  // still listed, instead of silently vanishing from the output.
+  const allProviders = new Set([...Object.keys(KNOWN_IDS), ...Object.keys(knownExtra), ...Object.keys(seenInCache)]);
+
+  for (const provider of [...allProviders].sort()) {
+    log.info(maskSecretTokens(`${provider}:`));
+    // One `printed` set per provider so an id shipped in BOTH the catalog and known_extra/
+    // seen-in-cache is printed once, tagged by its highest-precedence source.
+    const printed = new Set();
+    for (const id of knownIdsForProvider(provider)) {
+      log.info(`  ${id}`);
+      printed.add(id);
+    }
+    for (const id of ownIdList(knownExtra, provider)) {
+      if (printed.has(id)) continue;
+      log.info(maskSecretTokens(`  ${id} (known_extra)`));
+      printed.add(id);
+    }
+    for (const id of ownIdList(seenInCache, provider)) {
+      if (printed.has(id)) continue;
+      log.info(maskSecretTokens(`  ${id} (seen-in-cache)`));
+      printed.add(id);
+    }
+  }
+  return 0;
+}

package/src/cli/plan.mjs

@@ -0,0 +1,70 @@
+/**
+ * `code-forge plan check <plan-file> [--facts <sheet>]` (plan §3.8 rule 4, §3.2; block B9b) —
+ * the deterministic harden exit. Prints every failing row on stderr, one per line, and exits 1
+ * when there is any; prints `plan check: ok (<n> blocks)` and exits 0 otherwise; 2 on usage.
+ * Limits come from `.code-forge.yml` when there is one (`caps.coders`, `budget.block_cases`,
+ * `budget.block_lines`), else the plan defaults.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/load.mjs';
+import { checkPlan } from '../session/plan-check.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge plan check <plan-file> [--facts <sheet>]\n';
+
+/**
+ * @param {string[]} args
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runPlanVerb(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: ['facts'] });
+    if (positionals.length !== 2 || positionals[0] !== 'check') {
+      writeSafe(stderr, USAGE);
+      return 2;
+    }
+    const planPath = path.resolve(cwd, positionals[1]);
+    const factsPath = typeof flags.facts === 'string' ? path.resolve(cwd, flags.facts) : undefined;
+    /** @param {string} file @param {string} what */
+    const read = (file, what) => {
+      try {
+        return readFileSync(file, 'utf8');
+      } catch {
+        throw new StateError('usage', `${what} cannot be read`);
+      }
+    };
+    const text = read(planPath, 'the plan file');
+    const factsText = factsPath ? read(factsPath, '--facts') : undefined;
+    const loaded = await loadProjectConfig(cwd);
+    if (!loaded.ok && loaded.error !== 'not-found') {
+      writeSafe(stderr, `plan: ${loaded.message}\n`);
+      return 2;
+    }
+    const result = checkPlan(text, { planPath, factsPath, factsText, cfg: loaded.ok ? loaded.config : undefined });
+    if (!result.ok) {
+      for (const line of result.errors) writeSafe(stderr, `${line}\n`);
+      return 1;
+    }
+    writeSafe(stdout, `plan check: ok (${result.blocks} blocks)\n`);
+    return 0;
+  } catch (err) {
+    if (err instanceof StateError) {
+      writeSafe(stderr, `plan: ${err.message}\n`);
+      return 2;
+    }
+    throw err;
+  }
+}
+
+/** @param {string[]} args */
+export default async function planVerb(args) {
+  return runPlanVerb(args);
+}