@izkac/forgekit 0.3.13 → 0.3.14

package/bin/forge.mjs

@@ -9,6 +9,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { findRepoRoot } from '../src/repo-root.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SRC = path.join(__dirname, '..', 'src');
@@ -93,12 +94,23 @@ if (!entry) {
   process.exit(1);
 }
 
-const args = [...(entry.prependArgs ?? []), ...rest];
+// Every subcommand is project-scoped, so run it from the project root rather
+// than wherever the shell happens to sit: `cd crates && forge status` used to
+// report "no session" and `forge new` would have written a second .forge tree
+// inside the workspace. An explicit relative `--cwd` still means what the
+// caller typed, so absolutize it against the invocation dir first.
+const invokedFrom = process.cwd();
+const repoRoot = findRepoRoot(invokedFrom);
+const args = [...(entry.prependArgs ?? []), ...rest].map((arg, i, all) =>
+  i > 0 && all[i - 1] === '--cwd' && !path.isAbsolute(arg) ? path.resolve(invokedFrom, arg) : arg,
+);
+
 const r = spawnSync(process.execPath, [path.join(SRC, entry.script), ...args], {
   stdio: 'inherit',
-  cwd: process.cwd(),
+  cwd: repoRoot,
   env: {
     ...process.env,
+    FORGE_INVOKED_FROM: invokedFrom,
     FORGEKIT_ROOT: path.resolve(__dirname, '..', '..', '..'),
     FORGEKIT_CLI_ROOT: path.resolve(__dirname, '..'),
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   ],
   "scripts": {
     "prepack": "node scripts/prepack.mjs",
+    "prepublishOnly": "npm run lint && npm test",
     "test": "node scripts/run-tests.mjs",
     "lint": "eslint src bin scripts"
   },

package/src/fleet.test.mjs

@@ -80,6 +80,56 @@ test('listFleet self-heals entries whose session dir is gone', () => {
   assert.equal(fs.existsSync(entryFile(project, 'gone')), false);
 });
 
+test('listFleet reconciles a stale entry against session.json on disk', () => {
+  // Regression: the registry is a cache, not a source of truth. A session
+  // whose phase advanced without a mirroring write (older CLI, a crash, a
+  // hand-edited record) showed its first-registered phase forever — helm's
+  // phase-0 sat at `brainstorm` in `forge fleet list` after reaching `done`.
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-reconcile-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  const sessionDir = makeProject(project, 's5');
+
+  registerSession(project, makeSession('s5', { phase: 'brainstorm', tasksComplete: 0 }));
+  // Disk moves on without the registry.
+  const later = new Date(Date.now() + 60_000).toISOString();
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify(
+      makeSession('s5', {
+        phase: 'done',
+        tasksTotal: 20,
+        tasksComplete: 20,
+        openspecChange: 'phase-0',
+        updatedAt: later,
+      }),
+    )}\n`,
+    'utf8',
+  );
+
+  const [entry] = listFleet();
+  assert.equal(entry.phase, 'done');
+  assert.equal(entry.tasksComplete, 20);
+  assert.equal(entry.tasksTotal, 20);
+  assert.equal(entry.openspecChange, 'phase-0');
+  assert.equal(entry.updatedAt, later);
+  // Reconciliation is persisted, so the next read is already correct.
+  assert.equal(JSON.parse(fs.readFileSync(entryFile(project, 's5'), 'utf8')).phase, 'done');
+  // lastSeen is a heartbeat, not a session field — reconciling must not forge one.
+  assert.ok(entry.lastSeen <= new Date().toISOString());
+});
+
+test('listFleet keeps registry-only fields when session.json is unreadable', () => {
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-unreadable-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  const sessionDir = makeProject(project, 's6');
+  registerSession(project, makeSession('s6', { phase: 'verify' }));
+  fs.writeFileSync(path.join(sessionDir, 'session.json'), '{ not json', 'utf8');
+
+  const [entry] = listFleet();
+  assert.equal(entry.phase, 'verify');
+  assert.equal(entry.missing, false);
+});
+
 test('saveSession mirrors into the fleet registry', () => {
   process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-mirror-'), 'sessions');
   const project = tmp('fleet-proj-');

package/src/integrity.mjs

@@ -112,9 +112,15 @@ export function resolveChangeDir(opts = {}) {
     return forWrite ? openspecDir : liveOrArchived(openspecChanges, change);
   }
 
+  // Only a *specs* engine resolution can name the specs dir. The engine
+  // resolver's last resort is {engine:'openspec', dir:'openspec'}, so taking
+  // `.dir` unconditionally pointed specs sessions at `openspec/changes/<name>`
+  // in every project whose .forge/config.json has no `plan` block — the change
+  // dir, its brief.html, spine.json and e2e.json all silently missing.
   let specsRoot = DEFAULT_SPECS_DIR;
   try {
-    specsRoot = resolveProjectPlanEngine(cwd, { useUserDefault: false }).dir;
+    const engine = resolveProjectPlanEngine(cwd, { useUserDefault: false });
+    if (engine.engine === 'specs') specsRoot = engine.dir;
   } catch {
     // keep default
   }

package/src/integrity.test.mjs

@@ -146,6 +146,52 @@ test('resolveChangeDir: falls back to the archived copy after archive', () => {
   }
 });
 
+test('resolveChangeDir: a specs session never falls back to the openspec dir', () => {
+  // Regression: resolveProjectPlanEngine's last-resort default is
+  // {engine:'openspec', dir:'openspec'}, so a specs-engine session in a
+  // project whose .forge/config.json has no `plan` block (ADR-only config,
+  // pre-engine config, hand-written) resolved into openspec/changes/<name> —
+  // which made `forge phase implement` refuse a brief that was right there.
+  const cwd = tmp('forge-specs-dir-');
+  try {
+    const session = { planType: 'specs', openspecChange: 'my-change' };
+    fs.mkdirSync(path.join(cwd, '.forge'), { recursive: true });
+    fs.writeFileSync(
+      path.join(cwd, '.forge', 'config.json'),
+      `${JSON.stringify({ adr: { enabled: true, dir: 'docs/adr' } })}\n`,
+      'utf8',
+    );
+    const specsChange = path.join(cwd, 'specs', 'changes', 'my-change');
+    fs.mkdirSync(specsChange, { recursive: true });
+
+    assert.equal(resolveChangeDir({ cwd, session }), specsChange);
+    assert.equal(resolveChangeDir({ cwd, session, forWrite: true }), specsChange);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('resolveChangeDir: specs engine honors a configured plan.dir', () => {
+  // `forge init --no-openspec --plan-dir openspec` — specs engine reusing an
+  // existing OpenSpec tree without moving files.
+  const cwd = tmp('forge-specs-plandir-');
+  try {
+    const session = { planType: 'specs', openspecChange: 'my-change' };
+    fs.mkdirSync(path.join(cwd, '.forge'), { recursive: true });
+    fs.writeFileSync(
+      path.join(cwd, '.forge', 'config.json'),
+      `${JSON.stringify({ plan: { engine: 'specs', dir: 'openspec' } })}\n`,
+      'utf8',
+    );
+    const changeDir = path.join(cwd, 'openspec', 'changes', 'my-change');
+    fs.mkdirSync(changeDir, { recursive: true });
+
+    assert.equal(resolveChangeDir({ cwd, session }), changeDir);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
 test('spinePath/e2ePath forWrite target the live dir even after archive', () => {
   const cwd = tmp('forge-write-guard-');
   try {

package/src/lib/fleet.mjs

@@ -134,10 +134,59 @@ export function unregisterSession(projectRoot, sessionId) {
 }
 
 /**
- * All registry entries, newest first. Self-heals: entries whose session dir
- * vanished (cleanup ran without unregister, project deleted the .forge dir)
- * are removed; entries whose whole project path is unreachable (unplugged
- * drive) are kept and marked `missing`.
+ * Fields the registry mirrors from session.json. `session.json` is the source
+ * of truth; the entry is only a cache, so reads refresh it.
+ */
+const MIRRORED_FIELDS = [
+  'slug',
+  'phase',
+  'planType',
+  'openspecChange',
+  'tasksTotal',
+  'tasksComplete',
+  'createdAt',
+  'updatedAt',
+];
+
+/**
+ * Refresh a cached entry from the session on disk. Returns true when anything
+ * changed. A registry write that never happened (older CLI, a crash mid-run,
+ * a hand-edited record) otherwise pins the entry at whatever phase it was
+ * first registered with, forever.
+ *
+ * @param {Record<string, any>} entry
+ * @param {string} sessionDir
+ */
+function reconcileEntry(entry, sessionDir) {
+  let session;
+  try {
+    session = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+  } catch {
+    return false; // unreadable/absent — keep the cached view
+  }
+  let changed = false;
+  for (const key of MIRRORED_FIELDS) {
+    const value = session[key];
+    if (value === undefined) continue;
+    if (entry[key] !== value) {
+      entry[key] = value;
+      changed = true;
+    }
+  }
+  const pace = session.resolvedPace ?? session.pace ?? null;
+  if (pace !== null && entry.pace !== pace) {
+    entry.pace = pace;
+    changed = true;
+  }
+  return changed;
+}
+
+/**
+ * All registry entries, newest first. Self-heals: entries are reconciled
+ * against each session.json on disk; entries whose session dir vanished
+ * (cleanup ran without unregister, project deleted the .forge dir) are
+ * removed; entries whose whole project path is unreachable (unplugged drive)
+ * are kept and marked `missing`.
  *
  * @returns {Array<Record<string, any>>}
  */
@@ -156,6 +205,14 @@ export function listFleet() {
     }
     const sessionDir = path.join(entry.project, '.forge', 'sessions', entry.sessionId);
     if (fs.existsSync(sessionDir)) {
+      // Persist before stamping `missing`, which is a view flag, not state.
+      if (reconcileEntry(entry, sessionDir)) {
+        try {
+          fs.writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
+        } catch {
+          /* registry is advisory — a read-only registry still renders */
+        }
+      }
       entry.missing = false;
     } else if (fs.existsSync(entry.project)) {
       fs.rmSync(file, { force: true });

package/src/lib.mjs

@@ -7,8 +7,11 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { registerSession } from './lib/fleet.mjs';
+import { findRepoRoot } from './repo-root.mjs';
 
-export const REPO_ROOT = process.cwd();
+export { findRepoRoot };
+
+export const REPO_ROOT = findRepoRoot();
 export const FORGE_DIR = path.join(REPO_ROOT, '.forge');
 export const SESSIONS_DIR = path.join(FORGE_DIR, 'sessions');
 export const ACTIVE_FILE = path.join(FORGE_DIR, 'active.json');
@@ -137,7 +140,21 @@ export function saveSession(dir, session) {
   registerSession(path.resolve(dir, '..', '..', '..'), session);
 }
 
+/**
+ * Age of a session in days, for retention. Legacy and hand-written records
+ * carry `startedAt` (or nothing) instead of `createdAt`; an undatable record
+ * counts as **infinitely old** rather than brand new — `new Date(undefined)`
+ * is NaN and `NaN > RETENTION_DAYS` is false, which let abandoned sessions
+ * survive every cleanup run forever.
+ *
+ * @param {Record<string, any>} session
+ * @returns {number} days, or Infinity when no date can be read
+ */
 export function sessionAgeDays(session) {
-  const created = new Date(session.createdAt).getTime();
-  return (Date.now() - created) / (1000 * 60 * 60 * 24);
+  for (const value of [session?.createdAt, session?.startedAt, session?.updatedAt]) {
+    if (!value) continue;
+    const at = new Date(value).getTime();
+    if (!Number.isNaN(at)) return (Date.now() - at) / (1000 * 60 * 60 * 24);
+  }
+  return Infinity;
 }

package/src/lib.test.mjs

@@ -0,0 +1,128 @@
+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 { findRepoRoot, sessionAgeDays } from './lib.mjs';
+
+const SESSION_STATUS = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'session-status.mjs',
+);
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+test('sessionAgeDays reads createdAt, then startedAt, then updatedAt', () => {
+  const days = (n) => new Date(Date.now() - n * 86400000).toISOString();
+
+  assert.ok(Math.abs(sessionAgeDays({ createdAt: days(3) }) - 3) < 0.01);
+  // Hand-written / legacy records carry startedAt (a bare date) instead.
+  assert.ok(Math.abs(sessionAgeDays({ startedAt: days(5).slice(0, 10) }) - 5) < 1.01);
+  assert.ok(Math.abs(sessionAgeDays({ updatedAt: days(2) }) - 2) < 0.01);
+  // createdAt wins when several are present.
+  assert.ok(
+    Math.abs(sessionAgeDays({ createdAt: days(9), startedAt: days(1), updatedAt: days(1) }) - 9) <
+      0.01,
+  );
+});
+
+test('sessionAgeDays treats an undatable session as infinitely old, not age 0', () => {
+  // Regression: `new Date(undefined)` → NaN, and `NaN > RETENTION_DAYS` is
+  // false, so a session record without a date was never "too old" and
+  // survived every cleanup run forever.
+  assert.equal(sessionAgeDays({ phase: 'implement' }), Infinity);
+  assert.equal(sessionAgeDays({ createdAt: 'not-a-date' }), Infinity);
+  assert.equal(sessionAgeDays({}), Infinity);
+});
+
+test('forge cleanup removes an undatable abandoned session', () => {
+  const root = tmp('forge-cleanup-');
+  const sessionDir = path.join(root, '.forge', 'sessions', 'legacy');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    // No date of any kind — the shape that lingered in volo, minus the
+    // startedAt that now gives such records a real age.
+    `${JSON.stringify({ slug: 'legacy', phase: 'implement' })}\n`,
+    'utf8',
+  );
+
+  const cleanup = path.join(path.dirname(SESSION_STATUS), 'cleanup-sessions.mjs');
+  const out = execFileSync(process.execPath, [cleanup], {
+    cwd: root,
+    env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('forge-cleanup-fleet-'), 's') },
+  }).toString();
+
+  assert.match(out, /"reason": "retention"/);
+  assert.equal(fs.existsSync(sessionDir), false);
+});
+
+test('findRepoRoot walks up to the nearest .forge, then .git, then falls back', () => {
+  const root = tmp('forge-root-');
+  const nested = path.join(root, 'crates', 'helm-vfs', 'src');
+  fs.mkdirSync(nested, { recursive: true });
+
+  // No markers anywhere: the start dir is the root.
+  assert.equal(findRepoRoot(nested), nested);
+
+  // .git alone marks the project.
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+  assert.equal(findRepoRoot(nested), root);
+
+  // .forge wins over .git when both are present but at different depths:
+  // a nested checkout with its own session is its own project.
+  const inner = path.join(root, 'crates');
+  fs.mkdirSync(path.join(inner, '.forge'), { recursive: true });
+  assert.equal(findRepoRoot(nested), inner);
+  assert.equal(findRepoRoot(root), root);
+});
+
+test('forge status finds the session from a subdirectory of the project', () => {
+  const root = tmp('forge-subdir-');
+  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: 'implement',
+      planType: 'specs',
+      openspecChange: 'my-change',
+      tasksTotal: 3,
+      tasksComplete: 1,
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  const nested = path.join(root, 'crates', 'helm-vfs');
+  fs.mkdirSync(nested, { recursive: true });
+
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('forge-subdir-fleet-'), 's') };
+  const out = execFileSync(process.execPath, [SESSION_STATUS], { cwd: nested, env }).toString();
+  const status = JSON.parse(out);
+
+  assert.equal(status.status, 'ok');
+  assert.equal(status.sessionId, 's1');
+  // Paths stay relative to the project root, not to the working directory.
+  assert.equal(status.sessionPath, '.forge/sessions/s1');
+
+  // ...and through the bin, which re-roots the child process, so writes land
+  // in the project's .forge rather than creating a second tree in the subdir.
+  const FORGE_BIN = path.join(path.dirname(SESSION_STATUS), '..', 'bin', 'forge.mjs');
+  execFileSync(process.execPath, [FORGE_BIN, 'phase', 'brainstorm'], { cwd: nested, env });
+  const saved = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+  assert.equal(saved.phase, 'brainstorm');
+  assert.equal(fs.existsSync(path.join(nested, '.forge')), false);
+});

package/src/repo-root.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Project-root resolution.
+ *
+ * Standalone (node builtins only) so the `forge` bin can re-root itself
+ * without importing session machinery.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Nearest enclosing project root: the closest ancestor holding `.forge/`,
+ * else the closest holding `.git/` (a repo boundary — a nested checkout must
+ * not adopt the enclosing project's sessions), else the start dir.
+ *
+ * Without this, forge was bound to the exact cwd: `cd crates && forge status`
+ * reported "no session" in a repo that had one, and `forge new` there would
+ * have created a second `.forge` tree inside the workspace.
+ *
+ * @param {string} [start]
+ * @returns {string}
+ */
+export function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.forge'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(start);
+    dir = parent;
+  }
+}

package/src/specs-sync.mjs

@@ -115,10 +115,8 @@ export function applyDeltaToMain(capability, mainBody, deltaBody) {
   const reqHeaderEnd = reqMatch ? reqMatch.index + reqMatch[0].length : main.length;
   const before = main.slice(0, reqHeaderEnd);
   const afterReq = main.slice(reqHeaderEnd);
-  // Stop at next ## section if any
-  const nextSection = /^##\s+/m.exec(afterReq.replace(/^\n/, ''));
-  // Simpler: treat everything after ## Requirements as the requirements body
-  // until EOF (OpenSpec main specs usually end there).
+  // Treat everything after ## Requirements as the requirements body until the
+  // next non-Requirements ## heading (OpenSpec main specs usually end there).
   let reqBody = afterReq.replace(/^\n+/, '');
   const trailingMatch = /\n##\s+(?!Requirements).*$/m.exec(`\n${reqBody}`);
   let trailing = '';