@izkac/forgekit 0.1.0

package/src/install.test.mjs

@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  parseArgs,
+  installSkillsToAgents,
+  listInstallStatus,
+  uninstallSkillsFromAgents,
+  updateOutdatedSkills,
+  readInstallStamp,
+  FORGEKIT_STAMP,
+  SKILL_IDS,
+  AGENT_IDS,
+} from './install.mjs';
+
+test('parseArgs supports multi skills and agents', () => {
+  const opts = parseArgs([
+    '--skills',
+    'forge,thorough-code-review',
+    '--agents',
+    'cursor,claude',
+    '--force',
+  ]);
+  assert.deepEqual(opts.skills, ['forge', 'thorough-code-review']);
+  assert.deepEqual(opts.agents, ['cursor', 'claude']);
+  assert.equal(opts.force, true);
+});
+
+test('parseArgs accepts --skill singular and shorthand agents', () => {
+  const opts = parseArgs(['--skill', 'forge', '--cursor', '--codex']);
+  assert.deepEqual(opts.skills, ['forge']);
+  assert.deepEqual(opts.agents, ['cursor', 'codex']);
+});
+
+test('parseArgs --all-skills / --all-agents / --update / --uninstall', () => {
+  const opts = parseArgs(['--all-skills', '--all-agents', '--update']);
+  assert.equal(opts.allSkills, true);
+  assert.equal(opts.allAgents, true);
+  assert.equal(opts.update, true);
+  assert.equal(parseArgs(['--uninstall']).uninstall, true);
+});
+
+test('installSkillsToAgents installs and stamps .forgekit.json', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-install-'));
+  try {
+    const results = installSkillsToAgents(['forge'], ['cursor', 'claude'], {
+      home,
+      force: true,
+    });
+    assert.equal(results.length, 2);
+    assert.ok(results.every((r) => r.status === 'installed'));
+    const dest = path.join(home, '.cursor', 'skills', 'forge');
+    assert.ok(fs.existsSync(path.join(dest, 'SKILL.md')));
+    assert.ok(fs.existsSync(path.join(dest, FORGEKIT_STAMP)));
+    const stamp = readInstallStamp(dest);
+    assert.equal(stamp.skill, 'forge');
+    assert.ok(stamp.contentHash);
+    assert.ok(stamp.version);
+
+    const again = installSkillsToAgents(['forge'], ['cursor'], { home });
+    assert.equal(again[0].status, 'exists');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('listInstallStatus covers every skill×agent', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-list-'));
+  try {
+    const rows = listInstallStatus({ home });
+    assert.equal(rows.length, SKILL_IDS.length * AGENT_IDS.length);
+    assert.ok(rows.every((r) => r.status === 'missing'));
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('uninstallSkillsFromAgents removes installed dirs', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-uninst-'));
+  try {
+    installSkillsToAgents(['forge'], ['cursor'], { home, force: true });
+    const results = uninstallSkillsFromAgents(['forge'], ['cursor'], { home });
+    assert.equal(results[0].status, 'removed');
+    assert.ok(!fs.existsSync(path.join(home, '.cursor', 'skills', 'forge')));
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('updateOutdatedSkills refreshes unversioned installs', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-upd-'));
+  try {
+    installSkillsToAgents(['forge'], ['cursor'], { home, force: true });
+    const dest = path.join(home, '.cursor', 'skills', 'forge');
+    fs.unlinkSync(path.join(dest, FORGEKIT_STAMP));
+    const { results } = updateOutdatedSkills({ home });
+    assert.ok(results.some((r) => r.skill === 'forge' && r.status === 'installed'));
+    assert.ok(fs.existsSync(path.join(dest, FORGEKIT_STAMP)));
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/integrity-check.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Forge integrity check — mechanical gate behind `forge phase done|finish`.
+ *
+ * Usage:
+ *   forge integrity-check [--session <id>]
+ *
+ * Fails (exit 1) when:
+ *   - deferrals are unresolved
+ *   - spine.json is required (jobs/workers in scope) but missing or invalid
+ *   - a spine with rows exists but verify-evidence.md lacks a product-loop
+ *     section, or contains an explicit BLOCKED marker
+ */
+
+import { loadSession, readActive } from './lib.mjs';
+import { runIntegrityChecks } from './integrity.mjs';
+
+const args = process.argv.slice(2);
+if (args[0] === '--help') {
+  process.stdout.write('Usage: forge integrity-check [--session <id>]\n');
+  process.exit(0);
+}
+
+let sessionId = null;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  }
+}
+
+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 result = runIntegrityChecks({ sessionDir: dir, session });
+
+process.stdout.write(
+  JSON.stringify(
+    {
+      sessionId,
+      ok: result.ok,
+      problems: result.problems,
+      spineFile: result.spineFile,
+      spineExists: result.spineExists,
+    },
+    null,
+    2,
+  ),
+);
+process.stdout.write('\n');
+process.exit(result.ok ? 0 : 1);

package/src/integrity.mjs

@@ -0,0 +1,317 @@
+/**
+ * Forge runtime-integrity mechanics: spine matrix, deferral registry,
+ * and the integrity checks that gate `forge phase done|finish`.
+ *
+ * Spine matrix — `spine.json` in the change dir (or session dir when the
+ * session has no tracked change). One row per capability/REQ cluster:
+ * library → runtime owner → writes → reads → UI consumer → evidence.
+ * Library-only rows (missing runtime owner / writes / evidence) fail
+ * validation, so "wire later" cannot be checkboxed past `forge phase done`.
+ *
+ * Deferral registry — `deferrals.json` in the session dir. Reviewers may only
+ * accept "wiring deferred" when a registered deferral names the open task;
+ * unresolved deferrals block done/finish.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, writeJson } from './lib.mjs';
+import { DEFAULT_SPECS_DIR, resolveProjectPlanEngine } from './plan-engine.mjs';
+
+/** Signals that a change involves jobs/workers and therefore needs a spine. */
+export const JOBS_SIGNAL_RE =
+  /\b(worker|workers|job|jobs|queue|queues|pipeline|pipelines|etl|orchestration|handler|handlers|cron|scheduler|daemon|ingest|dispatch)\b/i;
+
+/** Row fields that must be filled (reads/uiConsumer accept "N/A"). */
+export const SPINE_ROW_REQUIRED = Object.freeze([
+  'capability',
+  'library',
+  'runtimeOwner',
+  'writes',
+  'reads',
+  'uiConsumer',
+  'evidence',
+]);
+
+const SPINE_FILE = 'spine.json';
+const DEFERRALS_FILE = 'deferrals.json';
+
+/**
+ * @param {unknown} value
+ */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * Resolve the change directory for a session (openspec or specs engine).
+ * Returns null when the session has no tracked change.
+ *
+ * @param {{ cwd?: string, session?: Record<string, unknown> | null }} opts
+ */
+export function resolveChangeDir(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const session = opts.session ?? null;
+  const change = session && isNonEmptyString(session.openspecChange) ? session.openspecChange : null;
+  if (!change) return null;
+
+  const openspecDir = path.join(cwd, 'openspec', 'changes', change);
+  if (session.planType === 'openspec') return openspecDir;
+
+  let specsRoot = DEFAULT_SPECS_DIR;
+  try {
+    specsRoot = resolveProjectPlanEngine(cwd, { useUserDefault: false }).dir;
+  } catch {
+    // keep default
+  }
+  const specsDir = path.join(cwd, specsRoot, 'changes', change);
+  if (session.planType === 'specs') return specsDir;
+
+  // planType unknown — prefer whichever exists
+  if (fs.existsSync(openspecDir)) return openspecDir;
+  if (fs.existsSync(specsDir)) return specsDir;
+  return openspecDir;
+}
+
+/**
+ * Path to spine.json: change dir when available, else session dir.
+ *
+ * @param {{ cwd?: string, session?: Record<string, unknown> | null, sessionDir?: string }} opts
+ */
+export function spinePath(opts = {}) {
+  const changeDir = resolveChangeDir(opts);
+  if (changeDir) return path.join(changeDir, SPINE_FILE);
+  if (opts.sessionDir) return path.join(opts.sessionDir, SPINE_FILE);
+  throw new Error('Cannot resolve spine.json location: no change and no session dir');
+}
+
+/**
+ * @param {{ change?: string | null }} [opts]
+ */
+export function spineTemplate(opts = {}) {
+  return {
+    change: opts.change ?? null,
+    notApplicable: null,
+    rows: [
+      {
+        capability: '<REQ id or capability cluster, e.g. REQ-GOV-01 matching>',
+        library: '<module path, e.g. services/etl-core/matcher.py>',
+        runtimeOwner: '<production caller, e.g. worker job analyze_study>',
+        writes: '<artifact/collection, e.g. study_proposals>',
+        reads: '<consumed inputs, or N/A>',
+        uiConsumer: '<UI/API surface reading the writes, or N/A>',
+        evidence: '<tier-2/E2E evidence path proving the wired path>',
+      },
+    ],
+  };
+}
+
+/**
+ * Scaffold spine.json (refuses to overwrite unless force).
+ *
+ * @param {{ file: string, change?: string | null, force?: boolean }} opts
+ */
+export function initSpine(opts) {
+  if (fs.existsSync(opts.file) && !opts.force) {
+    throw new Error(`spine.json already exists: ${opts.file} (use --force to overwrite)`);
+  }
+  writeJson(opts.file, spineTemplate({ change: opts.change }));
+  return opts.file;
+}
+
+/**
+ * Validate a spine document.
+ *
+ * Valid when either:
+ *  - `notApplicable` is a non-empty string (honest opt-out, e.g. docs-only), or
+ *  - `rows` is a non-empty array where every required cell is filled and no
+ *    cell still contains scaffold placeholders (`<...>`).
+ *
+ * @param {unknown} doc
+ * @returns {{ ok: boolean, problems: string[] }}
+ */
+export function validateSpine(doc) {
+  /** @type {string[]} */
+  const problems = [];
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { ok: false, problems: ['spine.json is not an object'] };
+  }
+  const spine = /** @type {Record<string, unknown>} */ (doc);
+
+  if (isNonEmptyString(spine.notApplicable)) {
+    return { ok: true, problems: [] };
+  }
+
+  const rows = spine.rows;
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return {
+      ok: false,
+      problems: ['spine.rows is empty — add one row per capability, or set notApplicable with a reason'],
+    };
+  }
+
+  rows.forEach((row, i) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+      problems.push(`row ${i + 1}: not an object`);
+      return;
+    }
+    const r = /** @type {Record<string, unknown>} */ (row);
+    for (const field of SPINE_ROW_REQUIRED) {
+      const value = r[field];
+      if (!isNonEmptyString(value)) {
+        problems.push(`row ${i + 1} (${r.capability ?? '?'}): missing ${field}`);
+      } else if (/^<.*>$/.test(value.trim())) {
+        problems.push(`row ${i + 1} (${r.capability ?? '?'}): ${field} still has scaffold placeholder`);
+      }
+    }
+  });
+
+  return { ok: problems.length === 0, problems };
+}
+
+/**
+ * @param {string} sessionDir
+ */
+export function deferralsPath(sessionDir) {
+  return path.join(sessionDir, DEFERRALS_FILE);
+}
+
+/**
+ * @param {string} sessionDir
+ * @returns {{ deferrals: Array<{ task: string, reason: string, createdAt: string, resolvedAt: string | null }> }}
+ */
+export function loadDeferrals(sessionDir) {
+  const file = deferralsPath(sessionDir);
+  if (!fs.existsSync(file)) return { deferrals: [] };
+  const doc = readJson(file);
+  return { deferrals: Array.isArray(doc?.deferrals) ? doc.deferrals : [] };
+}
+
+/**
+ * @param {string} sessionDir
+ * @param {{ task: string, reason: string }} entry
+ */
+export function addDeferral(sessionDir, entry) {
+  if (!isNonEmptyString(entry.task)) throw new Error('Deferral requires --task <id>');
+  if (!isNonEmptyString(entry.reason)) throw new Error('Deferral requires --reason "<why>"');
+  const doc = loadDeferrals(sessionDir);
+  if (doc.deferrals.some((d) => d.task === entry.task && !d.resolvedAt)) {
+    throw new Error(`Deferral for task ${entry.task} already open`);
+  }
+  doc.deferrals.push({
+    task: entry.task,
+    reason: entry.reason,
+    createdAt: new Date().toISOString(),
+    resolvedAt: null,
+  });
+  writeJson(deferralsPath(sessionDir), doc);
+  return doc;
+}
+
+/**
+ * @param {string} sessionDir
+ * @param {string} task
+ */
+export function resolveDeferral(sessionDir, task) {
+  const doc = loadDeferrals(sessionDir);
+  const open = doc.deferrals.find((d) => d.task === task && !d.resolvedAt);
+  if (!open) throw new Error(`No open deferral for task ${task}`);
+  open.resolvedAt = new Date().toISOString();
+  writeJson(deferralsPath(sessionDir), doc);
+  return doc;
+}
+
+/**
+ * @param {string} sessionDir
+ */
+export function openDeferrals(sessionDir) {
+  return loadDeferrals(sessionDir).deferrals.filter((d) => !d.resolvedAt);
+}
+
+/**
+ * @param {Record<string, unknown> | null | undefined} session
+ */
+export function sessionJobsSignalText(session) {
+  return [session?.paceSignal, session?.slug, session?.openspecChange]
+    .filter((v) => isNonEmptyString(v))
+    .join(' ');
+}
+
+/**
+ * Run the mechanical integrity checks for a session.
+ *
+ * Checks:
+ *  1. No unresolved deferrals.
+ *  2. spine.json — **always required** (filled rows, or `notApplicable` with a
+ *     reason). Keyword sniffing is not enough to decide; missing spine is how
+ *     library-only platforms checkbox past gaps.
+ *  3. verify-evidence.md — when a spine has real rows (not notApplicable): must
+ *     exist and contain a product-loop section; an explicit BLOCKED marker means
+ *     the change cannot be done. Sync-only work should prefer `notApplicable`
+ *     over inventing a fake loop.
+ *
+ * @param {{ cwd?: string, sessionDir: string, session: Record<string, unknown> }} opts
+ * @returns {{ ok: boolean, problems: string[], spineFile: string, spineExists: boolean }}
+ */
+export function runIntegrityChecks(opts) {
+  /** @type {string[]} */
+  const problems = [];
+  const { sessionDir, session } = opts;
+  const cwd = opts.cwd ?? process.cwd();
+
+  const open = openDeferrals(sessionDir);
+  if (open.length > 0) {
+    problems.push(
+      `unresolved deferrals: ${open.map((d) => `${d.task} (${d.reason})`).join('; ')} — resolve via forge defer resolve --task <id>`,
+    );
+  }
+
+  const spineFile = spinePath({ cwd, session, sessionDir });
+  const spineExists = fs.existsSync(spineFile);
+
+  /** @type {ReturnType<typeof validateSpine> | null} */
+  let spineResult = null;
+  let spineHasRows = false;
+  if (!spineExists) {
+    problems.push(
+      `spine.json required at ${spineFile} — run forge spine init, then fill rows (or set notApplicable with a reason). Spine is mandatory for every change so capability→runtime wiring cannot be skipped by accident.`,
+    );
+  } else {
+    try {
+      const doc = readJson(spineFile);
+      spineResult = validateSpine(doc);
+      spineHasRows =
+        Array.isArray(doc?.rows) &&
+        doc.rows.length > 0 &&
+        !isNonEmptyString(doc?.notApplicable);
+    } catch (err) {
+      spineResult = {
+        ok: false,
+        problems: [`spine.json unreadable: ${err instanceof Error ? err.message : err}`],
+      };
+    }
+    if (!spineResult.ok) {
+      problems.push(...spineResult.problems.map((p) => `spine: ${p}`));
+    }
+  }
+
+  if (spineExists && spineHasRows) {
+    const evidenceFile = path.join(sessionDir, 'verify-evidence.md');
+    if (!fs.existsSync(evidenceFile)) {
+      problems.push(
+        'verify-evidence.md missing — spine rows require product-loop evidence (or use notApplicable for sync-only work)',
+      );
+    } else {
+      const body = fs.readFileSync(evidenceFile, 'utf8');
+      if (/\bBLOCKED\b/.test(body)) {
+        problems.push('verify-evidence.md contains BLOCKED — change cannot be marked done while E2E is blocked');
+      } else if (!/product[- ]loop/i.test(body)) {
+        problems.push(
+          'verify-evidence.md has no "Product loop" section — record the closed producer→consumer loop (or BLOCKED). Sync-only changes should use spine notApplicable instead.',
+        );
+      }
+    }
+  }
+
+  return { ok: problems.length === 0, problems, spineFile, spineExists };
+}