@izkac/forgekit 0.3.12 → 0.3.14

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

@@ -1,143 +1,160 @@
-#!/usr/bin/env node
-/**
- * Shared helpers for Forge session management.
- */
-
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { registerSession } from './lib/fleet.mjs';
-
-export const REPO_ROOT = process.cwd();
-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');
-export const RETENTION_DAYS = 14;
-
-export function ensureForgeLayout() {
-  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
-}
-
-export function slugify(input) {
-  return String(input)
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 48) || 'session';
-}
-
-export function utcCompactNow() {
-  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
-}
-
-export function randomSuffix(bytes = 3) {
-  return crypto.randomBytes(bytes).toString('hex');
-}
-
-export function makeSessionId(slug) {
-  return `${utcCompactNow()}-${slugify(slug)}-${randomSuffix()}`;
-}
-
-export function sessionPath(sessionId) {
-  return path.join(SESSIONS_DIR, sessionId);
-}
-
-export function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-}
-
-export function writeJson(filePath, data) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
-}
-
-export function readActive() {
-  if (!fs.existsSync(ACTIVE_FILE)) return null;
-  try {
-    return readJson(ACTIVE_FILE);
-  } catch {
-    return null;
-  }
-}
-
-export function writeActive(sessionId) {
-  writeJson(ACTIVE_FILE, {
-    sessionId,
-    sessionPath: path.relative(REPO_ROOT, sessionPath(sessionId)).replace(/\\/g, '/'),
-    updatedAt: new Date().toISOString(),
-  });
-}
-
-export function clearActive() {
-  if (fs.existsSync(ACTIVE_FILE)) fs.unlinkSync(ACTIVE_FILE);
-}
-
-export function defaultSession(sessionId, slug) {
-  const now = new Date().toISOString();
-  return {
-    id: sessionId,
-    slug: slugify(slug),
-    createdAt: now,
-    updatedAt: now,
-    phase: 'triage',
-    planType: null,
-    openspecChange: null,
-    forgeSkipped: false,
-    cursorChatId: null,
-    tasksTotal: 0,
-    tasksComplete: 0,
-    /** Requested pace: auto | thorough | standard | brisk | lite */
-    pace: 'auto',
-    /** Concrete pace after auto resolve or explicit pin */
-    resolvedPace: null,
-    paceReason: null,
-    paceSignal: null,
-    pacePinned: false,
-    preferencesOverride: null,
-  };
-}
-
-export function defaultStatus(session) {
-  return {
-    sessionId: session.id,
-    phase: session.phase,
-    planType: session.planType,
-    openspecChange: session.openspecChange,
-    tasksTotal: session.tasksTotal,
-    tasksComplete: session.tasksComplete,
-    pace: session.pace ?? null,
-    resolvedPace: session.resolvedPace ?? null,
-    paceReason: session.paceReason ?? null,
-    updatedAt: session.updatedAt,
-  };
-}
-
-export function scaffoldSessionDirs(dir) {
-  for (const sub of ['brainstorm', 'tasks', 'reviews']) {
-    fs.mkdirSync(path.join(dir, sub), { recursive: true });
-  }
-}
-
-export function loadSession(sessionId) {
-  const dir = sessionPath(sessionId);
-  const file = path.join(dir, 'session.json');
-  if (!fs.existsSync(file)) {
-    throw new Error(`Session not found: ${sessionId}`);
-  }
-  return { dir, session: readJson(file) };
-}
-
-export function saveSession(dir, session) {
-  session.updatedAt = new Date().toISOString();
-  writeJson(path.join(dir, 'session.json'), session);
-  writeJson(path.join(dir, 'status.json'), defaultStatus(session));
-  // Mirror into ~/.forgekit/fleet so `forge fleet` sees every project's
-  // sessions. Project root derived from dir (<root>/.forge/sessions/<id>),
-  // not REPO_ROOT, so callers with explicit dirs mirror correctly too.
-  registerSession(path.resolve(dir, '..', '..', '..'), session);
-}
-
-export function sessionAgeDays(session) {
-  const created = new Date(session.createdAt).getTime();
-  return (Date.now() - created) / (1000 * 60 * 60 * 24);
-}
+#!/usr/bin/env node
+/**
+ * Shared helpers for Forge session management.
+ */
+
+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 { 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');
+export const RETENTION_DAYS = 14;
+
+export function ensureForgeLayout() {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+export function slugify(input) {
+  return String(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'session';
+}
+
+export function utcCompactNow() {
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+export function randomSuffix(bytes = 3) {
+  return crypto.randomBytes(bytes).toString('hex');
+}
+
+export function makeSessionId(slug) {
+  return `${utcCompactNow()}-${slugify(slug)}-${randomSuffix()}`;
+}
+
+export function sessionPath(sessionId) {
+  return path.join(SESSIONS_DIR, sessionId);
+}
+
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+export function readActive() {
+  if (!fs.existsSync(ACTIVE_FILE)) return null;
+  try {
+    return readJson(ACTIVE_FILE);
+  } catch {
+    return null;
+  }
+}
+
+export function writeActive(sessionId) {
+  writeJson(ACTIVE_FILE, {
+    sessionId,
+    sessionPath: path.relative(REPO_ROOT, sessionPath(sessionId)).replace(/\\/g, '/'),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export function clearActive() {
+  if (fs.existsSync(ACTIVE_FILE)) fs.unlinkSync(ACTIVE_FILE);
+}
+
+export function defaultSession(sessionId, slug) {
+  const now = new Date().toISOString();
+  return {
+    id: sessionId,
+    slug: slugify(slug),
+    createdAt: now,
+    updatedAt: now,
+    phase: 'triage',
+    planType: null,
+    openspecChange: null,
+    forgeSkipped: false,
+    cursorChatId: null,
+    tasksTotal: 0,
+    tasksComplete: 0,
+    /** Requested pace: auto | thorough | standard | brisk | lite */
+    pace: 'auto',
+    /** Concrete pace after auto resolve or explicit pin */
+    resolvedPace: null,
+    paceReason: null,
+    paceSignal: null,
+    pacePinned: false,
+    preferencesOverride: null,
+  };
+}
+
+export function defaultStatus(session) {
+  return {
+    sessionId: session.id,
+    phase: session.phase,
+    planType: session.planType,
+    openspecChange: session.openspecChange,
+    tasksTotal: session.tasksTotal,
+    tasksComplete: session.tasksComplete,
+    pace: session.pace ?? null,
+    resolvedPace: session.resolvedPace ?? null,
+    paceReason: session.paceReason ?? null,
+    updatedAt: session.updatedAt,
+  };
+}
+
+export function scaffoldSessionDirs(dir) {
+  for (const sub of ['brainstorm', 'tasks', 'reviews']) {
+    fs.mkdirSync(path.join(dir, sub), { recursive: true });
+  }
+}
+
+export function loadSession(sessionId) {
+  const dir = sessionPath(sessionId);
+  const file = path.join(dir, 'session.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  return { dir, session: readJson(file) };
+}
+
+export function saveSession(dir, session) {
+  session.updatedAt = new Date().toISOString();
+  writeJson(path.join(dir, 'session.json'), session);
+  writeJson(path.join(dir, 'status.json'), defaultStatus(session));
+  // Mirror into ~/.forgekit/fleet so `forge fleet` sees every project's
+  // sessions. Project root derived from dir (<root>/.forge/sessions/<id>),
+  // not REPO_ROOT, so callers with explicit dirs mirror correctly too.
+  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) {
+  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/models.defaults.json

@@ -1,41 +1,41 @@
-{
-  "billing": "included",
-  "agents": {
-    "cursor": {
-      "included": {
-        "fast": "inherit",
-        "standard": "inherit",
-        "capable": "inherit"
-      },
-      "metered": {
-        "fast": "gpt-5.6-terra-medium",
-        "standard": "claude-sonnet-5-thinking-high",
-        "capable": "claude-opus-4-8-thinking-high"
-      }
-    },
-    "claude-code": {
-      "included": {
-        "fast": "haiku",
-        "standard": "sonnet",
-        "capable": "opus"
-      },
-      "metered": {
-        "fast": "haiku",
-        "standard": "sonnet",
-        "capable": "opus"
-      }
-    },
-    "codex": {
-      "included": {
-        "fast": "inherit",
-        "standard": "inherit",
-        "capable": "inherit"
-      },
-      "metered": {
-        "fast": "inherit",
-        "standard": "inherit",
-        "capable": "inherit"
-      }
-    }
-  }
-}
+{
+  "billing": "included",
+  "agents": {
+    "cursor": {
+      "included": {
+        "fast": "inherit",
+        "standard": "inherit",
+        "capable": "inherit"
+      },
+      "metered": {
+        "fast": "gpt-5.6-terra-medium",
+        "standard": "claude-sonnet-5-thinking-high",
+        "capable": "claude-opus-4-8-thinking-high"
+      }
+    },
+    "claude-code": {
+      "included": {
+        "fast": "haiku",
+        "standard": "sonnet",
+        "capable": "opus"
+      },
+      "metered": {
+        "fast": "haiku",
+        "standard": "sonnet",
+        "capable": "opus"
+      }
+    },
+    "codex": {
+      "included": {
+        "fast": "inherit",
+        "standard": "inherit",
+        "capable": "inherit"
+      },
+      "metered": {
+        "fast": "inherit",
+        "standard": "inherit",
+        "capable": "inherit"
+      }
+    }
+  }
+}