@codedology/code-forge 0.3.2 → 0.5.0

package/src/cli/facts.mjs

@@ -16,7 +16,7 @@ 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 { redact, writeSafe } from '../util/redact.mjs';
 import { slugFor } from './run.mjs';
 import { exitCodeFor } from './spawn.mjs';
 
@@ -34,6 +34,19 @@ function readable(file, { fileOnly = false } = {}) {
   }
 }
 
+/**
+ * One stderr line for a downgraded row: the id must be `F<n>` (else `F?`), the reason is redacted
+ * and every control character (newlines included) becomes a space, so a row is always one line.
+ * @param {{fact_id: string, reason: string}} d
+ * @returns {string}
+ */
+export function downgradeLine(d) {
+  const id = /^F\d+$/.test(String(d.fact_id)) ? d.fact_id : 'F?';
+  // eslint-disable-next-line no-control-regex
+  const reason = redact(String(d.reason).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
+  return `facts: ${id} not counted — ${reason}\n`;
+}
+
 const USAGE = 'usage: code-forge facts --brief <file> [--sources <path>...] [--out <file>] [--run <id>] [--timeout <seconds>]\n';
 
 /**
@@ -107,6 +120,8 @@ export async function runFactsVerb(args, deps = {}) {
       return exitCodeFor(result);
     }
     const facts = result.facts ?? [];
+    // B39: a row whose check broke a rule is kept as UNVERIFIABLE (not counted); say so, exit 0
+    for (const d of result.downgraded ?? []) writeSafe(stderr, downgradeLine(d));
     writeSafe(stdout, `${JSON.stringify({ out: outPath, claims: result.claims.length, verified: facts.filter((f) => f.tag === 'VERIFIED').length })}\n`);
     return 0;
   } catch (err) {

package/src/cli/jev.mjs

@@ -5,6 +5,19 @@
  * `src/decide/**` directly rather than shelling out to this verb).
  *
  *   jev ask <id> --state <file.json> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]
+ *           [--block <id>] [--plan <file>] [--rules]
+ *
+ * B36: `--block` records the block the answer is for (and `--plan` the plan file's base name) on
+ * the decision row — `plan check` refuses a block whose level is not the lane recorded this way.
+ * `--rules` answers `lane`, `risk` or `security_sensitive` with the deterministic fallback rules
+ * (`decide/fallback-rules.mjs`, for a run without Jev): the state file is then an object carrying
+ * all six fallback facts (`filesChanged`, `linesAdded` numbers; `touchesMigration`,
+ * `touchesPolicyOrMiddleware`, `pathFloorHit` booleans; `keywordsFound` a string list) — a missing
+ * or mistyped one is a usage error naming it, with nothing recorded. `system1.disable` still
+ * applies. No key is resolved, no request is sent, and the row says `source: 'rules'`.
+ * The ledger slug is `--slug`, else `project.slug`, else the directory-name slug `run` and
+ * `author` use (`slugFor`; B36 — it used to fall back to `code-forge`). An unknown flag is a usage
+ * error.
  *
  * 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
@@ -23,24 +36,74 @@ 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 { resolveDispatchQuestionsByRules } from '../decide/fallback-rules.mjs';
 import { createDefaultKeyStore, resolveKey } from '../keys/store.mjs';
 import { appendRow as realAppendRow } from '../ledger/write.mjs';
 import { writeSafe } from '../util/redact.mjs';
+import { slugFor } from './run.mjs';
+
+const USAGE = 'usage: code-forge jev ask <question-id> --state <file> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>] [--block <id>] [--plan <file>] [--rules]\n';
+
+/** The block id shape the run record uses (`state/block.mjs`). */
+const BLOCK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+
+/** Flags that take a value, and the one boolean flag. */
+const VALUE_FLAGS = Object.freeze(['--state', '--cwd', '--slug', '--key-ref', '--block', '--plan']);
+const BOOLEAN_FLAGS = Object.freeze(['--rules']);
+
+/**
+ * Strict flag walk over everything after `ask <id>`: a value flag takes the next token (never one
+ * that starts with `--`, so a bare `--slug --cwd x` never reads `--cwd` as the slug), a boolean
+ * flag takes none, and an unknown token, a repeated flag or a missing value is a usage error.
+ * @param {string[]} rest
+ * @returns {{ok: true, values: Record<string, string>, booleans: Set<string>} | {ok: false}}
+ */
+function parseAskFlags(rest) {
+  /** @type {Record<string, string>} */
+  const values = {};
+  const booleans = new Set();
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (BOOLEAN_FLAGS.includes(arg)) {
+      if (booleans.has(arg)) return { ok: false };
+      booleans.add(arg);
+      continue;
+    }
+    if (!VALUE_FLAGS.includes(arg) || Object.hasOwn(values, arg)) return { ok: false };
+    const next = rest[i + 1];
+    if (next === undefined || next.startsWith('--')) return { ok: false };
+    values[arg] = next;
+    i += 1;
+  }
+  return { ok: true, values, booleans };
+}
 
