@izkac/forgekit 0.3.12 → 0.3.13

package/src/change.test.mjs

@@ -1,83 +1,145 @@
-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 {
-  assertChangeName,
-  archiveSpecsChange,
-  createSpecsChange,
-  parseArgs,
-  runChange,
-} from './change.mjs';
-import { writeProjectPlanConfig, scaffoldSpecs } from './plan-engine.mjs';
-
-function tmp() {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-change-'));
-}
-
-test('assertChangeName accepts kebab-case', () => {
-  assert.equal(assertChangeName('add-auth'), 'add-auth');
-  assert.throws(() => assertChangeName('Add Auth'), /kebab-case/);
-  assert.throws(() => assertChangeName('UPPER'), /kebab-case/);
-});
-
-test('parseArgs new and archive', () => {
-  assert.deepEqual(parseArgs(['new', 'foo', '--force']).action, 'new');
-  assert.equal(parseArgs(['new', 'foo']).name, 'foo');
-  assert.equal(parseArgs(['archive', 'foo', '--date', '2026-01-02']).date, '2026-01-02');
-});
-
-test('createSpecsChange writes proposal and tasks', () => {
-  const cwd = tmp();
-  try {
-    writeProjectPlanConfig(cwd, { engine: 'specs' });
-    scaffoldSpecs(cwd);
-    const result = createSpecsChange(cwd, 'add-refunds', { force: true });
-    assert.ok(fs.existsSync(path.join(result.changeDir, 'proposal.md')));
-    assert.ok(fs.existsSync(path.join(result.changeDir, 'tasks.md')));
-  } finally {
-    fs.rmSync(cwd, { recursive: true, force: true });
-  }
-});
-
-test('createSpecsChange rejects openspec engine', () => {
-  const cwd = tmp();
-  try {
-    writeProjectPlanConfig(cwd, { engine: 'openspec' });
-    assert.throws(() => createSpecsChange(cwd, 'x'), /not "specs"/);
-  } finally {
-    fs.rmSync(cwd, { recursive: true, force: true });
-  }
-});
-
-test('archiveSpecsChange moves to dated archive', () => {
-  const cwd = tmp();
-  try {
-    writeProjectPlanConfig(cwd, { engine: 'specs' });
-    scaffoldSpecs(cwd);
-    createSpecsChange(cwd, 'ship-it', { force: true });
-    const archived = archiveSpecsChange(cwd, 'ship-it', { date: '2026-07-18' });
-    assert.equal(archived.to, 'specs/changes/archive/2026-07-18-ship-it');
-    assert.ok(!fs.existsSync(path.join(cwd, 'specs', 'changes', 'ship-it')));
-    assert.ok(
-      fs.existsSync(
-        path.join(cwd, 'specs', 'changes', 'archive', '2026-07-18-ship-it', 'proposal.md'),
-      ),
-    );
-  } finally {
-    fs.rmSync(cwd, { recursive: true, force: true });
-  }
-});
-
-test('runChange new prints next steps', () => {
-  const cwd = tmp();
-  try {
-    writeProjectPlanConfig(cwd, { engine: 'specs' });
-    scaffoldSpecs(cwd);
-    const code = runChange(['new', 'demo-feat', '--cwd', cwd]);
-    assert.equal(code, 0);
-  } finally {
-    fs.rmSync(cwd, { recursive: true, force: true });
-  }
-});
+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 {
+  assertChangeName,
+  assertCapabilityName,
+  archiveSpecsChange,
+  createSpecsChange,
+  parseArgs,
+  runChange,
+} from './change.mjs';
+import { writeProjectPlanConfig, scaffoldSpecs } from './plan-engine.mjs';
+
+function tmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-change-'));
+}
+
+test('assertChangeName accepts kebab-case', () => {
+  assert.equal(assertChangeName('add-auth'), 'add-auth');
+  assert.throws(() => assertChangeName('Add Auth'), /kebab-case/);
+  assert.throws(() => assertChangeName('UPPER'), /kebab-case/);
+});
+
+test('assertCapabilityName accepts kebab-case', () => {
+  assert.equal(assertCapabilityName('auth'), 'auth');
+  assert.throws(() => assertCapabilityName('Auth'), /kebab-case/);
+});
+
+test('parseArgs new and archive with capabilities', () => {
+  assert.deepEqual(parseArgs(['new', 'foo', '--force']).action, 'new');
+  assert.equal(parseArgs(['new', 'foo']).name, 'foo');
+  assert.equal(parseArgs(['archive', 'foo', '--date', '2026-01-02']).date, '2026-01-02');
+  assert.deepEqual(
+    parseArgs(['new', 'foo', '--capability', 'auth', '--cap', 'payments']).capabilities,
+    ['auth', 'payments'],
+  );
+  assert.equal(parseArgs(['archive', 'foo', '--no-sync']).noSync, true);
+});
+
+test('createSpecsChange writes OpenSpec-parity artefacts including deltas', () => {
+  const cwd = tmp();
+  try {
+    writeProjectPlanConfig(cwd, { engine: 'specs' });
+    scaffoldSpecs(cwd);
+    const result = createSpecsChange(cwd, 'add-refunds', {
+      force: true,
+      capabilities: ['payments'],
+    });
+    assert.ok(fs.existsSync(path.join(result.changeDir, 'proposal.md')));
+    assert.ok(fs.existsSync(path.join(result.changeDir, 'design.md')));
+    assert.ok(fs.existsSync(path.join(result.changeDir, 'tasks.md')));
+    assert.ok(fs.existsSync(path.join(result.changeDir, 'specs', 'payments', 'spec.md')));
+    const proposal = fs.readFileSync(path.join(result.changeDir, 'proposal.md'), 'utf8');
+    assert.match(proposal, /## Capabilities/);
+    assert.match(proposal, /`payments`/);
+    const delta = fs.readFileSync(
+      path.join(result.changeDir, 'specs', 'payments', 'spec.md'),
+      'utf8',
+    );
+    assert.match(delta, /## ADDED Requirements/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('createSpecsChange rejects openspec engine', () => {
+  const cwd = tmp();
+  try {
+    writeProjectPlanConfig(cwd, { engine: 'openspec' });
+    assert.throws(() => createSpecsChange(cwd, 'x'), /not "specs"/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('createSpecsChange honors custom plan.dir', () => {
+  const cwd = tmp();
+  try {
+    writeProjectPlanConfig(cwd, { engine: 'specs', dir: 'openspec' });
+    scaffoldSpecs(cwd, { dir: 'openspec' });
+    const result = createSpecsChange(cwd, 'reuse-tree', {
+      force: true,
+      capabilities: ['auth'],
+    });
+    assert.equal(result.dir, 'openspec');
+    assert.ok(
+      fs.existsSync(path.join(cwd, 'openspec', 'changes', 'reuse-tree', 'specs', 'auth', 'spec.md')),
+    );
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('archiveSpecsChange merges deltas then moves to dated archive', () => {
+  const cwd = tmp();
+  try {
+    writeProjectPlanConfig(cwd, { engine: 'specs' });
+    scaffoldSpecs(cwd);
+    createSpecsChange(cwd, 'ship-it', { force: true, capabilities: ['auth'] });
+    const archived = archiveSpecsChange(cwd, 'ship-it', { date: '2026-07-18' });
+    assert.equal(archived.to, 'specs/changes/archive/2026-07-18-ship-it');
+    assert.ok(!fs.existsSync(path.join(cwd, 'specs', 'changes', 'ship-it')));
+    assert.ok(
+      fs.existsSync(
+        path.join(cwd, 'specs', 'changes', 'archive', '2026-07-18-ship-it', 'proposal.md'),
+      ),
+    );
+    assert.ok(fs.existsSync(path.join(cwd, 'specs', 'specs', 'auth', 'spec.md')));
+    assert.equal(archived.synced.length, 1);
+    assert.equal(archived.synced[0].capability, 'auth');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('archiveSpecsChange --no-sync skips main catalog merge', () => {
+  const cwd = tmp();
+  try {
+    writeProjectPlanConfig(cwd, { engine: 'specs' });
+    scaffoldSpecs(cwd);
+    createSpecsChange(cwd, 'no-merge', { force: true, capabilities: ['auth'] });
+    const archived = archiveSpecsChange(cwd, 'no-merge', {
+      date: '2026-07-18',
+      noSync: true,
+    });
+    assert.deepEqual(archived.synced, []);
+    assert.ok(!fs.existsSync(path.join(cwd, 'specs', 'specs', 'auth', 'spec.md')));
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runChange new prints next steps', () => {
+  const cwd = tmp();
+  try {
+    writeProjectPlanConfig(cwd, { engine: 'specs' });
+    scaffoldSpecs(cwd);
+    const code = runChange(['new', 'demo-feat', '--cwd', cwd, '--capability', 'demo']);
+    assert.equal(code, 0);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/src/cleanup-sessions.mjs

@@ -1,84 +1,84 @@
-#!/usr/bin/env node
-/**
- * Remove Forge sessions older than RETENTION_DAYS (default 14).
- * Skips the active session unless --include-active is passed.
- *
- * Usage:
- *   forge cleanup
- *   forge cleanup-sessions [--dry-run] [--include-active]
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import {
-  clearActive,
-  loadSession,
-  readActive,
-  RETENTION_DAYS,
-  SESSIONS_DIR,
-  sessionAgeDays,
-} from './lib.mjs';
-import { unregisterSession } from './lib/fleet.mjs';
-import { appendScorecardLedger } from './score.mjs';
-
-const args = new Set(process.argv.slice(2));
-const dryRun = args.has('--dry-run');
-const includeActive = args.has('--include-active');
-
-const active = readActive();
-const activeId = active?.sessionId ?? null;
-const removed = [];
-const kept = [];
-
-if (!fs.existsSync(SESSIONS_DIR)) {
-  process.stdout.write(JSON.stringify({ removed, kept, dryRun }, null, 2));
-  process.stdout.write('\n');
-  process.exit(0);
-}
-
-for (const entry of fs.readdirSync(SESSIONS_DIR, { withFileTypes: true })) {
-  if (!entry.isDirectory()) continue;
-  const sessionId = entry.name;
-  const dir = path.join(SESSIONS_DIR, sessionId);
-  const sessionFile = path.join(dir, 'session.json');
-  if (!fs.existsSync(sessionFile)) continue;
-
-  let session;
-  try {
-    ({ session } = loadSession(sessionId));
-  } catch {
-    continue;
-  }
-
-  const isActive = sessionId === activeId;
-  const tooOld = sessionAgeDays(session) > RETENTION_DAYS;
-  const isDone = session.phase === 'done' || session.phase === 'skipped';
-
-  const shouldRemove =
-    (tooOld || isDone) && (!isActive || includeActive);
-
-  if (shouldRemove) {
-    if (!dryRun) {
-      // Harvest the scorecard into the durable ledger before the session dir
-      // (and its scoring history) is erased. Covers sessions scored before
-      // the ledger existed; a no-op when the ledger already has the line.
-      try {
-        const cardFile = path.join(dir, 'scorecard.json');
-        if (fs.existsSync(cardFile)) {
-          appendScorecardLedger(dir, JSON.parse(fs.readFileSync(cardFile, 'utf8')), session);
-        }
-      } catch {
-        /* ledger is advisory — never block cleanup */
-      }
-      fs.rmSync(dir, { recursive: true, force: true });
-      if (isActive) clearActive();
-      unregisterSession(process.cwd(), sessionId);
-    }
-    removed.push({ sessionId, reason: tooOld ? 'retention' : 'finished' });
-  } else {
-    kept.push({ sessionId, phase: session.phase, ageDays: sessionAgeDays(session).toFixed(1) });
-  }
-}
-
-process.stdout.write(JSON.stringify({ removed, kept, dryRun, retentionDays: RETENTION_DAYS }, null, 2));
-process.stdout.write('\n');
+#!/usr/bin/env node
+/**
+ * Remove Forge sessions older than RETENTION_DAYS (default 14).
+ * Skips the active session unless --include-active is passed.
+ *
+ * Usage:
+ *   forge cleanup
+ *   forge cleanup-sessions [--dry-run] [--include-active]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  clearActive,
+  loadSession,
+  readActive,
+  RETENTION_DAYS,
+  SESSIONS_DIR,
+  sessionAgeDays,
+} from './lib.mjs';
+import { unregisterSession } from './lib/fleet.mjs';
+import { appendScorecardLedger } from './score.mjs';
+
+const args = new Set(process.argv.slice(2));
+const dryRun = args.has('--dry-run');
+const includeActive = args.has('--include-active');
+
+const active = readActive();
+const activeId = active?.sessionId ?? null;
+const removed = [];
+const kept = [];
+
+if (!fs.existsSync(SESSIONS_DIR)) {
+  process.stdout.write(JSON.stringify({ removed, kept, dryRun }, null, 2));
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+for (const entry of fs.readdirSync(SESSIONS_DIR, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const sessionId = entry.name;
+  const dir = path.join(SESSIONS_DIR, sessionId);
+  const sessionFile = path.join(dir, 'session.json');
+  if (!fs.existsSync(sessionFile)) continue;
+
+  let session;
+  try {
+    ({ session } = loadSession(sessionId));
+  } catch {
+    continue;
+  }
+
+  const isActive = sessionId === activeId;
+  const tooOld = sessionAgeDays(session) > RETENTION_DAYS;
+  const isDone = session.phase === 'done' || session.phase === 'skipped';
+
+  const shouldRemove =
+    (tooOld || isDone) && (!isActive || includeActive);
+
+  if (shouldRemove) {
+    if (!dryRun) {
+      // Harvest the scorecard into the durable ledger before the session dir
+      // (and its scoring history) is erased. Covers sessions scored before
+      // the ledger existed; a no-op when the ledger already has the line.
+      try {
+        const cardFile = path.join(dir, 'scorecard.json');
+        if (fs.existsSync(cardFile)) {
+          appendScorecardLedger(dir, JSON.parse(fs.readFileSync(cardFile, 'utf8')), session);
+        }
+      } catch {
+        /* ledger is advisory — never block cleanup */
+      }
+      fs.rmSync(dir, { recursive: true, force: true });
+      if (isActive) clearActive();
+      unregisterSession(process.cwd(), sessionId);
+    }
+    removed.push({ sessionId, reason: tooOld ? 'retention' : 'finished' });
+  } else {
+    kept.push({ sessionId, phase: session.phase, ageDays: sessionAgeDays(session).toFixed(1) });
+  }
+}
+
+process.stdout.write(JSON.stringify({ removed, kept, dryRun, retentionDays: RETENTION_DAYS }, null, 2));
+process.stdout.write('\n');

package/src/config.mjs

@@ -1,103 +1,103 @@
-#!/usr/bin/env node
-/**
- * Shared user (~/.forgekit/config.json) and project (.forge/config.json) config IO.
- */
-
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-/**
- * @param {string} [home]
- * @returns {string}
- */
-export function userConfigPath(home = os.homedir()) {
-  return path.join(home, '.forgekit', 'config.json');
-}
-
-/**
- * @param {string} [home]
- * @returns {Record<string, unknown>}
- */
-export function loadUserConfig(home = os.homedir()) {
-  const p = userConfigPath(home);
-  if (!fs.existsSync(p)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Deep-merge top-level keys; nested objects under named keys are shallow-merged.
- * @param {Record<string, unknown>} patch
- * @param {string} [home]
- * @param {string[]} [mergeKeys] keys to shallow-merge instead of replace
- */
-export function saveUserConfig(patch, home = os.homedir(), mergeKeys = ['adr', 'plan']) {
-  const dir = path.dirname(userConfigPath(home));
-  fs.mkdirSync(dir, { recursive: true });
-  const current = loadUserConfig(home);
-  /** @type {Record<string, unknown>} */
-  const next = { ...current, ...patch };
-  for (const key of mergeKeys) {
-    if (patch[key] && typeof patch[key] === 'object') {
-      next[key] = {
-        ...((current[key] && typeof current[key] === 'object' ? current[key] : {})),
-        .../** @type {Record<string, unknown>} */ (patch[key]),
-      };
-    }
-  }
-  fs.writeFileSync(userConfigPath(home), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
-  return next;
-}
-
-/**
- * @param {string} cwd
- * @returns {string}
- */
-export function projectConfigPath(cwd) {
-  return path.join(cwd, '.forge', 'config.json');
-}
-
-/**
- * @param {string} cwd
- * @returns {Record<string, unknown>}
- */
-export function loadProjectConfig(cwd) {
-  const p = projectConfigPath(cwd);
-  if (!fs.existsSync(p)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Merge-write project config. Nested mergeKeys are shallow-merged unless listed in replaceKeys.
- * @param {string} cwd
- * @param {Record<string, unknown>} patch
- * @param {{ mergeKeys?: string[], replaceKeys?: string[] }} [opts]
- */
-export function saveProjectConfig(cwd, patch, opts = {}) {
-  const mergeKeys = opts.mergeKeys ?? ['adr', 'plan'];
-  const replaceKeys = new Set(opts.replaceKeys ?? []);
-  const p = projectConfigPath(cwd);
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  const current = loadProjectConfig(cwd);
-  /** @type {Record<string, unknown>} */
-  const next = { ...current, ...patch };
-  for (const key of mergeKeys) {
-    if (replaceKeys.has(key)) continue;
-    if (patch[key] && typeof patch[key] === 'object') {
-      next[key] = {
-        ...((current[key] && typeof current[key] === 'object' ? current[key] : {})),
-        .../** @type {Record<string, unknown>} */ (patch[key]),
-      };
-    }
-  }
-  fs.writeFileSync(p, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
-  return next;
-}
+#!/usr/bin/env node
+/**
+ * Shared user (~/.forgekit/config.json) and project (.forge/config.json) config IO.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * @param {string} [home]
+ * @returns {string}
+ */
+export function userConfigPath(home = os.homedir()) {
+  return path.join(home, '.forgekit', 'config.json');
+}
+
+/**
+ * @param {string} [home]
+ * @returns {Record<string, unknown>}
+ */
+export function loadUserConfig(home = os.homedir()) {
+  const p = userConfigPath(home);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Deep-merge top-level keys; nested objects under named keys are shallow-merged.
+ * @param {Record<string, unknown>} patch
+ * @param {string} [home]
+ * @param {string[]} [mergeKeys] keys to shallow-merge instead of replace
+ */
+export function saveUserConfig(patch, home = os.homedir(), mergeKeys = ['adr', 'plan']) {
+  const dir = path.dirname(userConfigPath(home));
+  fs.mkdirSync(dir, { recursive: true });
+  const current = loadUserConfig(home);
+  /** @type {Record<string, unknown>} */
+  const next = { ...current, ...patch };
+  for (const key of mergeKeys) {
+    if (patch[key] && typeof patch[key] === 'object') {
+      next[key] = {
+        ...((current[key] && typeof current[key] === 'object' ? current[key] : {})),
+        .../** @type {Record<string, unknown>} */ (patch[key]),
+      };
+    }
+  }
+  fs.writeFileSync(userConfigPath(home), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function projectConfigPath(cwd) {
+  return path.join(cwd, '.forge', 'config.json');
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, unknown>}
+ */
+export function loadProjectConfig(cwd) {
+  const p = projectConfigPath(cwd);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge-write project config. Nested mergeKeys are shallow-merged unless listed in replaceKeys.
+ * @param {string} cwd
+ * @param {Record<string, unknown>} patch
+ * @param {{ mergeKeys?: string[], replaceKeys?: string[] }} [opts]
+ */
+export function saveProjectConfig(cwd, patch, opts = {}) {
+  const mergeKeys = opts.mergeKeys ?? ['adr', 'plan'];
+  const replaceKeys = new Set(opts.replaceKeys ?? []);
+  const p = projectConfigPath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const current = loadProjectConfig(cwd);
+  /** @type {Record<string, unknown>} */
+  const next = { ...current, ...patch };
+  for (const key of mergeKeys) {
+    if (replaceKeys.has(key)) continue;
+    if (patch[key] && typeof patch[key] === 'object') {
+      next[key] = {
+        ...((current[key] && typeof current[key] === 'object' ? current[key] : {})),
+        .../** @type {Record<string, unknown>} */ (patch[key]),
+      };
+    }
+  }
+  fs.writeFileSync(p, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}