@codedology/code-forge 0.7.7 → 0.8.0

package/src/cli/report.mjs

@@ -1,13 +1,15 @@
 /**
  * `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. The
+ * only, plus an optional `--export <dir>` that writes the same 14 sections as JSON files. The
  * terminal output ends with the spend per run (B33) and the mode of each run (B59: brief or plan);
- * both are text only, never in `--json` or `--export`, so the 13 pinned sections stay as they are.
+ * both are text only, never in `--json` or `--export`. The 14th section, `outside_review` (B66), is
+ * printed as text lines under its header (`outside review: none`, or one line per PR).
  */
 
 import { writeSafe } from '../util/redact.mjs';
 import { buildReport, buildRunModes, buildSpend } from '../ledger/report.mjs';
 import { exportReportSections } from '../ledger/export.mjs';
+import { outsideReviewLines } from '../ledger/outside-review.mjs';
 import { readAllRows } from '../ledger/write.mjs';
 
 /**
@@ -60,7 +62,8 @@ export async function runReport(args, deps = {}) {
     }
 
     for (const [name, data] of Object.entries(sections)) {
-      out(`== ${name} ==\n${JSON.stringify(data, null, 2)}\n`);
+      const body = name === 'outside_review' ? outsideReviewLines(data) : `${JSON.stringify(data, null, 2)}\n`;
+      out(`== ${name} ==\n${body}`);
     }
     out(spendLines(buildSpend(rows)));
     out(modeLines(buildRunModes(rows)));
@@ -72,7 +75,7 @@ export async function runReport(args, deps = {}) {
 }
 
 /**
- * B33: the running spend per run (open blocks included), after the 13 sections. Unknown-price
+ * B33: the running spend per run (open blocks included), after the 14 sections. Unknown-price
  * sessions are named, never priced.
  * @param {ReturnType<typeof buildSpend>} spend @returns {string}
  */

package/src/cli/review-file.mjs

@@ -23,13 +23,28 @@
  * down on two polls in a row, and a worker whose pid is alive with a fresh heartbeat is never down
  * (`liveWorker`, B30). Output is one JSON line on stdout.
  * Exit codes: 0 queued/done/pending, 1 bad-path or another refusal, 2 usage, 3 worker_down.
+ *
+ * B62b: the queue and the worker are always the MAIN tree's (`mainRootOf`), also when the coder
+ * runs `review-file` inside a block's worktree. For a block the run record gives a worktree
+ * (`proof.isolation: worktree`), the content is hashed in that tree — never in the main tree — and
+ * the ticket and the answer carry `tree: <tree top level>`; the worker reviews the same tree. The
+ * path is still given relative to the current directory, inside the tree it is called from, and is
+ * re-checked in the tree the content is read from. A block the record gives no worktree is hashed
+ * in the main tree, wherever `review-file` is called. When the run record does not exist here or
+ * cannot be opened (a sandboxed coder), the content is hashed in the tree `review-file` is called
+ * from, which is the block's tree when the coder works there. A record naming a worktree that is
+ * gone or malformed is refused (exit 1, `reason: worktree-missing|worktree-malformed|…`), and
+ * nothing is queued.
  */
 