-const USAGE = 'usage: code-forge jev ask <question-id> --state <file> [--cwd <dir>] [--slug <slug>] [--key-ref <ref>]\n';
+/** The six fallback facts `--rules` needs, each with its type (`decide/fallback-rules.mjs`). */
+const RULE_FACTS = Object.freeze({
+  filesChanged: 'number',
+  linesAdded: 'number',
+  touchesMigration: 'boolean',
+  touchesPolicyOrMiddleware: 'boolean',
+  pathFloorHit: 'boolean',
+  keywordsFound: 'string[]',
+});
 
 /**
- * @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.
+ * @param {unknown} state
+ * @returns {string[]} the fallback facts that are missing or of the wrong type (all six when the
+ *   state is not a plain object).
  */
-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 };
+function badRuleFacts(state) {
+  if (state === null || typeof state !== 'object' || Array.isArray(state)) return Object.keys(RULE_FACTS);
+  const facts = /** @type {Record<string, unknown>} */ (state);
+  return Object.entries(RULE_FACTS)
+    .filter(([name, type]) => {
+      const v = facts[name];
+      if (type === 'number') return typeof v !== 'number' || !Number.isFinite(v) || v < 0;
+      if (type === 'boolean') return typeof v !== 'boolean';
+      return !Array.isArray(v) || !v.every((k) => typeof k === 'string');
+    })
+    .map(([name]) => name);
 }
 
 /**
@@ -82,14 +145,31 @@ export async function runJev(args, deps = {}) {
     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) {
+  const parsed = parseAskFlags(args.slice(2));
+  if (!parsed.ok || parsed.values['--state'] === undefined) {
     err(USAGE);
     return 2;
   }
+  const stateFlag = { value: parsed.values['--state'] };
+  const cwdFlag = { value: parsed.values['--cwd'] };
+  const slugFlag = { value: parsed.values['--slug'] };
+  const keyRefFlag = { value: parsed.values['--key-ref'] };
+  const blockFlag = { value: parsed.values['--block'] };
+  const planFlag = { value: parsed.values['--plan'] };
+  if (blockFlag.value !== undefined && !BLOCK_ID.test(blockFlag.value)) {
+    err('jev ask: --block must be a block id (letters, digits, . _ -; at most 32 characters)\n');
+    return 2;
+  }
+  const rules = parsed.booleans.has('--rules');
+  /** @type {Record<string, unknown>} */
+  const scope = {
+    ...(blockFlag.value !== undefined ? { block: blockFlag.value } : {}),
+    ...(planFlag.value !== undefined ? { plan: path.basename(planFlag.value) } : {}),
+  };
+  if (rules && !['lane', 'risk', 'security_sensitive'].includes(id)) {
+    err(`jev ask: no rule answers "${id}" (--rules covers lane, risk, security_sensitive)\n`);
+    return 2;
+  }
   const cwd = cwdFlag.value ?? process.cwd();
 
   let state;
