cap-pro 1.0.0

package/cap/bin/lib/cap-session.cjs

@@ -0,0 +1,445 @@
+// @cap-context CAP v2.0 session manager -- manages .cap/SESSION.json for cross-conversation workflow state.
+// @cap-decision SESSION.json is ephemeral (gitignored) -- it tracks the current developer's workflow state, not project state. Project state lives in FEATURE-MAP.md.
+// @cap-decision JSON format (not markdown) -- session state is machine-consumed, not human-read. JSON is faster to parse and type-safe.
+// @cap-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path).
+// @cap-pattern All session reads/writes go through this module -- no direct fs.readFileSync of SESSION.json elsewhere.
+
+'use strict';
+
+// @cap-feature(feature:F-003) Session State Management — .cap/SESSION.json for cross-conversation workflow state
+
+// @cap-history(sessions:2, edits:4, since:2026-05-08, learned:2026-05-08) Frequently modified — 2 sessions, 4 edits
+const fs = require('node:fs');
+const path = require('node:path');
+
+// @cap-decision Session schema is flat and extensible -- new workflow commands can add keys without schema migration.
+// @cap-todo(ref:AC-16) SESSION.json tracks ephemeral workflow state: active feature ID, current workflow step, session timestamps
+/**
+ * @typedef {Object} CapQuickMode
+ * @property {boolean} active - Whether quick-mode is currently active
+ * @property {string|null} feature - Feature ID being worked on (mirrors activeFeature when entered via /cap:quick)
+ * @property {string|null} startedAt - ISO timestamp when quick-mode started
+ * @property {string|null} startCommit - git HEAD SHA at quick-mode entry — used by /cap:finalize to compute changed files
+ */
+
+/**
+ * @typedef {Object} CapSession
+ * @property {string} version - Session schema version (e.g., "2.0.0")
+ * @property {string|null} lastCommand - Last /cap: command executed
+ * @property {string|null} lastCommandTimestamp - ISO timestamp of last command
+ * @property {string|null} activeApp - Currently focused app path (e.g., "apps/flow") or null for single-repo/root
+ * @property {string|null} activeFeature - Currently focused feature ID
+ * @property {string|null} step - Current workflow step
+ * @property {string|null} startedAt - ISO timestamp of when session started
+ * @property {string|null} activeDebugSession - Active debug session ID
+ * @property {'A'|'B'|'C'} trustMode - @cap-feature(feature:F-075) Trust-Mode slot — mirrored from .cap/config.json by cap-trust-mode.
+ * @property {CapQuickMode} quickMode - @cap-feature(feature:F-092) Two-phase workflow state — Phase 1 fast-lane editing
+ * @property {Object<string,string>} metadata - Extensible key-value metadata
+ */
+
+const CAP_DIR = '.cap';
+const SESSION_FILE = 'SESSION.json';
+
+// @cap-todo(ref:AC-3) .cap/.gitignore ignores SESSION.json (ephemeral state shall not be committed)
+const GITIGNORE_CONTENT = `# CAP ephemeral state -- do not commit
+SESSION.json
+debug/
+`;
+
+const CAP_MEMORY_RULE = `## CAP Project Memory
+
+This project uses CAP (Code as Plan) with a project memory system at \`.cap/memory/\`.
+
+The pipeline supports **two layouts** (F-093). Detect which is active before reading:
+
+### V6 layout (per-feature, opt-in via \`.cap/config.json: { memory: { layout: "v6" } }\`)
+
+When the top-level \`decisions.md\` or \`pitfalls.md\` contains the marker \`(V6 Index)\` in its title, this project is on V6:
+
+1. **Read \`.cap/memory/decisions.md\` and \`.cap/memory/pitfalls.md\` first** — these are short index tables (\`Destination | Count | File\`) listing per-feature memory files.
+2. **Then load only the per-feature file relevant to the current task** — e.g. \`.cap/memory/features/F-XXX-<topic>.md\` if you're working on F-XXX, or a \`platform/<topic>.md\` for cross-cutting concerns.
+3. Skip reading the index entries you don't need — that is the whole point of V6 (token-cost-of-read reduction).
+
+### V5 layout (legacy, default for projects without the V6 config flag)
+
+When the top-level files do NOT have the \`(V6 Index)\` marker, read them directly as monolithic memory:
+
+- \`.cap/memory/decisions.md\` — architectural decisions extracted from code tags and sessions
+- \`.cap/memory/pitfalls.md\` — known pitfalls, gotchas, and things that broke before
+- \`.cap/memory/patterns.md\` — recurring patterns and conventions observed in the codebase
+- \`.cap/memory/hotspots.md\` — frequently edited files and areas of high churn
+
+These files are auto-generated by the CAP memory pipeline after each session. They complement your auto-memory (user preferences, feedback) with project-specific technical context.
+
+Use this knowledge to:
+- Avoid repeating past mistakes documented in pitfalls
+- Follow established patterns when writing new code
+- Understand the reasoning behind architectural choices
+- Focus attention on hotspot files that change frequently
+`;
+
+// @cap-api getDefaultSession() -- Returns a fresh default session object.
+// @cap-todo(ref:AC-2) SESSION.json with valid JSON structure: { active_feature: null, step: null, started_at: null }
+/**
+ * @returns {CapSession}
+ */
+function getDefaultSession() {
+  return {
+    version: '2.0.0',
+    lastCommand: null,
+    lastCommandTimestamp: null,
+    activeApp: null,
+    activeFeature: null,
+    step: null,
+    startedAt: null,
+    activeDebugSession: null,
+    activeThread: null,
+    // @cap-feature(feature:F-075) Trust-Mode slot — mirrored from .cap/config.json.
+    // @cap-todo(ac:F-075/AC-1) SESSION.json carries trustMode field with default 'A'.
+    // Sessions created before F-075 will land here via the { ...default, ...parsed } merge
+    // in loadSession(), so backfill is automatic on first read.
+    trustMode: 'A',
+    // @cap-feature(feature:F-092) Two-phase workflow — Phase 1 (Visual Iteration) vs Phase 2 (Solidify).
+    //   Default { active: false } so existing sessions / non-quick-mode workflows are unaffected.
+    quickMode: {
+      active: false,
+      feature: null,
+      startedAt: null,
+      startCommit: null,
+    },
+    metadata: {},
+    // @cap-feature(feature:F-057) Checkpoint persistence fields — additive, null by default.
+    // lastCheckpointAt = ISO timestamp of the most recent /cap:checkpoint that detected a breakpoint.
+    // lastCheckpointSnapshot = minimal snapshot of feature states + AC statuses at that moment,
+    // so future /cap:checkpoint runs can diff against it.
+    lastCheckpointAt: null,
+    lastCheckpointSnapshot: null,
+  };
+}
+
+// @cap-api loadSession(projectRoot) -- Loads .cap/SESSION.json. Returns default session if file missing or corrupt.
+// @cap-todo(ref:AC-19) SESSION.json is the only mutable session artifact
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {CapSession}
+ */
+function loadSession(projectRoot) {
+  const sessionPath = path.join(projectRoot, CAP_DIR, SESSION_FILE);
+  try {
+    if (!fs.existsSync(sessionPath)) return getDefaultSession();
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    const parsed = JSON.parse(content);
+    // Merge with defaults to handle missing keys from older versions
+    return { ...getDefaultSession(), ...parsed };
+  } catch (_e) {
+    // Corrupt JSON -- return default
+    return getDefaultSession();
+  }
+}
+
+// @cap-api saveSession(projectRoot, session) -- Writes .cap/SESSION.json. Creates .cap/ directory if needed.
+// @cap-todo(ref:AC-18) SESSION.json shall not be committed to version control (enforced by .cap/.gitignore)
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {CapSession} session - Session data to persist
+ */
+function saveSession(projectRoot, session) {
+  const capDir = path.join(projectRoot, CAP_DIR);
+  if (!fs.existsSync(capDir)) {
+    fs.mkdirSync(capDir, { recursive: true });
+  }
+  const sessionPath = path.join(capDir, SESSION_FILE);
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n', 'utf8');
+}
+
+// @cap-api updateSession(projectRoot, updates) -- Partial update to session (merge, not overwrite).
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Partial<CapSession>} updates - Fields to merge into current session
+ * @returns {CapSession} - The updated session
+ */
+function updateSession(projectRoot, updates) {
+  const session = loadSession(projectRoot);
+  // Shallow merge -- metadata gets replaced if present in updates
+  const updated = { ...session, ...updates };
+  saveSession(projectRoot, updated);
+  return updated;
+}
+
+// @cap-api startSession(projectRoot, featureId, step) -- Set active feature and step with timestamp.
+// @cap-todo(ref:AC-17) SESSION.json connects to FEATURE-MAP.md only via feature IDs (loose coupling)
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} featureId - Feature ID to focus on (e.g., "F-001")
+ * @param {string} step - Current workflow step name
+ * @returns {CapSession}
+ */
+function startSession(projectRoot, featureId, step) {
+  return updateSession(projectRoot, {
+    activeFeature: featureId,
+    step,
+    startedAt: new Date().toISOString(),
+  });
+}
+
+// @cap-api updateStep(projectRoot, step) -- Update current workflow step.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} step - New workflow step name
+ * @returns {CapSession}
+ */
+function updateStep(projectRoot, step) {
+  return updateSession(projectRoot, { step });
+}
+
+// @cap-api endSession(projectRoot) -- Clear active feature and step.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {CapSession}
+ */
+function endSession(projectRoot) {
+  return updateSession(projectRoot, {
+    activeFeature: null,
+    step: null,
+    startedAt: null,
+  });
+}
+
+// @cap-api isInitialized(projectRoot) -- Check if .cap/ exists.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean}
+ */
+function isInitialized(projectRoot) {
+  return fs.existsSync(path.join(projectRoot, CAP_DIR));
+}
+
+// @cap-api initCapDirectory(projectRoot) -- Creates .cap/ directory structure and .gitignore. Idempotent.
+// @cap-todo(ref:AC-4) No prompts, questions, wizards, or configuration forms
+// @cap-todo(ref:AC-5) Completes in a single invocation with no follow-up steps
+// @cap-todo(ref:AC-6) Idempotent -- running on already-initialized project shall not overwrite existing content
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ */
+function initCapDirectory(projectRoot) {
+  const capDir = path.join(projectRoot, CAP_DIR);
+  const stackDocsDir = path.join(capDir, 'stack-docs');
+  const debugDir = path.join(capDir, 'debug');
+  const gitignorePath = path.join(capDir, '.gitignore');
+  const sessionPath = path.join(capDir, SESSION_FILE);
+
+  // Create directories (idempotent via recursive:true)
+  fs.mkdirSync(capDir, { recursive: true });
+  fs.mkdirSync(stackDocsDir, { recursive: true });
+  fs.mkdirSync(debugDir, { recursive: true });
+
+  // Write .gitignore (always overwrite -- it's infrastructure, not user content)
+  fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, 'utf8');
+
+  // Write SESSION.json only if it doesn't exist (preserve existing session)
+  if (!fs.existsSync(sessionPath)) {
+    saveSession(projectRoot, getDefaultSession());
+  }
+
+  // Create .claude/rules/cap-memory.md -- bridges CAP project memory with Claude auto-memory
+  const rulesDir = path.join(projectRoot, '.claude', 'rules');
+  const memoryRulePath = path.join(rulesDir, 'cap-memory.md');
+  if (!fs.existsSync(memoryRulePath)) {
+    fs.mkdirSync(rulesDir, { recursive: true });
+    fs.writeFileSync(memoryRulePath, CAP_MEMORY_RULE, 'utf8');
+  }
+}
+
+// @cap-api setActiveApp(projectRoot, appPath) -- Set the active app in SESSION.json for monorepo scoping.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string|null} appPath - Relative app path (e.g., "apps/flow") or null to clear
+ * @returns {CapSession}
+ */
+function setActiveApp(projectRoot, appPath) {
+  return updateSession(projectRoot, { activeApp: appPath || null });
+}
+
+// @cap-api getActiveApp(projectRoot) -- Get current active app path from SESSION.json.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string|null} - Active app path or null
+ */
+function getActiveApp(projectRoot) {
+  const session = loadSession(projectRoot);
+  return session.activeApp || null;
+}
+
+// @cap-api getAppRoot(projectRoot) -- Returns the effective root for app-scoped operations.
+// If activeApp is set, returns projectRoot + activeApp. Otherwise returns projectRoot.
+// This is the KEY function for all scoping decisions.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string} - Absolute path to the active app root (or project root if no app)
+ */
+function getAppRoot(projectRoot) {
+  const activeApp = getActiveApp(projectRoot);
+  if (activeApp) {
+    return path.join(projectRoot, activeApp);
+  }
+  return projectRoot;
+}
+
+// @cap-api listApps(projectRoot) -- List available apps/packages in a monorepo using detectWorkspaces.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ isMonorepo: boolean, apps: string[] }}
+ */
+function listApps(projectRoot) {
+  // Lazy require to avoid circular dependency
+  const { detectWorkspaces } = require('./cap-tag-scanner.cjs');
+  const workspaces = detectWorkspaces(projectRoot);
+  return {
+    isMonorepo: workspaces.isMonorepo,
+    apps: workspaces.packages,
+  };
+}
+
+// @cap-feature(feature:F-092, primary:true) Two-Phase Workflow — /cap:quick + /cap:finalize
+// @cap-decision(F-092) Quick-mode state lives in SESSION.json, not in a separate file. Mirrors
+//   how activeFeature, activeApp, etc. live in the existing schema. Single source of truth for
+//   ephemeral workflow state.
+// @cap-decision(F-092/git-snapshot) startCommit captures git HEAD at /cap:quick time. /cap:finalize
+//   diffs against this commit to compute changed-files. This decouples quick-mode lifetime from
+//   commit cadence — Bastian can iterate freely, commit or not, and finalize sees the full set.
+
+const { execSync } = require('node:child_process');
+
+/**
+ * Resolve current git HEAD SHA for the given working directory.
+ * Returns null if not a git repo or git is unavailable — caller treats as "no snapshot, fall back to unstaged-only diff".
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function _getGitHeadSha(cwd) {
+  try {
+    const out = execSync('git rev-parse HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    return String(out).trim() || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+// @cap-api startQuickMode(projectRoot, featureId) -- Enter Phase 1 (Visual Iteration) for a feature.
+// @cap-todo(ac:F-092/AC-1) SESSION.json carries quickMode state with startCommit snapshot.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} featureId - Feature ID being worked on (e.g., "F-Hub-Spotlight-Carousel")
+ * @returns {CapSession}
+ */
+function startQuickMode(projectRoot, featureId) {
+  const startCommit = _getGitHeadSha(projectRoot);
+  return updateSession(projectRoot, {
+    activeFeature: featureId,
+    quickMode: {
+      active: true,
+      feature: featureId,
+      startedAt: new Date().toISOString(),
+      startCommit,
+    },
+  });
+}
+
+// @cap-api endQuickMode(projectRoot) -- Exit Phase 1 — typically called from /cap:finalize after consolidation.
+// @cap-todo(ac:F-092/AC-10) Reset quickMode flag after successful finalize.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {CapSession}
+ */
+function endQuickMode(projectRoot) {
+  return updateSession(projectRoot, {
+    quickMode: {
+      active: false,
+      feature: null,
+      startedAt: null,
+      startCommit: null,
+    },
+  });
+}
+
+// @cap-api isQuickModeActive(projectRoot) -- Check whether the current session is in Phase 1.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean}
+ */
+function isQuickModeActive(projectRoot) {
+  const session = loadSession(projectRoot);
+  return Boolean(session.quickMode && session.quickMode.active === true);
+}
+
+// @cap-api getChangedFilesSinceQuickStart(projectRoot) -- Compute files changed since /cap:quick was entered.
+// @cap-todo(ac:F-092/AC-4) Diff = committed since startCommit + currently unstaged.
+// @cap-decision(F-092) Returns DEDUPLICATED set — a file edited then committed then re-edited shows up once.
+//   Filters to source files (excludes .cap/, node_modules/, dist/, build/, .git/) so finalize doesn't
+//   try to annotate generated artifacts.
+/**
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ files: string[], startCommit: string|null, error?: string }}
+ */
+function getChangedFilesSinceQuickStart(projectRoot) {
+  const session = loadSession(projectRoot);
+  const startCommit = session.quickMode && session.quickMode.startCommit;
+  const set = new Set();
+  const exclude = (p) =>
+    /^\.cap\//.test(p) ||
+    /^node_modules\//.test(p) ||
+    /^dist\//.test(p) ||
+    /^build\//.test(p) ||
+    /^\.git\//.test(p);
+
+  try {
+    if (startCommit) {
+      // Files committed since quick-start (includes renames as both old + new path)
+      const committed = execSync(
+        `git diff --name-only ${startCommit} HEAD`,
+        { cwd: projectRoot, stdio: ['ignore', 'pipe', 'ignore'] }
+      );
+      String(committed).trim().split('\n').filter(Boolean).forEach(f => { if (!exclude(f)) set.add(f); });
+    }
+    // Currently unstaged changes
+    const unstaged = execSync(
+      'git diff --name-only HEAD',
+      { cwd: projectRoot, stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+    String(unstaged).trim().split('\n').filter(Boolean).forEach(f => { if (!exclude(f)) set.add(f); });
+    // Untracked files (newly created in quick-mode)
+    const untracked = execSync(
+      'git ls-files --others --exclude-standard',
+      { cwd: projectRoot, stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+    String(untracked).trim().split('\n').filter(Boolean).forEach(f => { if (!exclude(f)) set.add(f); });
+  } catch (e) {
+    return { files: [], startCommit: startCommit || null, error: String(e && e.message ? e.message : e).trim() };
+  }
+
+  return { files: Array.from(set).sort(), startCommit: startCommit || null };
+}
+
+module.exports = {
+  CAP_DIR,
+  SESSION_FILE,
+  GITIGNORE_CONTENT,
+  loadSession,
+  saveSession,
+  updateSession,
+  getDefaultSession,
+  startSession,
+  updateStep,
+  endSession,
+  isInitialized,
+  initCapDirectory,
+  setActiveApp,
+  getActiveApp,
+  getAppRoot,
+  listApps,
+  // F-092: two-phase workflow
+  startQuickMode,
+  endQuickMode,
+  isQuickModeActive,
+  getChangedFilesSinceQuickStart,
+};