@codedology/code-forge 0.8.0 → 0.10.0

package/src/cli/keys.mjs

@@ -5,43 +5,96 @@
  * message would be masked once the chain registered it.
  *
  *   keys list
- *   keys set <name> [--op <ref>]         hidden prompt, or read once from 1Password and cache 8 h
+ *   keys set <name> [--op <ref> [--cache-hours <n>]]
+ *                                        hidden prompt, or read once from 1Password and cache it
  *   keys test <name> [--ref <ref>]       resolve through the chain (no prompt)
  *   keys remove <name>
  *
+ * Cache time (B84): `--cache-hours` (only with `--op`; a typed key never expires), else
+ * `keys.cache_hours` from the `.code-forge.yml` of the project root of the current directory, else
+ * 8 h — whole hours from 1 to 24. `keys set --op` and `keys test` read that config; a missing file
+ * is the default, a file that cannot be loaded is the default with one WARN line. An invalid
+ * `--cache-hours`, or an invalid `keys.cache_hours` for `set --op`, exits 2 before any 1Password
+ * call; `keys test` warns once and uses 8 h for an invalid `keys.cache_hours` (as `jev ask` does).
+ * A cached entry is never
+ * trusted for longer than those hours (`store.read`).
+ *
+ * Expiry warning (B85): `keys list` keeps its stdout table and writes one stderr line per key with
+ * less than 1 hour left — `WARN <name> expires in <m> min; re-link: code-forge keys set <name> --op
+ * <ref>` — naming the `op://` reference from the index row, or a placeholder for a row written
+ * before the index carried it.
+ *
  * An `--op`/`--ref` value may be a 1Password item ID or item link instead of `op://vault/item/field`:
  * it is resolved to `op://<vaultId>/<itemId>/<fieldId>` first (`op item get`, B25).
  *
  * Every name is validated before any store call, on every subcommand.
  */
 
+import path from 'node:path';
 import { writeSafe } from '../util/redact.mjs';
+import { DEFAULT_CONFIG_FILENAME, loadConfigFile, projectRootFor } from '../config/load.mjs';
 import { describeOpItem, isOpRef, OP_APPROVE_NOTE, OP_MESSAGES, opItemIdFromInput, toOpRef } from '../keys/onepassword.mjs';
-import { assertKeyName, createDefaultKeyStore, parseRef, readOpAndCache, resolveKey } from '../keys/store.mjs';
+import { assertKeyName, CACHE_HOURS_RULE, cacheHoursFrom, createDefaultKeyStore, DEFAULT_CACHE_HOURS, isCacheHours, isTime, parseRef, readOpAndCache, resolveKey, shellWord } from '../keys/store.mjs';
+
+const USAGE = 'usage: code-forge keys list | set <name> [--op <item-id|link|op://ref> [--cache-hours <1-24>]] | test <name> [--ref <ref>] | remove <name>\n';
 
-const USAGE = 'usage: code-forge keys list | set <name> [--op <item-id|link|op://ref>] | test <name> [--ref <ref>] | remove <name>\n';
+/** The flags each subcommand accepts (list and remove take none); each at most once, any order. */
+const FLAGS = /** @type {Record<string, string[]>} */ ({ list: [], set: ['--op', '--cache-hours'], test: ['--ref'], remove: [] });
+
+/**
+ * @param {string} text
+ * @returns {number | null} the whole number of hours `text` spells (digits only) within the
+ *   bounds, else null.
+ */
+export function parseCacheHours(text) {
+  if (!/^[0-9]{1,3}$/.test(text)) {
+    return null;
+  }
+  const hours = Number(text);
+  return isCacheHours(hours) ? hours : null;
+}
 