@@ -110,11 +190,28 @@ export async function runJev(args, deps = {}) {
     return 1;
   }
 
+  // the same ledger as the rest of the tool: --slug, else project.slug, else the directory name
+  const slug = slugFlag.value ?? slugFor(cfg, cwd);
+
   if (isQuestionDisabled(id, cfg)) {
     err(`jev ask: question "${id}" is disabled by system1.disable\n`);
     return 1;
   }
 
+  if (rules) {
+    const bad = badRuleFacts(state);
+    if (bad.length > 0) {
+      err(`jev ask: --rules needs the fallback facts in the --state object; missing or wrong type: ${bad.join(', ')}\n`);
+      return 2;
+    }
+    const byRules = resolveDispatchQuestionsByRules(state);
+    const value = byRules[/** @type {'lane'|'risk'|'security_sensitive'} */ (id)].value;
+    const decisionId = makeId();
+    await write({ event: 'decision', decision_id: decisionId, question: id, answer: value, source: 'rules', ...scope }, { slug });
+    out(`${JSON.stringify({ decision_id: decisionId, question: id, answer: value, source: 'rules', ...scope }, null, 2)}\n`);
+    return 0;
+  }
+
   const keyStore = store ?? (await createDefaultKeyStore(env));
   const keyRef = keyRefFlag.value ?? cfg?.keys?.jev;
   let resolved;
@@ -146,7 +243,6 @@ export async function runJev(args, deps = {}) {
     return 1;
   }
   const decision = decide(id, answer, cfg);
-  const slug = slugFlag.value ?? cfg?.project?.slug ?? 'code-forge';
   const decisionId = makeId();
 
   await write(
@@ -159,6 +255,7 @@ export async function runJev(args, deps = {}) {
       confidence: decision.confidence,
       margin: decision.margin,
       source: 'jev',
+      ...scope,
       tokens_in: result.usage?.input_tokens,
       tokens_out: result.usage?.output_tokens,
     },

package/src/cli/ledger.mjs

@@ -6,13 +6,20 @@
  *   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>]
+ *   ledger tail --slug <slug> [--n <count> | -n <count>]
+ *   ledger add coder --run <r> --block <b> --usd <n> [--note "..."]
+ *
+ * B33: `ledger add coder` records manual/cloud coder spend (a session code-forge never saw) as a
+ * signed `session` row (`role: coder, manual: true, usd, cost_source: manual`) in the run's
+ * ledger, so `report` and the `budget.usd` check count it. The slug is the run record's project.
  */
 
 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';
