@izkac/forgekit 0.1.7 → 0.3.0

package/bin/forge.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * Forge CLI — session orchestration, prefs, models, project init.
  *
@@ -31,9 +31,12 @@ const COMMANDS = {
   triage: { script: 'triage-prompt.mjs' },
   change: { script: 'change.mjs' },
   spine: { script: 'spine.mjs' },
+  e2e: { script: 'e2e.mjs' },
   defer: { script: 'defer.mjs' },
   'integrity-check': { script: 'integrity-check.mjs', aliases: ['integrity'] },
   score: { script: 'score-cli.mjs', aliases: ['scorecard'] },
+  fleet: { script: 'fleet.mjs' },
+  brief: { script: 'brief-cli.mjs' },
 };
 
 function printHelp() {
@@ -59,9 +62,12 @@ Commands:
   triage                  Classify whether a prompt needs Forge triage
   change new|archive      Specs-engine change scaffold / archive
   spine init|check        Capability→runtime spine matrix (spine.json)
+  e2e init|run|check      Executable product-loop acceptance (e2e.json)
   defer add|resolve|list  Deferral registry (deferred wiring = tracked debt)
   integrity-check         Mechanical integrity gate (runs at phase done)
   score [--write]         L2 session scorecard (auto-written at phase done)
+  fleet list|watch|view|send  Cross-project session control terminal
+  brief stamp|check|open  Operator brief (plain-language HTML, gates implement)
 
 Prefer \`forgekit install\` to pick multiple skills + agents at once.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {

package/scripts/run-tests.mjs

@@ -7,6 +7,7 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -39,5 +40,11 @@ if (files.length === 0) {
 const result = spawnSync(process.execPath, ['--test', ...files], {
   cwd: cliRoot,
   stdio: 'inherit',
+  env: {
+    ...process.env,
+    // Keep saveSession's fleet-registry mirroring away from ~/.forgekit
+    // when tests exercise session saves with scratch projects.
+    FORGEKIT_FLEET_DIR: fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-test-fleet-')),
+  },
 });
 process.exit(result.status ?? 1);

package/src/brief-cli.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Operator-brief CLI (core in brief.mjs).
+ *
+ * Usage:
+ *   forge brief stamp [--session <id>] [--no-open]   stamp freshness hash + open in browser
+ *   forge brief check [--session <id>]               exit 1 when missing/stale/unstamped
+ *   forge brief open  [--session <id>]               open in default browser
+ */
+
+import fs from 'node:fs';
+import { loadSession, readActive } from './lib.mjs';
+import { resolveChangeDir } from './integrity.mjs';
+import { BRIEF_FILE, briefPath, checkBrief, openInBrowser, stampBrief } from './brief.mjs';
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || !['stamp', 'check', 'open'].includes(cmd)) {
+  process.stderr.write(
+    'Usage: forge brief stamp [--session <id>] [--no-open] | check [--session <id>] | open [--session <id>]\n',
+  );
+  process.exit(1);
+}
+
+let sessionId = null;
+const si = rest.indexOf('--session');
+if (si >= 0 && rest[si + 1]) sessionId = rest[si + 1];
+if (!sessionId) sessionId = readActive()?.sessionId ?? null;
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { session } = loadSession(sessionId);
+const changeDir = resolveChangeDir({ session });
+
+if (cmd === 'check') {
+  const result = checkBrief({ session });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exit(result.ok ? 0 : 1);
+}
+
+if (!changeDir) {
+  process.stderr.write('Session has no tracked change — nothing to brief.\n');
+  process.exit(1);
+}
+
+if (cmd === 'stamp') {
+  const hash = stampBrief(changeDir);
+  process.stdout.write(`Stamped ${briefPath(changeDir)} (specs hash ${hash})\n`);
+  if (!rest.includes('--no-open')) {
+    openInBrowser(briefPath(changeDir));
+    process.stdout.write('Opened in default browser.\n');
+  }
+} else {
+  const file = briefPath(changeDir);
+  if (!fs.existsSync(file)) {
+    process.stderr.write(`No ${BRIEF_FILE} in ${changeDir}.\n`);
+    process.exit(1);
+  }
+  openInBrowser(file);
+  process.stdout.write(`Opened ${file}\n`);
+}

package/src/brief.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Operator brief core — a plain-language, self-contained HTML explanation of
+ * what will be built, written by the agent at the end of the plan phase into
+ * `<changeDir>/brief.html`. CLI in brief-cli.mjs (`forge brief`).
+ *
+ * Freshness: `stampBrief` records a hash of proposal.md/design.md/tasks.md
+ * inside brief.html. When the specs change afterwards the brief goes stale and
+ * the hard gate in `forge phase implement` refuses until it is rewritten and
+ * re-stamped — same executed-evidence philosophy as the e2e gate.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveChangeDir } from './integrity.mjs';
+
+export const BRIEF_FILE = 'brief.html';
+const HASH_MARKER = /<!--\s*forge-brief-specs-hash:([a-f0-9]+)\s*-->/;
+const SPEC_FILES = ['proposal.md', 'design.md', 'tasks.md'];
+
+/** Hash of the spec sources a brief must reflect (missing files hash as absent). */
+export function specsHash(changeDir) {
+  const h = crypto.createHash('sha256');
+  for (const name of SPEC_FILES) {
+    const file = path.join(changeDir, name);
+    h.update(name);
+    h.update(fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '<absent>');
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+export function briefPath(changeDir) {
+  return path.join(changeDir, BRIEF_FILE);
+}
+
+export function readBriefHash(file) {
+  if (!fs.existsSync(file)) return null;
+  const match = fs.readFileSync(file, 'utf8').match(HASH_MARKER);
+  return match ? match[1] : null;
+}
+
+/** Write/replace the freshness marker in brief.html. Returns the stamped hash. */
+export function stampBrief(changeDir) {
+  const file = briefPath(changeDir);
+  if (!fs.existsSync(file)) {
+    throw new Error(`No ${BRIEF_FILE} in ${changeDir} — write the operator brief first.`);
+  }
+  const hash = specsHash(changeDir);
+  let html = fs.readFileSync(file, 'utf8');
+  const marker = `<!-- forge-brief-specs-hash:${hash} -->`;
+  html = HASH_MARKER.test(html) ? html.replace(HASH_MARKER, marker) : `${marker}\n${html}`;
+  fs.writeFileSync(file, html, 'utf8');
+  return hash;
+}
+
+/**
+ * Brief status for a session.
+ *
+ * @param {{ cwd?: string, session: Record<string, any> }} opts
+ * @returns {{ ok: boolean, reason: 'not-applicable'|'fresh'|'missing'|'unstamped'|'stale', path: string | null }}
+ */
+export function checkBrief(opts) {
+  const { session } = opts;
+  const changeDir = resolveChangeDir(opts);
+  // Brief only applies to tracked-change plans; direct/throwaway have no specs
+  // for an operator to review.
+  if (!changeDir || session.planType === 'direct' || session.planType === 'throwaway') {
+    return { ok: true, reason: 'not-applicable', path: null };
+  }
+  const file = briefPath(changeDir);
+  if (!fs.existsSync(file)) return { ok: false, reason: 'missing', path: file };
+  const stamped = readBriefHash(file);
+  if (!stamped) return { ok: false, reason: 'unstamped', path: file };
+  if (stamped !== specsHash(changeDir)) return { ok: false, reason: 'stale', path: file };
+  return { ok: true, reason: 'fresh', path: file };
+}
+
+/** Human-readable problem line for a failed check, null when ok. */
+export function briefProblem(result) {
+  switch (result.reason) {
+    case 'missing':
+      return `operator brief missing — write ${result.path} (plain-language HTML, see forge references/operator-brief.md), then run forge brief stamp`;
+    case 'unstamped':
+      return 'operator brief not stamped — run forge brief stamp (records specs hash + opens it for the operator)';
+    case 'stale':
+      return `operator brief is stale — specs changed after it was written; update ${result.path} and re-run forge brief stamp`;
+    default:
+      return null;
+  }
+}
+
+/** Open a file with the OS default handler (fire-and-forget). */
+export function openInBrowser(file) {
+  const target = path.resolve(file);
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', target]]
+      : process.platform === 'darwin'
+        ? ['open', [target]]
+        : ['xdg-open', [target]];
+  spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+}

package/src/brief.test.mjs

@@ -0,0 +1,186 @@
+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';
+import {
+  briefPath,
+  checkBrief,
+  readBriefHash,
+  specsHash,
+  stampBrief,
+} from './brief.mjs';
+
+const SET_PHASE = path.join(path.dirname(fileURLToPath(import.meta.url)), 'set-phase.mjs');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+/** Project with a specs-engine change dir containing proposal + tasks. */
+function makeChange(root, change) {
+  const changeDir = path.join(root, 'specs', 'changes', change);
+  fs.mkdirSync(changeDir, { recursive: true });
+  fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# Why\nBecause.\n', 'utf8');
+  fs.writeFileSync(path.join(changeDir, 'tasks.md'), '# Tasks\n- [ ] 1.1 do it\n', 'utf8');
+  return changeDir;
+}
+
+function writeBrief(changeDir) {
+  fs.writeFileSync(
+    briefPath(changeDir),
+    '<html><head><title>Brief</title></head><body><h1>TL;DR</h1></body></html>\n',
+    'utf8',
+  );
+}
+
+function makeSession(overrides = {}) {
+  return {
+    id: 's1',
+    slug: 'fixture',
+    planType: 'specs',
+    openspecChange: 'my-change',
+    ...overrides,
+  };
+}
+
+test('specsHash changes when a spec file changes', () => {
+  const changeDir = makeChange(tmp('brief-'), 'my-change');
+  const before = specsHash(changeDir);
+  fs.appendFileSync(path.join(changeDir, 'proposal.md'), 'More.\n');
+  assert.notEqual(specsHash(changeDir), before);
+});
+
+test('stampBrief injects the marker once and restamp replaces it', () => {
+  const changeDir = makeChange(tmp('brief-'), 'my-change');
+  writeBrief(changeDir);
+  const hash = stampBrief(changeDir);
+  assert.equal(readBriefHash(briefPath(changeDir)), hash);
+
+  fs.appendFileSync(path.join(changeDir, 'tasks.md'), '- [ ] 1.2 more\n');
+  const hash2 = stampBrief(changeDir);
+  assert.notEqual(hash2, hash);
+  const html = fs.readFileSync(briefPath(changeDir), 'utf8');
+  assert.equal(html.match(/forge-brief-specs-hash/g).length, 1);
+});
+
+test('stampBrief throws when brief.html is missing', () => {
+  const changeDir = makeChange(tmp('brief-'), 'my-change');
+  assert.throws(() => stampBrief(changeDir), /write the operator brief first/);
+});
+
+test('checkBrief lifecycle: missing → unstamped → fresh → stale', () => {
+  const root = tmp('brief-');
+  const changeDir = makeChange(root, 'my-change');
+  const session = makeSession();
+
+  assert.equal(checkBrief({ cwd: root, session }).reason, 'missing');
+
+  writeBrief(changeDir);
+  assert.equal(checkBrief({ cwd: root, session }).reason, 'unstamped');
+
+  stampBrief(changeDir);
+  const fresh = checkBrief({ cwd: root, session });
+  assert.equal(fresh.reason, 'fresh');
+  assert.equal(fresh.ok, true);
+
+  fs.appendFileSync(path.join(changeDir, 'proposal.md'), 'Edited after stamp.\n');
+  const stale = checkBrief({ cwd: root, session });
+  assert.equal(stale.reason, 'stale');
+  assert.equal(stale.ok, false);
+});
+
+test('checkBrief not-applicable without a change or for direct/throwaway plans', () => {
+  const root = tmp('brief-');
+  assert.equal(
+    checkBrief({ cwd: root, session: makeSession({ openspecChange: null }) }).reason,
+    'not-applicable',
+  );
+  makeChange(root, 'my-change');
+  assert.equal(
+    checkBrief({ cwd: root, session: makeSession({ planType: 'direct' }) }).reason,
+    'not-applicable',
+  );
+});
+
+/** Full .forge fixture so set-phase.mjs can run as a child in `root`. */
+function makePhaseFixture(root, overrides = {}) {
+  const sessionDir = path.join(root, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const now = new Date().toISOString();
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({
+      id: 's1',
+      slug: 'fixture',
+      createdAt: now,
+      updatedAt: now,
+      phase: 'plan',
+      planType: 'specs',
+      openspecChange: 'my-change',
+      forgeSkipped: false,
+      tasksTotal: 0,
+      tasksComplete: 0,
+      ...overrides,
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  return sessionDir;
+}
+
+function runSetPhase(cwd, args) {
+  try {
+    const stdout = execFileSync(process.execPath, [SET_PHASE, ...args], {
+      cwd,
+      env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('brief-fleet-'), 's') },
+    });
+    return { status: 0, stdout: stdout.toString(), stderr: '' };
+  } catch (err) {
+    return { status: err.status, stdout: String(err.stdout), stderr: String(err.stderr) };
+  }
+}
+
+test('phase implement hard-refuses without a fresh brief, passes with one', () => {
+  const root = tmp('brief-gate-');
+  const changeDir = makeChange(root, 'my-change');
+  makePhaseFixture(root);
+
+  const refused = runSetPhase(root, ['implement', '--tasks-total', '3']);
+  assert.notEqual(refused.status, 0);
+  assert.match(refused.stderr, /operator brief missing/);
+
+  writeBrief(changeDir);
+  stampBrief(changeDir);
+  const ok = runSetPhase(root, ['implement', '--tasks-total', '3']);
+  assert.equal(ok.status, 0);
+
+  fs.appendFileSync(path.join(changeDir, 'tasks.md'), '- [ ] 1.9 late edit\n');
+  const stale = runSetPhase(root, ['implement']);
+  assert.notEqual(stale.status, 0);
+  assert.match(stale.stderr, /stale/);
+});
+
+test('phase implement --allow-incomplete records briefSkipped', () => {
+  const root = tmp('brief-gate-');
+  makeChange(root, 'my-change');
+  const sessionDir = makePhaseFixture(root);
+
+  const ok = runSetPhase(root, ['implement', '--allow-incomplete', 'operator waived brief']);
+  assert.equal(ok.status, 0);
+  const session = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+  assert.equal(session.briefSkipped, 'operator waived brief');
+});
+
+test('phase implement unaffected for sessions without a tracked change', () => {
+  const root = tmp('brief-gate-');
+  makePhaseFixture(root, { planType: null, openspecChange: null });
+  const ok = runSetPhase(root, ['implement', '--tasks-total', '2']);
+  assert.equal(ok.status, 0);
+});

package/src/cleanup-sessions.mjs

@@ -18,6 +18,7 @@ import {
   SESSIONS_DIR,
   sessionAgeDays,
 } from './lib.mjs';
+import { unregisterSession } from './lib/fleet.mjs';
 
 const args = new Set(process.argv.slice(2));
 const dryRun = args.has('--dry-run');
@@ -59,6 +60,7 @@ for (const entry of fs.readdirSync(SESSIONS_DIR, { withFileTypes: true })) {
     if (!dryRun) {
       fs.rmSync(dir, { recursive: true, force: true });
       if (isActive) clearActive();
+      unregisterSession(process.cwd(), sessionId);
     }
     removed.push({ sessionId, reason: tooOld ? 'retention' : 'finished' });
   } else {

package/src/e2e.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Forge E2E acceptance — the closed product loop as an executable step list.
+ *
+ * Usage:
+ *   forge e2e                         # show status (file, validity, results freshness)
+ *   forge e2e init [--force]          # scaffold e2e.json for the active change
+ *   forge e2e run                     # execute steps, write e2e-results.json (session dir)
+ *   forge e2e check                   # gate check: green + current results; exit 1 with problems
+ *   [--session <id>]
+ *
+ * e2e.json lives next to spine.json (change dir, falling back to the session
+ * dir). Results carry a hash of the steps, so editing e2e.json after a green
+ * run invalidates the results. `forge integrity-check` / `forge phase done`
+ * run the same gate when the spine has real rows.
+ */
+
+import fs from 'node:fs';
+import { loadSession, readActive, readJson } from './lib.mjs';
+import {
+  checkE2eGate,
+  e2ePath,
+  e2eResultsPath,
+  e2eStepsHash,
+  initE2e,
+  loadE2eResults,
+  runE2eSteps,
+  validateE2e,
+  writeE2eResults,
+} from './integrity.mjs';
+
+const args = process.argv.slice(2);
+const sub = args[0] && !args[0].startsWith('--') ? args[0] : 'status';
+
+if (args[0] === '--help' || sub === 'help') {
+  process.stdout.write(
+    'Usage: forge e2e [init [--force] | run | check | status] [--session <id>]\n',
+  );
+  process.exit(0);
+}
+
+let sessionId = null;
+let force = false;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--force') {
+    force = true;
+  }
+}
+
+if (!sessionId) {
+  const active = readActive();
+  sessionId = active?.sessionId;
+}
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { dir, session } = loadSession(sessionId);
+const file = e2ePath({ session, sessionDir: dir });
+
+if (sub === 'init') {
+  try {
+    initE2e({ file, change: session.openspecChange ?? null, force });
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(
+    `Scaffolded ${file}\nAuthor the product-loop steps (produce → consume → assert domain side effects).\nSteps that would pass against a stubbed handler are invalid.\nRun with: forge e2e run\n`,
+  );
+  process.exit(0);
+}
+
+if (sub === 'run') {
+  if (!fs.existsSync(file)) {
+    process.stderr.write(`e2e.json not found at ${file} — run forge e2e init\n`);
+    process.exit(1);
+  }
+  let doc;
+  try {
+    doc = readJson(file);
+  } catch (err) {
+    process.stderr.write(`e2e.json unreadable: ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+  }
+  const valid = validateE2e(doc);
+  if (!valid.ok) {
+    process.stderr.write(`e2e.json invalid:\n${valid.problems.map((p) => `  - ${p}`).join('\n')}\n`);
+    process.exit(1);
+  }
+  if (typeof doc.notApplicable === 'string' && doc.notApplicable.trim()) {
+    process.stdout.write(`e2e notApplicable: ${doc.notApplicable}\nNothing to run.\n`);
+    process.exit(0);
+  }
+  const results = runE2eSteps(doc, { cwd: process.cwd() });
+  const resultsFile = writeE2eResults(dir, results);
+  for (const step of results.steps) {
+    if (step.skipped) {
+      process.stdout.write(`  - ${step.name}: skipped (earlier step failed)\n`);
+    } else {
+      process.stdout.write(
+        `  ${step.ok ? '✓' : '✗'} ${step.name}: exit ${step.exitCode ?? 'n/a'}${
+          step.expectMatched === false ? ' (expect did not match)' : ''
+        }${step.error ? ` [${step.error}]` : ''} (${step.durationMs}ms)\n`,
+      );
+      if (!step.ok && step.outputTail) {
+        process.stdout.write(`${step.outputTail.replace(/^/gm, '    ')}\n`);
+      }
+    }
+  }
+  process.stdout.write(`${results.ok ? 'GREEN' : 'FAILED'} — results: ${resultsFile}\n`);
+  process.exit(results.ok ? 0 : 1);
+}
+
+if (sub === 'check') {
+  const gate = checkE2eGate({ e2eFile: file, sessionDir: dir });
+  process.stdout.write(
+    JSON.stringify(
+      { file, ok: gate.problems.length === 0, notApplicable: gate.notApplicable, problems: gate.problems },
+      null,
+      2,
+    ),
+  );
+  process.stdout.write('\n');
+  process.exit(gate.problems.length === 0 ? 0 : 1);
+}
+
+if (sub === 'status') {
+  if (!fs.existsSync(file)) {
+    process.stdout.write(JSON.stringify({ file, exists: false }, null, 2));
+    process.stdout.write('\n');
+    process.exit(0);
+  }
+  let doc = null;
+  let valid = { ok: false, problems: ['unreadable'] };
+  try {
+    doc = readJson(file);
+    valid = validateE2e(doc);
+  } catch (err) {
+    valid = { ok: false, problems: [`unreadable: ${err instanceof Error ? err.message : err}`] };
+  }
+  const results = loadE2eResults(dir);
+  process.stdout.write(
+    JSON.stringify(
+      {
+        file,
+        exists: true,
+        ok: valid.ok,
+        problems: valid.problems,
+        results: results
+          ? {
+              file: e2eResultsPath(dir),
+              ok: results.ok === true,
+              ranAt: results.ranAt ?? null,
+              stale: doc ? results.stepsHash !== e2eStepsHash(doc.steps) : null,
+            }
+          : null,
+      },
+      null,
+      2,
+    ),
+  );
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+process.stderr.write(`Unknown subcommand: ${sub}\n`);
+process.exit(1);