@izkac/forgekit 0.3.14 → 0.3.16

package/src/findings-cli.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * `forge finding` — file, list and close findings (see findings.mjs).
+ *
+ * Usage:
+ *   forge finding add "<text>" [--change <slug>] [--severity blocker|major|minor|note]
+ *   forge finding list [--json] [--all]
+ *   forge finding resolve <id> [--note "<text>"]
+ */
+
+import { FORGE_DIR, loadSession, readActive } from './lib.mjs';
+import { addFinding, readFindings, resolveFinding } from './findings.mjs';
+
+function usage() {
+  process.stderr.write(
+    `Usage:
+  forge finding add "<text>" [--change <slug>] [--severity blocker|major|minor|note]
+  forge finding list [--json] [--all]
+  forge finding resolve <id> [--note "<text>"]
+`,
+  );
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function emit(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/** Active session, or nulls — findings are often filed between sessions. */
+function activeSessionInfo() {
+  try {
+    const active = readActive();
+    if (!active?.sessionId) return { sessionId: null, slug: null };
+    const { session } = loadSession(active.sessionId);
+    return { sessionId: session.id ?? null, slug: session.slug ?? null };
+  } catch {
+    return { sessionId: null, slug: null };
+  }
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  usage();
+  process.exit(cmd ? 0 : 1);
+}
+
+if (cmd === 'add') {
+  const text = argv[1] ?? '';
+  if (!text.trim() || text.startsWith('--')) {
+    fail('A finding needs text: forge finding add "<text>"');
+  }
+  let change = null;
+  let severity = 'major';
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--change' && argv[i + 1]) change = argv[(i += 1)];
+    else if (argv[i] === '--severity' && argv[i + 1]) severity = argv[(i += 1)];
+    else fail(`Unknown argument: ${argv[i]}`);
+  }
+  try {
+    const entry = addFinding({
+      forgeDir: FORGE_DIR,
+      text,
+      severity,
+      change,
+      session: activeSessionInfo(),
+    });
+    emit({
+      ok: true,
+      ...entry,
+      next: change
+        ? `Open its home: forge change new ${change}`
+        : 'Give it a home: forge change new <slug>, forge defer add, or fix it now — otherwise label it a note (--severity note).',
+    });
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+  process.exit(0);
+}
+
+if (cmd === 'list') {
+  const all = argv.includes('--all');
+  const entries = readFindings(FORGE_DIR);
+  const open = entries.filter((e) => e.status === 'open');
+  const resolved = entries.filter((e) => e.status !== 'open');
+  if (argv.includes('--json')) {
+    emit({ open, resolved: all ? resolved : resolved.slice(-10), total: entries.length });
+    process.exit(0);
+  }
+  if (entries.length === 0) {
+    process.stdout.write('No findings recorded. File one: forge finding add "<text>"\n');
+    process.exit(0);
+  }
+  const rows = (all ? entries : open).map(
+    (e) =>
+      `${e.id}  ${String(e.severity ?? 'major').padEnd(7)} ${e.status === 'open' ? ' ' : '✓'} ${e.text}${
+        e.change ? `  → ${e.change}` : ''
+      }`,
+  );
+  process.stdout.write(
+    `${rows.join('\n')}\n\n${open.length} open, ${resolved.length} resolved${
+      all ? '' : ' (--all to see resolved)'
+    }\n`,
+  );
+  process.exit(0);
+}
+
+if (cmd === 'resolve') {
+  const id = argv[1];
+  if (!id) fail('Usage: forge finding resolve <id> [--note "<text>"]');
+  let note = null;
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--note' && argv[i + 1]) note = argv[(i += 1)];
+    else fail(`Unknown argument: ${argv[i]}`);
+  }
+  try {
+    emit({ ok: true, ...resolveFinding({ forgeDir: FORGE_DIR, id, note }) });
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+  process.exit(0);
+}
+
+usage();
+fail(`Unknown subcommand: ${cmd}`);

package/src/findings.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Findings ledger — give an observation a home the day it is written.
+ *
+ * Analysis reports kept re-listing the same unactioned items ("untick 6.2",
+ * "the e2e parallel race", "grouping.ts D1 extraction") because nothing turned
+ * a report line into tracked work: prose in a gitignored report is not a
+ * queue. A finding either becomes a change, a deferral, or an edit made on the
+ * spot — or it is a note, and should be labelled one.
+ *
+ * Library half (`findings-cli.mjs` is the command). Ledger:
+ * `.forge/findings.jsonl`, durable across session cleanup.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { readLedger } from './ledger.mjs';
+
+export const SEVERITIES = ['blocker', 'major', 'minor', 'note'];
+
+/** @param {string} forgeDir */
+export function findingsPath(forgeDir) {
+  return path.join(forgeDir, 'findings.jsonl');
+}
+
+/** @param {string} forgeDir */
+export function readFindings(forgeDir) {
+  return readLedger(findingsPath(forgeDir));
+}
+
+/** @param {string} forgeDir */
+export function openFindings(forgeDir) {
+  return readFindings(forgeDir).filter((f) => f && f.status === 'open');
+}
+
+/**
+ * Next id: F1, F2, … Stable across resolves so a report can cite one.
+ * @param {Record<string, any>[]} entries
+ */
+export function nextFindingId(entries) {
+  let max = 0;
+  for (const e of entries) {
+    const m = /^F(\d+)$/.exec(String(e?.id ?? ''));
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `F${max + 1}`;
+}
+
+/**
+ * @param {string} forgeDir
+ * @param {Record<string, any>[]} entries
+ */
+function writeAll(forgeDir, entries) {
+  const file = findingsPath(forgeDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`, 'utf8');
+}
+
+/**
+ * @param {{ forgeDir: string, text: string, severity?: string, change?: string | null,
+ *           session?: { sessionId?: string | null, slug?: string | null }, now?: () => Date }} opts
+ */
+export function addFinding(opts) {
+  const text = String(opts.text ?? '').trim();
+  if (!text) throw new Error('A finding needs text: forge finding add "<text>"');
+  const severity = opts.severity ?? 'major';
+  if (!SEVERITIES.includes(severity)) {
+    throw new Error(`Unknown severity "${severity}" (expected ${SEVERITIES.join(' | ')}).`);
+  }
+  const entries = readFindings(opts.forgeDir);
+  const entry = {
+    id: nextFindingId(entries),
+    text,
+    severity,
+    status: 'open',
+    change: opts.change ?? null,
+    sessionId: opts.session?.sessionId ?? null,
+    slug: opts.session?.slug ?? null,
+    createdAt: (opts.now?.() ?? new Date()).toISOString(),
+  };
+  writeAll(opts.forgeDir, [...entries, entry]);
+  return entry;
+}
+
+/**
+ * @param {{ forgeDir: string, id: string, note?: string | null, now?: () => Date }} opts
+ */
+export function resolveFinding(opts) {
+  const entries = readFindings(opts.forgeDir);
+  const idx = entries.findIndex((e) => e.id === opts.id);
+  if (idx < 0) throw new Error(`No finding with id ${opts.id}. See: forge finding list --all`);
+  if (entries[idx].status !== 'open') {
+    throw new Error(`Finding ${opts.id} is already ${entries[idx].status}.`);
+  }
+  entries[idx] = {
+    ...entries[idx],
+    status: 'resolved',
+    note: opts.note ?? entries[idx].note ?? null,
+    resolvedAt: (opts.now?.() ?? new Date()).toISOString(),
+  };
+  writeAll(opts.forgeDir, entries);
+  return entries[idx];
+}

package/src/findings.test.mjs

@@ -0,0 +1,140 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const FINDINGS = path.join(path.dirname(fileURLToPath(import.meta.url)), 'findings-cli.mjs');
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+function makeProject() {
+  const cwd = tmp('forge-finding-');
+  const sessionDir = path.join(cwd, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({
+      id: 's1',
+      slug: 'phase-1',
+      openspecChange: 'phase-1',
+      phase: 'verify',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(cwd, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  return cwd;
+}
+
+function run(cwd, args) {
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('finding-fleet-'), 's') };
+  try {
+    const stdout = execFileSync(process.execPath, [FINDINGS, ...args], { cwd, env });
+    const text = stdout.toString();
+    try {
+      return { status: 0, out: JSON.parse(text), text };
+    } catch {
+      return { status: 0, out: null, text };
+    }
+  } catch (err) {
+    return { status: err.status, out: null, text: String(err.stdout), stderr: String(err.stderr) };
+  }
+}
+
+test('a finding lands in a durable ledger with the session that raised it', () => {
+  // "A finding either gets a home the day it is written, or it is not a
+  // finding — it is a note." Three analysis reports in a row carried the same
+  // unactioned items because nothing converted a line into tracked work.
+  const cwd = makeProject();
+  const { status, out } = run(cwd, [
+    'add',
+    'smoke suite pinned --workers=1 in 6/6 changes; the shared-state race is never fixed',
+  ]);
+
+  assert.equal(status, 0);
+  assert.equal(out.ok, true);
+  assert.match(out.id, /^F\d+$/);
+
+  const ledger = path.join(cwd, '.forge', 'findings.jsonl');
+  const [entry] = fs
+    .readFileSync(ledger, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+  assert.equal(entry.status, 'open');
+  assert.equal(entry.sessionId, 's1');
+  assert.match(entry.text, /workers=1/);
+});
+
+test('a finding can name the change that will carry it', () => {
+  const cwd = makeProject();
+  const { out } = run(cwd, ['add', 'grouping.ts D1 extraction', '--change', 'fix-grouping-d1']);
+  assert.equal(out.change, 'fix-grouping-d1');
+  // The command tells you how to open that change rather than creating it
+  // behind your back.
+  assert.match(out.next, /forge change new fix-grouping-d1/);
+});
+
+test('list shows open findings and resolve closes one by id', () => {
+  const cwd = makeProject();
+  const first = run(cwd, ['add', 'server suite baseline is 1-4 varying failures']);
+  run(cwd, ['add', 'untick 6.2 in the archived tasks.md']);
+
+  const open = run(cwd, ['list', '--json']);
+  assert.equal(open.out.open.length, 2);
+
+  const resolved = run(cwd, ['resolve', first.out.id, '--note', 'quarantined the flaky names']);
+  assert.equal(resolved.status, 0);
+  assert.equal(resolved.out.status, 'resolved');
+
+  const after = run(cwd, ['list', '--json']);
+  assert.equal(after.out.open.length, 1);
+  assert.equal(after.out.resolved.length, 1);
+  assert.match(after.out.resolved[0].note, /quarantined/);
+});
+
+test('resolving an unknown id fails loudly instead of silently succeeding', () => {
+  const cwd = makeProject();
+  const { status, stderr } = run(cwd, ['resolve', 'F999']);
+  assert.equal(status, 1);
+  assert.match(stderr, /F999/);
+});
+
+test('add refuses an empty finding', () => {
+  const cwd = makeProject();
+  const { status, stderr } = run(cwd, ['add', '   ']);
+  assert.equal(status, 1);
+  assert.match(stderr, /text/i);
+});
+
+test('findings work without an active session', () => {
+  // Reports are often written between sessions; that must not block filing.
+  const cwd = tmp('forge-finding-nosession-');
+  fs.mkdirSync(path.join(cwd, '.forge'), { recursive: true });
+  const { status, out } = run(cwd, ['add', 'pace auto never selects brisk or lite']);
+  assert.equal(status, 0);
+  assert.equal(out.sessionId, null);
+});
+
+test('forge status reports open findings so they cannot be forgotten', () => {
+  const cwd = makeProject();
+  run(cwd, ['add', 'e2e parallel race unfixed']);
+  const statusScript = path.join(path.dirname(FINDINGS), 'session-status.mjs');
+  const stdout = execFileSync(process.execPath, [statusScript], {
+    cwd,
+    env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('finding-fleet-'), 's') },
+  }).toString();
+  const status = JSON.parse(stdout);
+  assert.equal(status.openFindings.count, 1);
+  assert.match(status.openFindings.latest[0].text, /parallel race/);
+});

package/src/fleet.mjs

@@ -24,6 +24,7 @@ import {
   queueMessage,
   sessionDirFor,
 } from './lib/fleet.mjs';
+import { healthCell, sessionHealth } from './health.mjs';
 
 function usage() {
   process.stderr.write(
@@ -70,21 +71,45 @@ function pad(str, len) {
   return s.length >= len ? s.slice(0, len) : s + ' '.repeat(len - s.length);
 }
 
+/**
+ * Health per entry, read from that project's session dir. A row showing a
+ * healthy-looking `27/32` while its e2e run is red and nobody has touched it
+ * for 14 hours is the failure this column exists to prevent.
+ */
+function healthFor(entry) {
+  if (entry.missing) return { state: 'unknown', line: 'missing' };
+  try {
+    const sessionDir = sessionDirFor(entry);
+    const session = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+    return sessionHealth({ cwd: entry.project, sessionDir, session });
+  } catch {
+    return { state: 'unknown', line: 'unknown' };
+  }
+}
+
 function renderTable(entries) {
   if (entries.length === 0) return 'No fleet sessions. Start one with `forge new <slug>`.\n';
-  const header = `${pad('PROJECT', 18)} ${pad('SESSION', 26)} ${pad('ENGINE', 7)} ${pad('PHASE', 18)} ${pad('TASKS', 16)} ${pad('PACE', 9)} ${pad('AGE', 4)} MSGS`;
+  const header = `${pad('PROJECT', 18)} ${pad('SESSION', 26)} ${pad('ENGINE', 7)} ${pad('PHASE', 18)} ${pad('TASKS', 16)} ${pad('HEALTH', 6)} ${pad('PACE', 9)} ${pad('AGE', 4)} MSGS`;
   const lines = [header, '-'.repeat(header.length)];
+  /** @type {string[]} */
+  const notes = [];
   for (const e of entries) {
     const pending = e.missing ? 0 : peekInbox(sessionDirFor(e)).length;
+    const health = healthFor(e);
+    if (health.state === 'red' || health.state === 'stale') {
+      notes.push(`${e.projectName}/${e.slug}: ${health.line}`);
+    }
     lines.push(
       `${pad(e.projectName, 18)} ${pad(e.slug, 26)} ${pad(e.engine ?? '—', 7)} ${pad(
         e.missing ? 'missing' : phaseBar(e.phase),
         18,
-      )} ${pad(tasksCell(e), 16)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.lastSeen ?? e.updatedAt), 4)} ${
+      )} ${pad(tasksCell(e), 16)} ${pad(healthCell(health.state), 6)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.lastSeen ?? e.updatedAt), 4)} ${
         pending > 0 ? `✉ ${pending}` : ''
       }`,
     );
   }
+  // The column says which row; the notes say why, without a second command.
+  if (notes.length) lines.push('', ...notes.map((n) => `  ! ${n}`));
   return `${lines.join('\n')}\n`;
 }
 

package/src/health.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Session health — a verdict, not a data dump.
+ *
+ * `forge status` printed every field a session had and said nothing about
+ * whether the session was in trouble, so a session could sit at
+ * `implement 27/32` with a red e2e run for 14 hours and look exactly like one
+ * that was mid-stride. Health answers the one question the operator actually
+ * asks: is this session fine, stopped, or broken?
+ *
+ * Cheap on purpose — file reads only, no subprocesses — because it runs on
+ * every `forge status`, every reminder hook, and once per row in
+ * `forge fleet list`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { e2ePath, e2eStepsHash, loadE2eResults } from './integrity.mjs';
+import { readJson } from './lib.mjs';
+
+/** Hours of no session write after which an unfinished session reads as stopped. */
+export const DEFAULT_IDLE_HOURS = 4;
+
+const SEVERITY = { done: 0, healthy: 1, stale: 2, red: 3 };
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function humanDuration(ms) {
+  const min = Math.floor(ms / 60000);
+  if (min < 60) return `${Math.max(min, 1)}m`;
+  const hours = Math.floor(min / 60);
+  if (hours < 48) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+/**
+ * The failing step of a red run, for a reason line that names the problem
+ * instead of pointing at a file.
+ *
+ * @param {Record<string, any> | null} results
+ */
+function failedStepName(results) {
+  if (!results || !Array.isArray(results.steps)) return null;
+  const failed = results.steps.find((s) => s && s.ok === false);
+  return failed?.name ?? null;
+}
+
+/**
+ * @param {{ cwd?: string, sessionDir: string, session: Record<string, any>, now?: number, idleHours?: number }} opts
+ * @returns {{ state: 'healthy'|'stale'|'red'|'done', reasons: string[], line: string }}
+ */
+export function sessionHealth(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const { sessionDir, session } = opts;
+  const now = opts.now ?? Date.now();
+  const idleHours = Number.isFinite(opts.idleHours) ? Number(opts.idleHours) : DEFAULT_IDLE_HOURS;
+
+  /** @type {string[]} */
+  const reasons = [];
+  let state = 'healthy';
+  const escalate = (next) => {
+    if (SEVERITY[next] > SEVERITY[state]) state = next;
+  };
+
+  if (session.phase === 'done' || session.phase === 'skipped') {
+    return {
+      state: 'done',
+      reasons: [],
+      line: `DONE — ${session.slug ?? session.id} (${session.phase})`,
+    };
+  }
+
+  // --- executed product loop: the strongest signal we have on disk ---
+  try {
+    const results = loadE2eResults(sessionDir);
+    if (results) {
+      let currentHash = null;
+      try {
+        const doc = readJson(e2ePath({ cwd, session, sessionDir }));
+        currentHash = e2eStepsHash(doc.steps);
+      } catch {
+        currentHash = null;
+      }
+      // A failed run outranks a stale one: staleness asks "does this proof
+      // still describe the current steps", a failure says the loop is broken
+      // either way.
+      if (results.ok === false) {
+        const step = failedStepName(results);
+        const since = results.ranAt ? ` since ${results.ranAt}` : '';
+        reasons.push(`e2e failing${since}${step ? ` at step "${step}"` : ''}`);
+        escalate('red');
+      } else if (currentHash && results.stepsHash !== currentHash) {
+        reasons.push('e2e results are stale — e2e.json changed since the last run');
+        escalate('stale');
+      }
+    }
+  } catch {
+    /* health must never throw — a broken artifact is the caller's problem */
+  }
+
+  // --- an explicit BLOCKED beats any inference we could make ---
+  try {
+    const verify = path.join(sessionDir, 'verify-evidence.md');
+    if (fs.existsSync(verify) && /\bBLOCKED\b/.test(fs.readFileSync(verify, 'utf8'))) {
+      reasons.push('verify-evidence records BLOCKED — product loop not proven');
+      escalate('red');
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // --- idle: nobody is driving this session ---
+  const updatedAt = new Date(session.updatedAt ?? session.createdAt ?? NaN).getTime();
+  if (!Number.isNaN(updatedAt)) {
+    const idleMs = now - updatedAt;
+    if (idleMs > idleHours * 3600 * 1000) {
+      const where = `${session.phase ?? 'unknown'}${
+        Number(session.tasksTotal) > 0 ? ` ${session.tasksComplete ?? 0}/${session.tasksTotal}` : ''
+      }`;
+      reasons.push(`idle ${humanDuration(idleMs)} at ${where}`);
+      escalate('stale');
+    }
+  }
+
+  const label = state.toUpperCase();
+  const line = reasons.length ? `${label} — ${reasons.join('; ')}` : `${label} — ${session.phase}`;
+  return { state, reasons, line };
+}
+
+/** Short cell for table renderers (`forge fleet list`). */
+export function healthCell(state) {
+  switch (state) {
+    case 'red':
+      return 'RED';
+    case 'stale':
+      return 'STALE';
+    case 'done':
+      return 'done';
+    default:
+      return 'ok';
+  }
+}