-/** 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 });
+/** Below this much time left, `keys list` warns (B85). */
+const WARN_BELOW_MS = 3_600_000;
+
+/**
+ * @param {{name: string, exp: number|null, ref?: string}} row
+ * @param {number} now
+ * @returns {string|null} the stderr warning for a key with less than 1 hour left, else null (also
+ *   for an `exp` that is not a valid time).
+ */
+export function expiryWarning(row, now) {
+  if (!isTime(row.exp) || row.exp <= now || row.exp - now >= WARN_BELOW_MS) {
+    return null;
+  }
+  // whole minutes left, never 0 and never 60 (under 1 hour is at most 59 min 59 s)
+  const minutes = Math.max(1, Math.floor((row.exp - now) / 60_000));
+  const ref = typeof row.ref === 'string' ? shellWord(row.ref) : '<your 1Password reference>';
+  return `WARN ${row.name} expires in ${minutes} min; re-link: code-forge keys set ${row.name} --op ${ref}\n`;
+}
 
 /**
  * @param {number|null} exp
  * @param {number} now
- * @returns {string}
+ * @returns {string} `unknown` for an `exp` that is not a valid time (a hand-edited index).
  */
 export function formatExpiry(exp, now) {
   if (exp === null) {
     return 'never';
   }
+  if (!isTime(exp)) {
+    return 'unknown';
+  }
   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.
+ * Strict parse: `<sub> [<name>] [<flag> <value>]...` — the name first, then the subcommand's flags,
+ * each at most once, in any order. A flag with no value, a value that looks like a flag, a name
+ * that looks like a flag, an unknown or repeated flag, an extra argument, or `--cache-hours`
+ * without `--op` (a typed key never expires) is a usage error — never silently reinterpreted.
  * @param {string[]} args
- * @returns {{sub: string, name?: string, flagArg?: string} | null}
+ * @returns {{sub: string, name?: string, flagArg?: string, cacheHoursArg?: string} | null}
  */
 export function parseKeysArgs(args) {
   const [sub, ...rest] = args;
@@ -51,17 +104,77 @@ export function parseKeysArgs(args) {
   if (sub === 'list') {
     return rest.length === 0 ? { sub } : null;
   }
-  const [name, flagName, flagArg, ...extra] = rest;
-  if (typeof name !== 'string' || name.startsWith('-') || extra.length > 0) {
+  const [name, ...flags] = rest;
+  if (typeof name !== 'string' || name.startsWith('-') || flags.length % 2 !== 0) {
     return null;
   }
-  if (flagName === undefined) {
-    return { sub, name };
+  /** @type {Record<string, string>} */
+  const values = {};
+  for (let i = 0; i < flags.length; i += 2) {
+    const flagName = flags[i];
+    const value = flags[i + 1];
+    if (!FLAGS[sub].includes(flagName) || Object.hasOwn(values, flagName) || value.length === 0 || value.startsWith('-')) {
+      return null;
+    }
+    values[flagName] = value;
   }
-  if (flagName !== FLAGS[sub] || typeof flagArg !== 'string' || flagArg.length === 0 || flagArg.startsWith('-')) {
+  if (values['--cache-hours'] !== undefined && values['--op'] === undefined) {
     return null;
   }
-  return { sub, name, flagArg };
+  const flagArg = sub === 'set' ? values['--op'] : values['--ref'];
+  return {
+    sub,
+    name,
+    ...(flagArg !== undefined ? { flagArg } : {}),
+    ...(values['--cache-hours'] !== undefined ? { cacheHoursArg: values['--cache-hours'] } : {}),
+  };
+}
+
+/**
+ * The cache time for `keys set --op` / `keys test`: `--cache-hours`, else `keys.cache_hours` from
+ * the project config, else 8. An invalid flag fails closed; an invalid `keys.cache_hours` fails
+ * closed when `strict` (`set --op`) and otherwise (`test`) gives the default with one warning. A
+ * config that cannot be loaded gives the default with one warning (`keys` must keep working beside
+ * an unrelated config error).
+ * @param {string|undefined} cacheHoursArg
+ * @param {string} cwd
+ * @param {typeof loadConfigFile} loadConfig
+ * @param {boolean} strict - true for `set --op`: an invalid `keys.cache_hours` refuses.
+ * @returns {Promise<{ok: true, hours: number, from: string|null, warning: string|null} | {ok: false, message: string}>}
+ *   `from` names where hours other than the default came from.
+ */
+async function cacheHoursFor(cacheHoursArg, cwd, loadConfig, strict) {
+  let fromFlag = null;
+  if (cacheHoursArg !== undefined) {
+    fromFlag = parseCacheHours(cacheHoursArg);
+    if (fromFlag === null) {
+      return { ok: false, message: `keys: --cache-hours must be ${CACHE_HOURS_RULE}\n` };
+    }
+  }
+  const loaded = await loadConfig(path.join(projectRootFor(cwd), DEFAULT_CONFIG_FILENAME));
+  /** @type {string|null} */
+  let warning = null;
+  /** @type {Record<string, any>} */
+  let cfg = {};
+  if (loaded.ok) {
+    cfg = loaded.config ?? {};
+  } else if (loaded.error !== 'not-found') {
+    // the error class only, never the loader's message; the WARN names the hours really used
+    const used = fromFlag !== null ? `${fromFlag} h from --cache-hours` : `the default ${DEFAULT_CACHE_HOURS} h`;
+    warning = `WARN keys: ${DEFAULT_CONFIG_FILENAME} cannot be loaded (${loaded.error}); caching for ${used}\n`;
+  }
+  const fromConfig = cacheHoursFrom(cfg);
+  if (fromConfig.problem !== null) {
+    if (strict) {
+      return { ok: false, message: `keys: ${fromConfig.problem} (${DEFAULT_CONFIG_FILENAME})\n` };
+    }
+    // fromConfig.hours is already the default here
+    warning = `WARN keys: ${fromConfig.problem} (${DEFAULT_CONFIG_FILENAME}); caching for the default ${fromConfig.hours} h\n`;
+  }
+  if (fromFlag !== null) {
+    return { ok: true, hours: fromFlag, from: '--cache-hours', warning };
+  }
+  return { ok: true, hours: fromConfig.hours, from: fromConfig.source === 'config' ? 'keys.cache_hours' : null, warning };
 }
 
 /** @param {string} name */
@@ -82,9 +195,11 @@ async function askHidden(name) {
  * @param {typeof import('../util/exec.mjs').exec} [deps.opExec] - runs `op item get` for an item ID or link.
  * @param {NodeJS.ProcessEnv} [deps.env]
  * @param {number} [deps.now]
+ * @param {string} [deps.cwd] - the project config is read at the project root of this directory.
+ * @param {typeof loadConfigFile} [deps.loadConfig]
  * @returns {Promise<number>}
  */
-export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, opExec, env = process.env, now = Date.now() }) {
+export async function runKeys(args, { store, stdout = process.stdout, stderr = process.stderr, ask = askHidden, opRead, opExec, env = process.env, now = Date.now(), cwd = process.cwd(), loadConfig = loadConfigFile }) {
   const out = (/** @type {string} */ s) => writeSafe(stdout, s);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
 
@@ -93,7 +208,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(USAGE);
     return 2;
   }
-  const { sub, name } = parsed;
+  const { sub, name, cacheHoursArg } = parsed;
   let { flagArg } = parsed;
   try {
     if (name !== undefined) {
@@ -103,6 +218,21 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     err(`keys: ${e.message}\n`);
     return 2;
   }
+  // B84: the cache time is settled before any 1Password call (`set --op` and `test` may cache);
+  // only `set --op` refuses an invalid keys.cache_hours, `test` warns once and uses 8 h
+  /** @type {{hours: number, from: string|null}} */
+  let cache = { hours: DEFAULT_CACHE_HOURS, from: null };
+  if (sub === 'test' || (sub === 'set' && flagArg !== undefined)) {
+    const found = await cacheHoursFor(cacheHoursArg, cwd, loadConfig, sub === 'set');
+    if ('message' in found) {
+      err(found.message);
+      return 2;
+    }
+    if (found.warning !== null) {
+      err(found.warning);
+    }
+    cache = found;
+  }
   const fullRef = flagArg !== undefined && isOpRef(flagArg);
   const itemId = flagArg !== undefined && !fullRef ? opItemIdFromInput(flagArg) : null;
   if (sub === 'set' && flagArg !== undefined && !fullRef && itemId === null) {
@@ -147,6 +277,10 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     for (const row of rows) {
       out(`${row.name}\t${row.source}\t${row.backend}\t${formatExpiry(row.exp, now)}\n`);
     }
+    for (const row of rows) {
+      const warning = expiryWarning(row, now);
+      if (warning !== null) err(warning);
+    }
     return 0;
   }
 
@@ -157,7 +291,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
   }
 
   if (sub === 'test') {
-    const res = await resolveKey(name, { store, ref: flagArg, env, opRead, now });
+    const res = await resolveKey(name, { store, ref: flagArg, env, opRead, now, cacheHours: cache.hours });
     for (const e of res.errors) {
       err(`${name}: ${e}\n`);
     }
@@ -170,7 +304,7 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
   }
 
   if (flagArg !== undefined) {
-    const res = await readOpAndCache(name, flagArg, { store, opRead, now });
+    const res = await readOpAndCache(name, flagArg, { store, opRead, now, cacheHours: cache.hours });
     for (const e of res.errors) {
       err(`${name}: ${e}\n`);
     }
@@ -178,7 +312,8 @@ export async function runKeys(args, { store, stdout = process.stdout, stderr = p
     if (res.value === null) {
       return 1;
     }
-    out(`stored ${name} in ${store.writer} (source=op, expires=${formatExpiry(res.exp, now)})\n`);
+    const from = cache.from === null ? '' : ` (cache ${cache.hours} h from ${cache.from})`;
+    out(`stored ${name} in ${store.writer} (source=op, expires=${formatExpiry(res.exp, now)})${from}\n`);
     return 0;
   }
 

package/src/cli/proof.mjs

@@ -16,6 +16,9 @@
  *                             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`.
+ *                             B87: a test file a `proof.runners` entry of the run snapshot matches
+ *                             runs with that entry's argv and is read from its JUnit report; the
+ *                             row and the output then carry `runner`, `env_keys` and `failed_tests`.
  *
  * `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
@@ -35,12 +38,14 @@ 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 { proofRunners } from '../state/config-snapshot.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 { adapterPrecheck, runnerCovers, runnerHook, runnerTimeoutMs, selectRunner } from '../proof/runners.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { blockFileSet, repoRelativePath } from '../review/gate-check.mjs';
@@ -83,13 +88,15 @@ async function assertTestFile(dir, file) {
 
 /**
  * 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.
+ * with the Node that runs this CLI. Other stacks need a `proof.runners` entry (B87).
  * @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');
+  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 — add a proof.runners entry for it (see proof.md §2)');
+  }
   const pattern = testCase === undefined ? [] : ['--test-name-pattern', `^${testCase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`];
   return [process.execPath, '--test', ...pattern, file];
 }
@@ -178,11 +185,14 @@ async function exportAndRecord({ runId, record, blockId, block, place, config, w
 
 /**
  * @param {string[]} args
- * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}}} [deps]
+ * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown},
+ *   precheck?: (entry: import('../proof/runners.mjs').RunnerEntry) => Promise<void>,
+ *   hook?: (entry: import('../proof/runners.mjs').RunnerEntry, test: {file: string, testCase?: string}) => import('../proof/runners.mjs').RunnerHook | null}} [deps] -
+ *   `precheck` and `hook` are test-only seams for the runner adapter's precheck and hook (B87)
  * @returns {Promise<number>}
  */
 export async function runProof(args, deps = {}) {
-  const { stdout = process.stdout, stderr = process.stderr } = deps;
+  const { stdout = process.stdout, stderr = process.stderr, precheck = adapterPrecheck, hook = runnerHook } = deps;
   const out = (/** @type {object} */ value) => writeSafe(stdout, `${redactJSON(value)}\n`);
   const err = (/** @type {string} */ s) => writeSafe(stderr, s);
   const [sub, ...rest] = args;
@@ -270,9 +280,17 @@ export async function runProof(args, deps = {}) {
       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);
+      // B87: the runner comes from the run snapshot only, never the live file; no entry matches ⇒
+      // the built-in node:test command, or the refusal
+      const runners = proofRunners(record);
+      const entry = selectRunner(runners, file);
+      const runner = entry === null ? null : (hook(entry, { file, testCase }) ?? null);
+      // a matched entry is run by its hook or not at all: never a node:test fallback (no row, no precheck)
+      if (entry !== null && runner === null) throw new StateError('usage', `the ${entry.adapter} runner for ${file} has no hook; no proof was run`);
+      // exactly one of the two: the built-in argv without a runner, the runner (its own argv) with one
+      const how = runner === null || entry === null ? { argv: filteredTestArgv(file, testCase) } : { runner, timeoutMs: runnerTimeoutMs(entry) };
       const block = record.blocks?.[blockId];
       if (block?.status !== 'open') throw new StateError('no-block', `block ${blockId} is not open in run ${runId}`);
       const place = await proofPlace(runId, record, blockId, block);
@@ -292,17 +310,20 @@ export async function runProof(args, deps = {}) {
         owned: block.owned_files,
         matchOwned: (f) => ownsFile(block.owned_files, f, block.owned_kinds),
       });
-      const sources = mechanism === 'assertion-deletion' ? [] : changed.map((c) => c.file).filter((f) => f !== file && !TEST_PATH.test(f));
+      // B87: a file a configured runner matches is a test too, never a source
+      const sources = mechanism === 'assertion-deletion' ? [] : changed.map((c) => c.file).filter((f) => f !== file && !TEST_PATH.test(f) && !runnerCovers(runners, 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`);
       }
+      // B87: the adapter's precheck runs before the export is built and before any file is reverted
+      if (entry !== null) await precheck(entry);
       const exp = isolation === 'export' ? await exportAndRecord({ runId, record, blockId, block, place, 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 : place.dir,
         repoDir: place.dir,
         base: place.base,
-        argv,
+        ...how,
         test: { file, ...(testCase === undefined ? {} : { case: testCase }), characterization: mechanism === 'assertion-deletion' },
         sources,
         isolation,
@@ -317,6 +338,11 @@ export async function runProof(args, deps = {}) {
       // 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;
+      // B87: only when a runner really ran, names only — its adapter, the bounded failed test names
+      // and the env variable names (row and JSON alike); `failed_ids` stays in memory, and env
+      // values are never shown
+      const runnerFields =
+        runner === null ? {} : { runner: runner.adapter, failed_tests: red !== null && 'failed_tests' in red ? red.failed_tests : [], env_keys: [...runner.env_keys] };
       await recordProof({
         runId,
         writeRow,
@@ -332,6 +358,7 @@ export async function runProof(args, deps = {}) {
           proven,
           failed: red?.failed ?? null,
           covers,
+          ...runnerFields,
         },
       });
       out({
@@ -343,6 +370,7 @@ export async function runProof(args, deps = {}) {
         red_kind: red?.red_kind ?? null,
         green: result.green ?? null,
         proven,
+        ...runnerFields,
         ...(exp ? { export: { dir: exp.dir, restored: exp.restored, untracked: exp.untracked } } : {}),
       });
       return proven ? 0 : 1;