cap-pro 1.0.0

package/cap/bin/lib/security.cjs

@@ -0,0 +1,394 @@
+/**
+ * Security — Input validation, path traversal prevention, and prompt injection guards
+ *
+ * This module centralizes security checks for GSD tooling. Because GSD generates
+ * markdown files that become LLM system prompts (agent instructions, workflow state,
+ * phase plans), any user-controlled text that flows into these files is a potential
+ * indirect prompt injection vector.
+ *
+ * Threat model:
+ *   1. Path traversal: user-supplied file paths escape the project directory
+ *   2. Prompt injection: malicious text in arguments/PRDs embeds LLM instructions
+ *   3. Shell metacharacter injection: user text interpreted by shell
+ *   4. JSON injection: malformed JSON crashes or corrupts state
+ *   5. Regex DoS: crafted input causes catastrophic backtracking
+ */
+'use strict';
+
+// @cap-feature(feature:F-011) Legacy GSD Modules — security: path traversal, prompt injection, shell metachar guards
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Path Traversal Prevention ──────────────────────────────────────────────
+
+/**
+ * Validate that a file path resolves within an allowed base directory.
+ * Prevents path traversal attacks via ../ sequences, symlinks, or absolute paths.
+ *
+ * @param {string} filePath - The user-supplied file path
+ * @param {string} baseDir - The allowed base directory (e.g., project root)
+ * @param {object} [opts] - Options
+ * @param {boolean} [opts.allowAbsolute=false] - Allow absolute paths (still must be within baseDir)
+ * @returns {{ safe: boolean, resolved: string, error?: string }}
+ */
+function validatePath(filePath, baseDir, opts = {}) {
+  if (!filePath || typeof filePath !== 'string') {
+    return { safe: false, resolved: '', error: 'Empty or invalid file path' };
+  }
+
+  if (!baseDir || typeof baseDir !== 'string') {
+    return { safe: false, resolved: '', error: 'Empty or invalid base directory' };
+  }
+
+  // Reject null bytes (can bypass path checks in some environments)
+  if (filePath.includes('\0')) {
+    return { safe: false, resolved: '', error: 'Path contains null bytes' };
+  }
+
+  // Resolve symlinks in base directory to handle macOS /var -> /private/var
+  // and similar platform-specific symlink chains
+  let resolvedBase;
+  try {
+    resolvedBase = fs.realpathSync(path.resolve(baseDir));
+  } catch {
+    resolvedBase = path.resolve(baseDir);
+  }
+
+  let resolvedPath;
+
+  if (path.isAbsolute(filePath)) {
+    if (!opts.allowAbsolute) {
+      return { safe: false, resolved: '', error: 'Absolute paths not allowed' };
+    }
+    resolvedPath = path.resolve(filePath);
+  } else {
+    resolvedPath = path.resolve(baseDir, filePath);
+  }
+
+  // Resolve symlinks in the target path too
+  try {
+    resolvedPath = fs.realpathSync(resolvedPath);
+  } catch {
+    // File may not exist yet (e.g., about to be created) — use logical resolution
+    // but still resolve the parent directory if it exists
+    const parentDir = path.dirname(resolvedPath);
+    try {
+      const realParent = fs.realpathSync(parentDir);
+      resolvedPath = path.join(realParent, path.basename(resolvedPath));
+    } catch {
+      // Parent doesn't exist either — keep the resolved path as-is
+    }
+  }
+
+  // Normalize both paths and check containment
+  const normalizedBase = resolvedBase + path.sep;
+  const normalizedPath = resolvedPath + path.sep;
+
+  // The resolved path must start with the base directory
+  // (or be exactly the base directory)
+  if (resolvedPath !== resolvedBase && !normalizedPath.startsWith(normalizedBase)) {
+    return {
+      safe: false,
+      resolved: resolvedPath,
+      error: `Path escapes allowed directory: ${resolvedPath} is outside ${resolvedBase}`,
+    };
+  }
+
+  return { safe: true, resolved: resolvedPath };
+}
+
+/**
+ * Validate a file path and throw on traversal attempt.
+ * Convenience wrapper around validatePath for use in CLI commands.
+ */
+function requireSafePath(filePath, baseDir, label, opts = {}) {
+  const result = validatePath(filePath, baseDir, opts);
+  if (!result.safe) {
+    throw new Error(`${label || 'Path'} validation failed: ${result.error}`);
+  }
+  return result.resolved;
+}
+
+// ─── Prompt Injection Detection ─────────────────────────────────────────────
+
+/**
+ * Patterns that indicate prompt injection attempts in user-supplied text.
+ * These patterns catch common indirect prompt injection techniques where
+ * an attacker embeds LLM instructions in text that will be read by an agent.
+ *
+ * Note: This is defense-in-depth — not a complete solution. The primary defense
+ * is proper input/output boundaries in agent prompts.
+ *
+ * @cap-decision(security/word-boundaries) Tightened prompt-injection regexes to
+ *   use \b word-boundaries; eliminates false positive on "contract**act** as the
+ *   feature" pattern that surfaced after F-079 shipped.
+ *
+ * Rule: All patterns whose start or end touches a word-character class (a-zA-Z0-9_)
+ * MUST use \b boundaries to avoid substring false-positives (e.g. "contract" +
+ * "act as", "ignored" matching "ignore"). Patterns bounded by non-word characters
+ * such as <, [, > do not need \b because the punctuation itself is a boundary.
+ */
+const INJECTION_PATTERNS = [
+  // Direct instruction override attempts
+  /\bignore\s+(all\s+)?previous\s+instructions\b/i,
+  /\bignore\s+(all\s+)?above\s+instructions\b/i,
+  /\bdisregard\s+(all\s+)?previous\b/i,
+  /\bforget\s+(all\s+)?(your\s+)?instructions\b/i,
+  /\boverride\s+(system|previous)\s+(prompt|instructions)\b/i,
+
+  // Role/identity manipulation
+  /\byou\s+are\s+now\s+(?:a|an|the)\s+/i,
+  /\bact\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,  // allow "act as a plan"
+  /\bpretend\s+(?:you(?:'re| are)\s+|to\s+be\s+)/i,
+  /\bfrom\s+now\s+on,?\s+you\s+(?:are|will|should|must)\b/i,
+
+  // System prompt extraction
+  /\b(?:print|output|reveal|show|display|repeat)\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions)\b/i,
+  /\bwhat\s+(?:are|is)\s+your\s+(?:system\s+)?(?:prompt|instructions)\b/i,
+
+  // Hidden instruction markers (XML/HTML tags that mimic system messages)
+  // Note: <instructions> is excluded — GSD uses it as legitimate prompt structure
+  // Requires > to close the tag (not just whitespace) to avoid matching generic types like Promise<User | null>
+  // These are bounded by non-word punctuation (<, [, >) and don't need \b.
+  /<\/?(?:system|assistant|human)>/i,
+  /\[SYSTEM\]/i,
+  /\[INST\]/i,
+  /<<\s*SYS\s*>>/i,
+
+  // Exfiltration attempts
+  /\b(?:send|post|fetch|curl|wget)\s+(?:to|from)\s+https?:\/\//i,
+  /\b(?:base64|btoa|encode)\s+(?:and\s+)?(?:send|exfiltrate|output)\b/i,
+
+  // Tool manipulation
+  /\b(?:run|execute|call|invoke)\s+(?:the\s+)?(?:bash|shell|exec|spawn)\s+(?:tool|command)\b/i,
+];
+
+/**
+ * Scan text for potential prompt injection patterns.
+ * Returns an array of findings (empty = clean).
+ *
+ * @param {string} text - The text to scan
+ * @param {object} [opts] - Options
+ * @param {boolean} [opts.strict=false] - Enable stricter matching (more false positives)
+ * @returns {{ clean: boolean, findings: string[] }}
+ */
+function scanForInjection(text, opts = {}) {
+  if (!text || typeof text !== 'string') {
+    return { clean: true, findings: [] };
+  }
+
+  const findings = [];
+
+  for (const pattern of INJECTION_PATTERNS) {
+    if (pattern.test(text)) {
+      findings.push(`Matched injection pattern: ${pattern.source}`);
+    }
+  }
+
+  if (opts.strict) {
+    // Check for suspicious Unicode that could hide instructions
+    // (zero-width chars, RTL override, homoglyph attacks)
+    if (/[\u200B-\u200F\u2028-\u202F\uFEFF\u00AD]/.test(text)) {
+      findings.push('Contains suspicious zero-width or invisible Unicode characters');
+    }
+
+    // Check for extremely long strings that could be prompt stuffing
+    if (text.length > 50000) {
+      findings.push(`Suspicious text length: ${text.length} chars (potential prompt stuffing)`);
+    }
+  }
+
+  return { clean: findings.length === 0, findings };
+}
+
+/**
+ * Sanitize text that will be embedded in agent prompts or planning documents.
+ * Strips known injection markers while preserving legitimate content.
+ *
+ * This does NOT alter user intent — it neutralizes control characters and
+ * instruction-mimicking patterns that could hijack agent behavior.
+ *
+ * @param {string} text - Text to sanitize
+ * @returns {string} Sanitized text
+ */
+function sanitizeForPrompt(text) {
+  if (!text || typeof text !== 'string') return text;
+
+  let sanitized = text;
+
+  // Strip zero-width characters that could hide instructions
+  sanitized = sanitized.replace(/[\u200B-\u200F\u2028-\u202F\uFEFF\u00AD]/g, '');
+
+  // Neutralize XML/HTML tags that mimic system boundaries
+  // Replace < > with full-width equivalents to prevent tag interpretation
+  // Note: <instructions> is excluded — GSD uses it as legitimate prompt structure
+  sanitized = sanitized.replace(/<(\/?)(?:system|assistant|human)>/gi,
+    (_, slash) => `＜${slash || ''}system-text＞`);
+
+  // Neutralize [SYSTEM] / [INST] markers
+  sanitized = sanitized.replace(/\[(SYSTEM|INST)\]/gi, '[$1-TEXT]');
+
+  // Neutralize <<SYS>> markers
+  sanitized = sanitized.replace(/<<\s*SYS\s*>>/gi, '«SYS-TEXT»');
+
+  return sanitized;
+}
+
+/**
+ * Sanitize text that will be displayed back to the user.
+ * Removes protocol-like leak markers that should never surface in checkpoints.
+ *
+ * @param {string} text - Text to sanitize
+ * @returns {string} Sanitized text
+ */
+function sanitizeForDisplay(text) {
+  if (!text || typeof text !== 'string') return text;
+
+  let sanitized = sanitizeForPrompt(text);
+
+  const protocolLeakPatterns = [
+    /^\s*(?:assistant|user|system)\s+to=[^:\s]+:[^\n]+$/i,
+    /^\s*<\|(?:assistant|user|system)[^|]*\|>\s*$/i,
+  ];
+
+  sanitized = sanitized
+    .split('\n')
+    .filter(line => !protocolLeakPatterns.some(pattern => pattern.test(line)))
+    .join('\n');
+
+  return sanitized;
+}
+
+// ─── Shell Safety ───────────────────────────────────────────────────────────
+
+/**
+ * Validate that a string is safe to use as a shell argument when quoted.
+ * This is a defense-in-depth check — callers should always use array-based
+ * exec (spawnSync) where possible.
+ *
+ * @param {string} value - The value to check
+ * @param {string} label - Description for error messages
+ * @returns {string} The validated value
+ */
+function validateShellArg(value, label) {
+  if (!value || typeof value !== 'string') {
+    throw new Error(`${label || 'Argument'}: empty or invalid value`);
+  }
+
+  // Reject null bytes
+  if (value.includes('\0')) {
+    throw new Error(`${label || 'Argument'}: contains null bytes`);
+  }
+
+  // Reject command substitution attempts
+  if (/[$`]/.test(value) && /\$\(|`/.test(value)) {
+    throw new Error(`${label || 'Argument'}: contains potential command substitution`);
+  }
+
+  return value;
+}
+
+// ─── JSON Safety ────────────────────────────────────────────────────────────
+
+/**
+ * Safely parse JSON with error handling and optional size limits.
+ * Wraps JSON.parse to prevent uncaught exceptions from malformed input.
+ *
+ * @param {string} text - JSON string to parse
+ * @param {object} [opts] - Options
+ * @param {number} [opts.maxLength=1048576] - Maximum input length (1MB default)
+ * @param {string} [opts.label='JSON'] - Description for error messages
+ * @returns {{ ok: boolean, value?: any, error?: string }}
+ */
+function safeJsonParse(text, opts = {}) {
+  const maxLength = opts.maxLength || 1048576;
+  const label = opts.label || 'JSON';
+
+  if (!text || typeof text !== 'string') {
+    return { ok: false, error: `${label}: empty or invalid input` };
+  }
+
+  if (text.length > maxLength) {
+    return { ok: false, error: `${label}: input exceeds ${maxLength} byte limit (got ${text.length})` };
+  }
+
+  try {
+    const value = JSON.parse(text);
+    return { ok: true, value };
+  } catch (err) {
+    return { ok: false, error: `${label}: parse error — ${err.message}` };
+  }
+}
+
+// ─── Phase/Argument Validation ──────────────────────────────────────────────
+
+/**
+ * Validate a phase number argument.
+ * Phase numbers must match: integer, decimal (2.1), or letter suffix (12A).
+ * Rejects arbitrary strings that could be used for injection.
+ *
+ * @param {string} phase - The phase number to validate
+ * @returns {{ valid: boolean, normalized?: string, error?: string }}
+ */
+function validatePhaseNumber(phase) {
+  if (!phase || typeof phase !== 'string') {
+    return { valid: false, error: 'Phase number is required' };
+  }
+
+  const trimmed = phase.trim();
+
+  // Standard numeric: 1, 01, 12A, 12.1, 12A.1.2
+  if (/^\d{1,4}[A-Z]?(?:\.\d{1,3})*$/i.test(trimmed)) {
+    return { valid: true, normalized: trimmed };
+  }
+
+  // Custom project IDs: PROJ-42, AUTH-101 (uppercase alphanumeric with hyphens)
+  if (/^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+){1,4}$/i.test(trimmed) && trimmed.length <= 30) {
+    return { valid: true, normalized: trimmed };
+  }
+
+  return { valid: false, error: `Invalid phase number format: "${trimmed}"` };
+}
+
+/**
+ * Validate a STATE.md field name to prevent injection into regex patterns.
+ * Field names must be alphanumeric with spaces, hyphens, underscores, or dots.
+ *
+ * @param {string} field - The field name to validate
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validateFieldName(field) {
+  if (!field || typeof field !== 'string') {
+    return { valid: false, error: 'Field name is required' };
+  }
+
+  // Allow typical field names: "Current Phase", "active_plan", "Phase 1.2"
+  if (/^[A-Za-z][A-Za-z0-9 _.\-/]{0,60}$/.test(field)) {
+    return { valid: true };
+  }
+
+  return { valid: false, error: `Invalid field name: "${field}"` };
+}
+
+module.exports = {
+  // Path safety
+  validatePath,
+  requireSafePath,
+
+  // Prompt injection
+  INJECTION_PATTERNS,
+  scanForInjection,
+  sanitizeForPrompt,
+  sanitizeForDisplay,
+
+  // Shell safety
+  validateShellArg,
+
+  // JSON safety
+  safeJsonParse,
+
+  // Input validation
+  validatePhaseNumber,
+  validateFieldName,
+};

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

@@ -0,0 +1,292 @@
+// @cap-context Session manager for monorepo mode -- persists and resolves the current app selection so all GSD commands auto-scope without --app flag
+// @cap-decision Session stored in .planning/SESSION.json -- co-located with planning artifacts, not in a hidden dotfile or temp directory
+// @cap-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path)
+// @cap-pattern All GSD commands call resolveCurrentApp() to get the effective app -- explicit --app flag overrides session, session overrides nothing
+
+'use strict';
+
+// @cap-feature(feature:F-012) Monorepo Support — session manager for persisting current app selection
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} SessionData
+ * @property {string|null} current_app - Relative path to the active app (e.g., 'apps/dashboard'), or null for root/global
+ * @property {string|null} default_app - Default app to auto-select at session start (set via /gsd:switch-app --default)
+ * @property {'monorepo'|'single'|null} workspace_type - Detected workspace type
+ * @property {string[]} available_apps - List of all app paths from workspace detection
+ * @property {number} updated_at - Epoch ms of last update
+ */
+
+// ---------------------------------------------------------------------------
+// File path resolution
+// ---------------------------------------------------------------------------
+
+// @cap-decision SESSION.json lives at root .planning/SESSION.json -- one session file for the whole monorepo, not per-app
+/**
+ * Get the path to SESSION.json.
+ *
+ * @param {string} rootPath - Project/monorepo root
+ * @returns {string}
+ */
+function getSessionPath(rootPath) {
+  return path.join(rootPath, '.planning', 'SESSION.json');
+}
+
+// ---------------------------------------------------------------------------
+// Read operations
+// ---------------------------------------------------------------------------
+
+// @cap-todo(ref:AC-13) Implement session detection at startup: when monorepo detected, present app selector if no session exists
+// @cap-api getSession(rootPath) -- returns SessionData or null if no session file exists
+/**
+ * Read the current session data.
+ *
+ * @param {string} rootPath - Project root
+ * @returns {SessionData|null}
+ */
+function getSession(rootPath) {
+  const sessionPath = getSessionPath(rootPath);
+  try {
+    const raw = fs.readFileSync(sessionPath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// @cap-todo(ref:AC-14) Implement auto-scoping: all GSD commands call resolveCurrentApp() so --app flag is not required after selection
+// @cap-api getCurrentApp(rootPath) -- returns the current app path string or null (global/root scope)
+/**
+ * Get the currently selected app path.
+ * Returns null if no session or if working at root/global scope.
+ *
+ * @param {string} rootPath - Project root
+ * @returns {string|null}
+ */
+function getCurrentApp(rootPath) {
+  const session = getSession(rootPath);
+  if (!session) return null;
+  // If no app explicitly selected but a default is configured, use the default
+  if (!session.current_app && session.default_app) return session.default_app;
+  return session.current_app || null;
+}
+
+// @cap-api resolveCurrentApp(rootPath, explicitApp) -- returns effective app path: explicit --app flag wins, then session, then null
+/**
+ * Resolve the effective current app for a command.
+ * Priority: explicit --app flag > session > null (root scope).
+ *
+ * @param {string} rootPath - Project root
+ * @param {string|null|undefined} explicitApp - Value from --app flag, if provided
+ * @returns {string|null}
+ */
+function resolveCurrentApp(rootPath, explicitApp) {
+  // @cap-decision Explicit --app always wins over session -- escape hatch for one-off commands on a different app
+  if (explicitApp) return explicitApp;
+  return getCurrentApp(rootPath);
+}
+
+// ---------------------------------------------------------------------------
+// Write operations
+// ---------------------------------------------------------------------------
+
+// @cap-todo(ref:AC-15) Wire setCurrentApp to /gsd:switch-app command for mid-session app switching
+// @cap-api setCurrentApp(rootPath, appPath, availableApps) -- writes SESSION.json with new current_app
+/**
+ * Set the current app in the session.
+ * Pass null for appPath to set global/root scope.
+ *
+ * @param {string} rootPath - Project root
+ * @param {string|null} appPath - Relative app path or null for global
+ * @param {string[]} [availableApps] - List of available app paths (updates the cached list)
+ * @returns {SessionData}
+ */
+function setCurrentApp(rootPath, appPath, availableApps) {
+  const existing = getSession(rootPath) || {};
+
+  const session = {
+    current_app: appPath,
+    workspace_type: existing.workspace_type || 'monorepo',
+    available_apps: availableApps || existing.available_apps || [],
+    updated_at: Date.now(),
+  };
+
+  const sessionPath = getSessionPath(rootPath);
+  // Ensure .planning/ exists
+  fs.mkdirSync(path.dirname(sessionPath), { recursive: true });
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n', 'utf-8');
+
+  return session;
+}
+
+// @cap-todo(ref:AC-16) Implement "Global" option: setCurrentApp(rootPath, null) puts session in root-level scope for cross-app work
+// @cap-api clearSession(rootPath) -- removes SESSION.json entirely, resetting to no-session state
+/**
+ * Clear the session entirely. Removes SESSION.json.
+ *
+ * @param {string} rootPath - Project root
+ */
+function clearSession(rootPath) {
+  const sessionPath = getSessionPath(rootPath);
+  try {
+    fs.unlinkSync(sessionPath);
+  } catch {
+    // File doesn't exist -- already cleared
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session initialization (for monorepo startup)
+// ---------------------------------------------------------------------------
+
+// @cap-api initSession(rootPath, workspaceInfo) -- creates initial SESSION.json from workspace detection results
+/**
+ * Initialize a session from workspace detection results.
+ * Called by monorepo-init or at session start when a monorepo is detected.
+ *
+ * @param {string} rootPath - Project root
+ * @param {Object} workspaceInfo - WorkspaceInfo from workspace-detector.cjs
+ * @returns {SessionData}
+ */
+function initSession(rootPath, workspaceInfo) {
+  // @cap-constraint Session init does NOT auto-select an app -- user must explicitly choose via selector or /gsd:switch-app
+  const availableApps = (workspaceInfo.apps || []).map(a => a.path);
+
+  // Check if a default app was previously configured — auto-select it
+  const existing = getSession(rootPath);
+  const defaultApp = (existing && existing.default_app) || null;
+
+  const session = {
+    current_app: defaultApp,
+    default_app: defaultApp,
+    workspace_type: workspaceInfo.type || 'monorepo',
+    available_apps: availableApps,
+    updated_at: Date.now(),
+  };
+
+  const sessionPath = getSessionPath(rootPath);
+  fs.mkdirSync(path.dirname(sessionPath), { recursive: true });
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n', 'utf-8');
+
+  return session;
+}
+
+// ---------------------------------------------------------------------------
+// Default app configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Set a default app that auto-selects at session start.
+ * Pass null to clear the default.
+ *
+ * @param {string} rootPath - Project root
+ * @param {string|null} appPath - Relative app path or null to clear
+ * @returns {SessionData}
+ */
+function setDefaultApp(rootPath, appPath) {
+  const existing = getSession(rootPath) || {};
+
+  const session = {
+    current_app: existing.current_app || appPath,
+    default_app: appPath,
+    workspace_type: existing.workspace_type || 'monorepo',
+    available_apps: existing.available_apps || [],
+    updated_at: Date.now(),
+  };
+
+  const sessionPath = getSessionPath(rootPath);
+  fs.mkdirSync(path.dirname(sessionPath), { recursive: true });
+  fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n', 'utf-8');
+
+  return session;
+}
+
+/**
+ * Get the default app, if configured.
+ *
+ * @param {string} rootPath - Project root
+ * @returns {string|null}
+ */
+function getDefaultApp(rootPath) {
+  const session = getSession(rootPath);
+  return (session && session.default_app) || null;
+}
+
+// ---------------------------------------------------------------------------
+// Query helpers
+// ---------------------------------------------------------------------------
+
+// @cap-api isMonorepoSession(rootPath) -- returns true if a monorepo session is active
+/**
+ * Check if the current session is a monorepo session.
+ *
+ * @param {string} rootPath - Project root
+ * @returns {boolean}
+ */
+function isMonorepoSession(rootPath) {
+  const session = getSession(rootPath);
+  return !!(session && session.workspace_type && session.workspace_type !== 'single');
+}
+
+// @cap-api getAvailableApps(rootPath) -- returns cached list of app paths from session, or empty array
+/**
+ * Get the list of available apps from the session.
+ *
+ * @param {string} rootPath - Project root
+ * @returns {string[]}
+ */
+function getAvailableApps(rootPath) {
+  const session = getSession(rootPath);
+  return (session && session.available_apps) || [];
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format the app selector prompt for display.
+ *
+ * @param {string[]} apps - Available app paths
+ * @param {string|null} currentApp - Currently selected app
+ * @returns {string}
+ */
+function formatAppSelector(apps, currentApp) {
+  const lines = ['Which app do you want to work on?\n'];
+
+  for (let i = 0; i < apps.length; i++) {
+    const marker = apps[i] === currentApp ? ' (current)' : '';
+    lines.push(`  ${i + 1}. ${apps[i]}${marker}`);
+  }
+
+  const globalMarker = currentApp === null ? ' (current)' : '';
+  lines.push(`  ${apps.length + 1}. [Global] -- root-level cross-app work${globalMarker}`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  getSessionPath,
+  getSession,
+  getCurrentApp,
+  resolveCurrentApp,
+  setCurrentApp,
+  setDefaultApp,
+  getDefaultApp,
+  clearSession,
+  initSession,
+  isMonorepoSession,
+  getAvailableApps,
+  formatAppSelector,
+};