+import { roundUsd, runSpend } from '../ledger/spend.mjs';
+import { appendRow, readAllRows } from '../ledger/write.mjs';
+import { readRun, writeSigned } from '../state/run.mjs';
 
 /**
  * @param {string[]} args @param {string} flag
@@ -56,9 +63,10 @@ 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 usage = () => err('usage: code-forge ledger calibration|outcome|tail --slug <slug> [...]  (tail: [--n|-n <count>]) | add coder --run <r> --block <b> --usd <n> [--note "..."]\n');
 
   const [sub] = args;
+  if (sub === 'add') return addSpend(args.slice(1), { out, err });
   const slug = flagValue(args, '--slug');
   if (!slug) {
     usage();
@@ -126,15 +134,22 @@ export async function runLedger(args, deps = {}) {
     }
 
     if (sub === 'tail') {
-      const nFlag = readOptionalFlag(args, '--n');
-      if (!nFlag.ok) {
-        err('ledger tail: --n requires a value\n');
+      // `-n` is the spelling everyone types from `tail(1)`; before B31 it was not recognised, so
+      // `ledger tail -n 3` silently printed the default 20 rows (issue #2, field note 8).
+      const longN = readOptionalFlag(args, '--n');
+      const shortN = readOptionalFlag(args, '-n');
+      if (!longN.ok || !shortN.ok) {
+        err(`ledger tail: ${longN.ok ? '-n' : '--n'} requires a value\n`);
+        return 2;
+      }
+      if (longN.value !== undefined && shortN.value !== undefined) {
+        err('ledger tail: give the count once, as --n <count> or -n <count>\n');
         return 2;
       }
-      const nArg = nFlag.value ?? '20';
+      const nArg = longN.value ?? shortN.value ?? '20';
       const n = parseNonNegativeInt(nArg);
       if (n === null) {
-        err(`ledger tail: --n must be a non-negative integer, got "${nArg}"\n`);
+        err(`ledger tail: --n/-n must be a non-negative integer, got "${nArg}"\n`);
         return 2;
       }
       const rows = await readAllRows(slug);
@@ -154,6 +169,82 @@ export async function runLedger(args, deps = {}) {
   return 2;
 }
 
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_NOTE_CHARS = 500;
+
+/**
+ * `ledger add coder --run <r> --block <b> --usd <n> [--note "..."]` (B33).
+ * @param {string[]} args - after `add`.
+ * @param {{out: (s: string) => void, err: (s: string) => void}} io
+ * @returns {Promise<number>}
+ */
+async function addSpend(args, { out, err }) {
+  const usage = () => err('usage: code-forge ledger add coder --run <r> --block <b> --usd <n> [--note "..."]\n');
+  const [role] = args;
+  const run = flagValue(args, '--run');
+  const block = flagValue(args, '--block');
+  const usdArg = flagValue(args, '--usd');
+  if (role !== 'coder' || !run || !block || usdArg === undefined) {
+    usage();
+    return 2;
+  }
+  const note = readOptionalFlag(args, '--note');
+  if (!note.ok) {
+    err('ledger add: --note requires a value\n');
+    return 2;
+  }
+  if (!ID.test(run)) {
+    err('ledger add: --run must be a run id (letters, digits, ".", "_", "-")\n');
+    return 2;
+  }
+  if (!ID.test(block)) {
+    err('ledger add: --block must be a block id (letters, digits, ".", "_", "-")\n');
+    return 2;
+  }
+  // rounded to the ledger's 4 decimals FIRST, then checked: 0.00001 rounds to 0 and is refused
+  const usd = /^\d+(\.\d+)?$/.test(usdArg) ? roundUsd(Number(usdArg)) : Number.NaN;
+  if (!Number.isFinite(usd) || usd <= 0) {
+    err(`ledger add: --usd must be a number > 0 (at 4 decimals), got "${usdArg}"\n`);
+    return 2;
+  }
+  if (note.value !== undefined && note.value.length > MAX_NOTE_CHARS) {
+    err(`ledger add: --note is longer than ${MAX_NOTE_CHARS} characters\n`);
+    return 2;
+  }
+  try {
+    const { project } = await readRun(run);
+    const writeRow = (/** @type {Record<string, any>} */ row) => appendRow(row, { slug: project });
+    const row = {
+      event: 'session',
+      role: 'coder',
+      manual: true,
+      block,
+      provider: null,
+      level: null,
+      tokens_in: null,
+      tokens_out: null,
+      usd,
+      cost_source: 'manual',
+      ...(note.value !== undefined ? { note: note.value } : {}),
+    };
+    await writeSigned(run, writeRow, row);
+    // the row is written: from here on nothing may throw or change the exit code
+    /** @type {number | null} */
+    let total = null;
+    try {
+      const spent = runSpend(await readAllRows(project), run).usd;
+      total = Number.isFinite(spent) ? spent : null;
+    } catch {
+      total = null;
+    }
+    out(`recorded coder spend $${usd.toFixed(4)} for run ${run} block ${block} · run total ${total === null ? 'unknown' : `$${total.toFixed(4)}`}\n`);
+    return 0;
+  } catch (thrown) {
+    err(`ledger add: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+}
+
 /** @param {string[]} args @returns {Promise<number>} */
 export default async function ledger(args) {
   return runLedger(args);