-import { readFileSync, rmSync } from 'node:fs';
+import { readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { enqueue, isDone, liveWorker, queueDir } from '../worker/queue.mjs';
-import { assertBlockId, assertTicketId, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
+import { assertBlockId, assertInsideRoot, assertTicketId, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
+import { StateError } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { blockTree } from '../proof/worktree.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
 const USAGE = 'usage: code-forge review-file <path> --block <id> [--run <id>] | review-file --wait <ticket> [--max <seconds>s]\n';
@@ -63,6 +78,39 @@ function doneResult(repoRoot, ticket) {
   }
 }
 
+/**
+ * B62b: where the block `block` of run `runId` keeps its content, from the run record (read from
+ * the user's state dir, `~/.code-forge/runs`, whatever the current directory): `{top}` with the
+ * top level of its worktree, realpath'd; `{top: null}` when the record gives the block no worktree
+ * (then the main tree, never the tree `review-file` is called from); null when the record does
+ * not exist here or cannot be opened (a sandboxed coder: no such file, or no permission) — only
+ * then is the content hashed in the tree `review-file` is called from, and the worker refuses a
+ * ticket hashed in the wrong tree. A record that names a worktree which cannot be used (gone,
+ * moved, malformed, off its branch) is refused, and so is a record that cannot be parsed or is not
+ * a record (`run-record-unreadable`): nothing is queued. Any other failure is rethrown.
+ * @param {string} runId @param {string} block
+ * @returns {Promise<{top: string | null} | null>}
+ * @throws {WorkerError} a `worktree-*` code, or `run-record-unreadable`.
+ */
+async function blockTreeOf(runId, block) {
+  let record;
+  try {
+    record = await readRun(runId);
+  } catch (err) {
+    const code = /** @type {{code?: unknown}} */ (err)?.code;
+    if (code === 'no-run' || code === 'EACCES' || code === 'EPERM') return null;
+    if (!(err instanceof SyntaxError)) throw err;
+    record = null;
+  }
+  if (record === null || typeof record !== 'object') throw new WorkerError('run-record-unreadable', `the run record of ${runId} cannot be read (corrupt or not a record); nothing was queued`);
+  try {
+    return { top: (await blockTree(record.workspace, record.blocks?.[block]))?.top ?? null };
+  } catch (err) {
+    if (err instanceof StateError) throw new WorkerError(err.code, `block ${block}: ${err.message}; nothing was queued`);
+    throw err;
+  }
+}
+
 /**
  * The coder-facing summary of a done result: the fix list and the stop reason, when any.
  * @param {Record<string, any> | null} result
@@ -103,7 +151,8 @@ export async function runReviewFile(args, deps = {}) {
   const cwd = deps.cwd ?? process.cwd();
   try {
     const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max'] });
-    const repoRoot = await repoRootOf(cwd);
+    // the queue and the worker: the main tree, also from inside a block's worktree
+    const repoRoot = await mainRootOf(cwd);
 
     if (typeof flags.wait === 'string') {
       if (positionals.length > 0 || flags.block !== undefined) throw new WorkerError('usage', '--wait takes only a ticket and --max');
@@ -132,18 +181,24 @@ export async function runReviewFile(args, deps = {}) {
 
     if (positionals.length !== 1 || typeof flags.block !== 'string' || flags.max !== undefined) throw new WorkerError('usage', 'give one path and --block');
     const block = assertBlockId(flags.block);
-    const file = normalizeRequestPath(positionals[0], cwd, repoRoot);
+    const file = normalizeRequestPath(positionals[0], cwd, await repoRootOf(cwd));
     const worker = liveWorker(repoRoot);
     if (!worker || (typeof flags.run === 'string' && flags.run !== worker.run)) {
       say({ status: 'worker_down', file });
       return 3;
     }
-    const queued = enqueue({ repoRoot, run: worker.run, block, file });
+    // the content: the block's worktree when the record gives one, the main tree when it gives
+    // none; only a record that cannot be opened here falls back to the tree review-file is called from
+    const recorded = await blockTreeOf(worker.run, block);
+    const tree = recorded === null ? await repoRootOf(cwd) : (recorded.top ?? repoRoot);
+    assertInsideRoot(tree, file); // the path, re-checked in the tree its content is read from
+    const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
+    const queued = enqueue({ repoRoot, run: worker.run, block, file, ...where });
     if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
       // `unavailable` is never approval AND never final: drop the done marker so the worker runs
       // the ticket again (the fix loop re-runs its pending round); the signed result is replaced.
       rmSync(path.join(queueDir(repoRoot), `${queued.ticket}.done`), { force: true });
-      say({ ...enqueue({ repoRoot, run: worker.run, block, file }), retry: true });
+      say({ ...enqueue({ repoRoot, run: worker.run, block, file, ...where }), retry: true });
       return 0;
     }
     say(queued);

package/src/cli/status.mjs

@@ -0,0 +1,212 @@
+/**
+ * `code-forge status [--run <id>] [--json]` (B64a, issue #13 item 6): a short status of a run, so
+ * the orchestrator checks progress with one command instead of reading logs or polling
+ * transcripts.
+ *
+ * Read-only: it reads the run record (`~/.code-forge/runs/<id>.json`, as `run status` does — no
+ * lock), the project's ledger rows and the workspace config (for `budget.usd`), and writes
+ * nothing — no ledger row, no file, no lock. The data comes from `briefStatus`
+ * (`src/state/brief-status.mjs`); this file finds the runs, counts open findings and renders.
+ *
+ * With `--run`, that run (ended or not). Without it, every run that is not ended whose workspace
+ * is the current repository (`projectRootFor(cwd)`, compared on realpaths), newest first (by
+ * `started_at`, then run id); with none, `no active run` (exit 0; `{"runs":[]}` with `--json`).
+ * An unknown `--run` exits 1; a usage error (unknown flag, a positional) exits 2.
+ *
+ * Text: at most {@link STATUS_MAX_LINES} lines per run, runs separated by one blank line:
+ *   run <id> · <status> · <plan|brief> · spent $<x>[ of $<budget>]
+ *   <id> <state> <level> · <model or -> · gate <pass|fail|none>[ (<gate>)] · findings <n>
+ *   … +<k> more blocks                  (only when the open blocks do not fit)
+ *   closed <a> · stopped <b>            (only when any exist; printed last, but block lines are
+ *                                        dropped first to keep it inside the cap)
+ * The gate field is `gate pass`, `gate fail (<gate>)`, `gate fail` (no gate named) or `gate none`.
+ * `<x>` is `run status`'s spent_usd with 2 decimals, followed by `+?` when some session has no
+ * known price (`run status`'s unknown_usd_sessions > 0); the whole amount is `$?` when the ledger
+ * cannot be read. A run record with no status shows `-`.
+ *
+ * `--json`: exactly one line, `{"runs":[{run_id, status, mode, spent_usd, unknown_usd_sessions,
+ * budget_usd, blocks, more, closed, stopped}]}` — every block that is neither closed nor stopped
+ * (no cap), `more` always 0, `spent_usd` and `unknown_usd_sessions` null when the ledger cannot be
+ * read, `status` null when the record has none.
+ *
+ * The run lock (`<runs>/<id>.lock`, taken by the worker and the block verbs) is never taken nor
+ * waited on: a held lock does not delay `status`.
+ *
+ * Findings: the number of distinct (file, finding) pairs the block gate would refuse today
+ * (`checkBlockReviews`, `src/review/gate-check.mjs` — the same rules `block close` applies: the
+ * latest review of each file left it open and no valid waiver, ruling or later approval cleared
+ * it). The files are the ones the block's review rows name (`reviewedFiles`, the selection
+ * `block close` uses for reviewed files), each at the content hash of its LAST review row (only
+ * review rows — the events `reviewedFiles` counts — supply a hash; other rows never do). A file
+ * whose review rows carry no hash is checked at the empty hash: the gate counts a refusal row
+ * with no `content_hash` for every hash of its file (fail closed), so its open findings count.
+ * The gate's other refusals (unreviewed, unsigned, proof, rule breaks) are not findings and are
+ * not counted. No transcript, diff or review text is ever read or printed.
+ *
+ * The run key is only read (`loadKey`: a stat and a read, never a create or a write); with no
+ * key, a zero key stands in, so no signed waiver or approval verifies (fail closed).
+ */
+
+import { readdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProjectConfig, projectRootFor } from '../config/load.mjs';
+import { budgetUsdOf } from '../ledger/spend.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+import { findingsKey, openFindingsOf } from '../review/open-findings.mjs';
+import { briefStatus } from '../state/brief-status.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { runsDir, StateError } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge status [--run <id>] [--json]\n';
+
+/** The hard cap on text lines per run. */
+const STATUS_MAX_LINES = 10;
+
+/**
+ * @typedef {import('../state/brief-status.mjs').RunStatus} RunStatus
+ */
+
+/** @param {string} p @returns {Promise<string>} */
+async function realOr(p) {
+  try {
+    return await realpath(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * The status data of one run.
+ * @param {Record<string, any>} record
+ * @returns {Promise<RunStatus>}
+ */
+async function statusOf(record) {
+  /** @type {Array<Record<string, any>> | null} null: the ledger cannot be read */
+  let rows = null;
+  try {
+    rows = await readAllRows(record.project);
+  } catch {
+    rows = null;
+  }
+  let budget = null;
+  try {
+    const loaded = await loadProjectConfig(record.workspace);
+    budget = loaded.ok ? budgetUsdOf(loaded.config) : null;
+  } catch {
+    budget = null;
+  }
+  const key = await findingsKey(record);
+  const runId = String(record.run_id);
+  const all = rows ?? [];
+  /** @type {Map<string, Array<Record<string, any>>>} the run's rows, grouped by block once */
+  const byBlock = new Map();
+  for (const r of all) {
+    if (r?.run !== runId || typeof r.block !== 'string') continue;
+    const list = byBlock.get(r.block);
+    if (list) list.push(r);
+    else byBlock.set(r.block, [r]);
+  }
+  return briefStatus({ record, rows, budget, findingsOf: (block) => openFindingsOf({ block, runId, mine: byBlock.get(block) ?? [], rows: all, key }) });
+}
+
+/**
+ * Every run that is not ended whose workspace is `root`, newest first.
+ * @param {string} root
+ * @returns {Promise<Array<Record<string, any>>>}
+ */
+async function activeRunsFor(root) {
+  const want = await realOr(root);
+  let names;
+  try {
+    names = await readdir(runsDir());
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    let record;
+    try {
+      record = await readRun(name.slice(0, -'.json'.length));
+    } catch {
+      continue; // not a run record (a bad id, unparsable): not a run to show
+    }
+    if (!record || typeof record !== 'object' || record.status === 'ended' || typeof record.workspace !== 'string') continue;
+    if ((await realOr(record.workspace)) !== want) continue;
+    records.push(record);
+  }
+  const at = (/** @type {Record<string, any>} */ r) => (typeof r.started_at === 'string' ? r.started_at : '');
+  return records.sort((a, b) => at(b).localeCompare(at(a)) || String(b.run_id).localeCompare(String(a.run_id)));
+}
+
+/** @param {number} n @returns {string} */
+const usd = (n) => `$${n.toFixed(2)}`;
+
+/**
+ * The text lines of one run, at most {@link STATUS_MAX_LINES}.
+ * @param {RunStatus} s @returns {string[]}
+ */
+export function runLines(s) {
+  const spent = s.spent_usd === null ? '$?' : `${usd(s.spent_usd)}${(s.unknown_usd_sessions ?? 0) > 0 ? '+?' : ''}`;
+  const lines = [`run ${s.run_id} · ${s.status ?? '-'} · ${s.mode} · spent ${spent}${s.budget_usd !== null ? ` of ${usd(s.budget_usd)}` : ''}`];
+  const tally = s.closed + s.stopped > 0 ? `closed ${s.closed} · stopped ${s.stopped}` : null;
+  const room = STATUS_MAX_LINES - 1 - (tally === null ? 0 : 1);
+  const shown = s.blocks.length <= room ? s.blocks : s.blocks.slice(0, room - 1);
+  for (const b of shown) {
+    lines.push(`${b.id} ${b.state} ${b.level ?? '-'} · ${b.model ?? '-'} · gate ${b.gate.result}${b.gate.name ? ` (${b.gate.name})` : ''} · findings ${b.findings}`);
+  }
+  if (shown.length < s.blocks.length) lines.push(`… +${s.blocks.length - shown.length} more blocks`);
+  if (tally !== null) lines.push(tally);
+  return lines;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function status(args) {
+  const out = (/** @type {string} */ s) => writeSafe(process.stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(process.stderr, s);
+  let flags;
+  try {
+    const parsed = parseFlags(args, { values: ['run'], booleans: ['json'] });
+    if (parsed.positionals.length > 0) throw new StateError('usage', `unexpected argument ${JSON.stringify(parsed.positionals[0])}`);
+    flags = parsed.flags;
+  } catch (thrown) {
+    err(`status: ${thrown?.message ?? String(thrown)}\n${USAGE}`);
+    return 2;
+  }
+  const json = flags.json === true;
+  try {
+    /** @type {Array<Record<string, any>>} */
+    let records;
+    if (typeof flags.run === 'string') {
+      const id = flags.run;
+      const record = await readRun(id).catch((thrown) => (thrown?.code === 'no-run' ? null : Promise.reject(thrown)));
+      if (!record || typeof record !== 'object') {
+        err(`status: no run record for ${id}\n`); // the wording every verb uses for an unknown run
+        return 1;
+      }
+      records = [record];
+    } else {
+      records = await activeRunsFor(projectRootFor(process.cwd()));
+    }
+    const shown = [];
+    for (const record of records) shown.push(await statusOf(record));
+    if (json) {
+      out(`${JSON.stringify({ runs: shown })}\n`); // briefStatus builds exactly the clause-3 run object
+      return 0;
+    }
+    if (shown.length === 0) {
+      out('no active run\n');
+      return 0;
+    }
+    out(`${shown.map((s) => runLines(s).join('\n')).join('\n\n')}\n`);
+    return 0;
+  } catch (thrown) {
+    err(`status: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+}

package/src/config/validate.mjs

@@ -62,6 +62,7 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import schema from '../../schema/code-forge.schema.json' with { type: 'json' };
 import { redact } from '../util/redact.mjs';
+import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
 import { checkEffort, displayEffort } from '../engines/efforts.mjs';
 import { CLOSED_BOOK_LEVELS, CODEX_CLOSED_BOOK_REFUSAL, isNoClosedBookProvider, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from './closed-book.mjs';
 import { isKnownId, resolveLevel } from './known-ids.mjs';
@@ -458,19 +459,52 @@ function isArgvArray(value) {
   return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string') && value[0].length > 0;
 }
 
-function checkGatesNotArgvArray(cfg) {
-  const issues = [];
-  for (const key of GATE_KEYS) {
-    const value = cfg?.gates?.[key];
-    if (value !== undefined && value !== null && !isArgvArray(value)) {
-      issues.push({
-        rule: 'gates-not-argv-array',
-        severity: 'error',
-        message: `gates.${key} must be a non-empty argv array of strings, or null`,
-      });
+/** B60: the keys a gate given as an object may have. */
+const GATE_OBJECT_KEYS = new Set(['argv', 'env']);
+/** B60: an environment variable name. */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Rule 9's messages for one gate: an argv array, `{argv, env}` (B60), or null. A message names a
+ * bad key or env variable NAME, never an env value.
+ * @param {string} key @param {unknown} value @returns {string[]}
+ */
+function gateMessages(key, value) {
+  if (value === undefined || value === null) return [];
+  // B60: `{test_files}` may expand to nothing, so it cannot be the command — and as the only item a
+  // full-suite run would be an empty argv
+  /** @param {string[]} argv @returns {string[]} */
+  const tokenMessages = (argv) =>
+    argv.length === 1 && argv[0] === TEST_FILES_TOKEN
+      ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the only item (the full suite would run an empty command)`]
+      : argv[0] === TEST_FILES_TOKEN
+        ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the command (argv[0])`]
+        : [];
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    if (!isArgvArray(value)) return [`gates.${key} must be a non-empty argv array of strings, an {argv, env} object, or null`];
+    return tokenMessages(/** @type {string[]} */ (value));
+  }
+  const gate = /** @type {Record<string, unknown>} */ (value);
+  const messages = Object.keys(gate)
+    .filter((k) => !GATE_OBJECT_KEYS.has(k))
+    .map((k) => `gates.${key}: unknown key ${JSON.stringify(k)} (an object gate has only argv and env)`);
+  if (!isArgvArray(gate.argv)) messages.push(`gates.${key}.argv must be a non-empty argv array of strings`);
+  else messages.push(...tokenMessages(/** @type {string[]} */ (gate.argv)));
+  if (gate.env !== undefined) {
+    if (gate.env === null || typeof gate.env !== 'object' || Array.isArray(gate.env)) {
+      messages.push(`gates.${key}.env must be a map of variable names to string values`);
+    } else {
+      for (const [name, envValue] of Object.entries(gate.env)) {
+        if (!ENV_NAME.test(name)) messages.push(`gates.${key}.env: ${JSON.stringify(name)} is not a variable name (letters, digits and _, not starting with a digit)`);
+        else if (typeof envValue !== 'string') messages.push(`gates.${key}.env.${name} must be a string`);
+      }
     }
   }
-  return issues;
+  return messages;
+}
+
+function checkGatesNotArgvArray(cfg) {
+  return GATE_KEYS.flatMap((key) => gateMessages(key, cfg?.gates?.[key]).map((message) => ({ rule: 'gates-not-argv-array', severity: 'error', message })));
 }
 
 // ── 10. secret-looking-value (ERROR) ────────────────────────────────────────