peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/playwright-session-store.d.ts

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+export declare const DEFAULT_PORT = 8931;
+export declare const MAX_PORT = 8949;
+/** The lowest TCP port the `--port` flag accepts. */
+export declare const MIN_PORT = 1024;
+/** The highest TCP port the `--port` flag accepts. */
+export declare const MAX_TCP_PORT = 65535;
+export declare const BROWSERS: readonly ["chromium", "firefox", "webkit"];
+export type Browser = (typeof BROWSERS)[number];
+export interface PlaywrightSession {
+    terminalId: string;
+    port: number;
+    browser: Browser;
+    userDataDir: string;
+    startedAt: string;
+    pid?: number;
+}
+export declare const PLAYWRIGHT_SESSIONS_DIR = "playwright-sessions";
+export declare function playwrightSessionsDir(projectRoot: string): string;
+export declare function sessionFilePath(projectRoot: string, terminalId: string): string;
+/**
+ * The per-terminal default `--user-data-dir` under the runtime tree. Guarded here,
+ * beside the join, for the same reason `sessionFilePath` above is: rule D keys the
+ * guard to the FILE, and the caller (`peaks playwright start`) reaches this only
+ * through `readSession` — so a guard that leaned on that call order would be the
+ * file-scoped hole the rule exists to keep visible.
+ */
+export declare function defaultUserDataDir(projectRoot: string, terminalId: string): string;
+/**
+ * Derive a stable terminal id from the process environment. Prefers
+ * the platform's own terminal-session id (macOS Terminal, Windows
+ * Terminal) and falls back to a hash of (ppid, tty).
+ */
+export declare function deriveTerminalId(env?: NodeJS.ProcessEnv, ppid?: number): string;
+/**
+ * Walk port range starting at `start` and return the first port
+ * that is NOT bound. Defaults: 8931 → 8949. If the range is exhausted,
+ * returns null.
+ */
+export declare function findFreePort(start?: number, max?: number, probe?: (port: number) => Promise<boolean>): Promise<number | null>;
+export declare function listSessions(projectRoot: string): PlaywrightSession[];
+export declare function readSession(projectRoot: string, terminalId: string): PlaywrightSession | null;
+export declare function writeSession(projectRoot: string, session: PlaywrightSession): void;
+export declare function removeSession(projectRoot: string, terminalId: string): boolean;
+/**
+ * Spawn the playwright MCP via npx. We do NOT bundle the binary;
+ * we just orchestrate the lifecycle. Returns the child PID so the
+ * session file can record it.
+ */
+export declare function spawnPlaywrightMcp(port: number, browser: Browser, userDataDir: string, projectRoot: string): {
+    pid: number | undefined;
+    child: ReturnType<typeof spawn>;
+};
+/**
+ * Resolve and validate a caller-supplied `--user-data-dir`. The dir must
+ * live under `projectRoot` so a malicious `--user-data-dir /etc/foo`
+ * cannot coerce the playwright-mcp browser into writing state to an
+ *
+ * Resolves `..` segments before checking, so a path like
+ * `<projectRoot>/../escape` is correctly normalized and rejected.
+ *
+ * Throws `Error('INVALID_USER_DATA_DIR: ...')` on validation failure;
+ * the action handler catches and emits the JSON envelope.
+ */
+export declare function resolveUserDataDir(raw: string, projectRoot: string): string;

package/dist/cli/commands/playwright-session-store.js

@@ -0,0 +1,189 @@
+// src/cli/commands/playwright-session-store.ts
+//
+// The Playwright MCP session store: port range, terminal-id derivation, the
+// session-record file layout, the port probe and the process spawn. Split out
+// of `playwright-commands.ts`, which re-exports every symbol below so its
+// public surface is unchanged.
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import net from 'node:net';
+import { join, dirname, resolve } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+export const DEFAULT_PORT = 8931;
+export const MAX_PORT = 8949;
+/** The lowest TCP port the `--port` flag accepts. */
+export const MIN_PORT = 1024;
+/** The highest TCP port the `--port` flag accepts. */
+export const MAX_TCP_PORT = 65535;
+/** Hex characters kept from the sha256 of (ppid, tty) when deriving a terminal id. */
+const TERMINAL_HASH_CHARS = 16;
+/** Longest id `sanitizeTerminalId` will emit. */
+const TERMINAL_ID_MAX_CHARS = 64;
+export const BROWSERS = ['chromium', 'firefox', 'webkit'];
+export const PLAYWRIGHT_SESSIONS_DIR = 'playwright-sessions';
+export function playwrightSessionsDir(projectRoot) {
+    return join(projectRoot, '.peaks', '_runtime', PLAYWRIGHT_SESSIONS_DIR);
+}
+export function sessionFilePath(projectRoot, terminalId) {
+    // Terminal-id axis. The derived id is already sanitised (`deriveTerminalId`),
+    // but `--terminal` is caller-supplied and reaches this join unsanitised.
+    // Measured (repair cycle 1, item 1): `playwright stop --terminal ../../../../X`
+    // read a session record planted OUTSIDE the project root, sent SIGTERM to the
+    // pid it named, unlinked that file, and returned `ok: true` — arbitrary
+    // process termination plus an arbitrary file delete, one flag away. This is
+    // the join every reader/writer of a session record goes through, so this is
+    // where the invariant lives.
+    if (isUnsafePathInput(terminalId)) {
+        throw new Error(`Invalid terminal id: ${terminalId} (must be a single path segment)`);
+    }
+    return join(playwrightSessionsDir(projectRoot), `${terminalId}.json`);
+}
+/**
+ * The per-terminal default `--user-data-dir` under the runtime tree. Guarded here,
+ * beside the join, for the same reason `sessionFilePath` above is: rule D keys the
+ * guard to the FILE, and the caller (`peaks playwright start`) reaches this only
+ * through `readSession` — so a guard that leaned on that call order would be the
+ * file-scoped hole the rule exists to keep visible.
+ */
+export function defaultUserDataDir(projectRoot, terminalId) {
+    if (isUnsafePathInput(terminalId)) {
+        throw new Error(`Invalid terminal id: ${terminalId} (must be a single path segment)`);
+    }
+    return join(projectRoot, '.peaks', '_runtime', 'playwright-userdata', terminalId);
+}
+/**
+ * Derive a stable terminal id from the process environment. Prefers
+ * the platform's own terminal-session id (macOS Terminal, Windows
+ * Terminal) and falls back to a hash of (ppid, tty).
+ */
+export function deriveTerminalId(env = process.env, ppid = process.ppid) {
+    const termSession = env.TERM_SESSION_ID;
+    if (termSession && termSession.length > 0) {
+        return sanitizeTerminalId(termSession);
+    }
+    const wtSession = env.WT_SESSION;
+    if (wtSession && wtSession.length > 0) {
+        return sanitizeTerminalId(`wt-${wtSession}`);
+    }
+    const tty = env.SSH_TTY ?? 'no-tty';
+    const hash = createHash('sha256')
+        .update(`${ppid}-${tty}`)
+        .digest('hex')
+        .slice(0, TERMINAL_HASH_CHARS);
+    return `tty-${hash}`;
+}
+function sanitizeTerminalId(raw) {
+    return raw.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, TERMINAL_ID_MAX_CHARS);
+}
+/**
+ * Walk port range starting at `start` and return the first port
+ * that is NOT bound. Defaults: 8931 → 8949. If the range is exhausted,
+ * returns null.
+ */
+export async function findFreePort(start = DEFAULT_PORT, max = MAX_PORT, probe = defaultPortProbe) {
+    for (let p = start; p <= max; p += 1) {
+        if (await probe(p))
+            return p;
+    }
+    return null;
+}
+async function defaultPortProbe(port) {
+    return new Promise((resolveProbe) => {
+        const server = net.createServer();
+        server.once('error', () => resolveProbe(false));
+        server.once('listening', () => {
+            server.close(() => resolveProbe(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+export function listSessions(projectRoot) {
+    const dir = playwrightSessionsDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const raw = readFileSync(join(dir, entry), 'utf8');
+            const session = JSON.parse(raw);
+            out.push(session);
+        }
+        catch {
+            // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip malformed session file
+        }
+    }
+    return out;
+}
+export function readSession(projectRoot, terminalId) {
+    const path = sessionFilePath(projectRoot, terminalId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function writeSession(projectRoot, session) {
+    const path = sessionFilePath(projectRoot, session.terminalId);
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(session, null, 2) + '\n', 'utf8');
+}
+export function removeSession(projectRoot, terminalId) {
+    const path = sessionFilePath(projectRoot, terminalId);
+    if (!existsSync(path))
+        return false;
+    unlinkSync(path);
+    return true;
+}
+/**
+ * Spawn the playwright MCP via npx. We do NOT bundle the binary;
+ * we just orchestrate the lifecycle. Returns the child PID so the
+ * session file can record it.
+ */
+export function spawnPlaywrightMcp(port, browser, userDataDir, projectRoot) {
+    const child = spawn('npx', [
+        'playwright-mcp@latest',
+        `--port=${port}`,
+        `--browser=${browser}`,
+        `--user-data-dir=${userDataDir}`
+    ], {
+        cwd: projectRoot,
+        env: process.env,
+        stdio: 'ignore',
+        detached: true,
+        windowsHide: true
+    });
+    return { pid: child.pid, child };
+}
+/**
+ * Resolve and validate a caller-supplied `--user-data-dir`. The dir must
+ * live under `projectRoot` so a malicious `--user-data-dir /etc/foo`
+ * cannot coerce the playwright-mcp browser into writing state to an
+ *
+ * Resolves `..` segments before checking, so a path like
+ * `<projectRoot>/../escape` is correctly normalized and rejected.
+ *
+ * Throws `Error('INVALID_USER_DATA_DIR: ...')` on validation failure;
+ * the action handler catches and emits the JSON envelope.
+ */
+export function resolveUserDataDir(raw, projectRoot) {
+    const resolved = resolve(projectRoot, raw);
+    const rootResolved = resolve(projectRoot) + (projectRoot.endsWith('/') || projectRoot.endsWith('\\') ? '' : '/');
+    // Use the projectRoot + sep as the prefix; require either an exact
+    // match or a child path. The `+ '/'` guard prevents sibling-prefix
+    // collisions (e.g. /home/A/proj2 passes the check for /home/A/proj).
+    if (resolved !== resolve(projectRoot) && !resolved.startsWith(rootResolved)) {
+        throw new Error(`INVALID_USER_DATA_DIR: --user-data-dir must resolve to a path under project root ${projectRoot} (got ${resolved})`);
+    }
+    return resolved;
+}

package/dist/cli/commands/project-commands.d.ts

@@ -1,3 +1,22 @@
+/**
+ * `peaks project *` — aggregate Peaks state for a target project (read-only).
+ *
+ * The umbrella verb plus the two memory verbs whose envelopes are pinned by
+ * source-scanning tests, which is why they stay in this file rather than moving
+ * to a sibling module beside the others:
+ *
+ *   - `tests/unit/services/memory/memory-kind-llm-surfaces.test.ts` requires the
+ *     literal `VALID_PROJECT_MEMORY_KINDS` here (the `--kind` help must stay
+ *     derived, never hand-maintained);
+ *   - `tests/unit/services/memory/memory-block-drop-diagnostics.test.ts` requires
+ *     the literal `describeMemoryBlockDrops(result.droppedBlocks)` here (the
+ *     drops must reach the `ok(..., warnings)` channel).
+ *
+ * The rest live one module per verb:
+ * `project-dashboard-command.ts`, `project-context-command.ts`,
+ * `project-memory-index-command.ts`, `project-memories-show-command.ts`,
+ * `project-knowledge-command.ts`.
+ */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerProjectCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/project-commands.js

@@ -1,96 +1,104 @@
-import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
-import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
-import { describeMemoryBlockDrops, describeSessionScanFailures, extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody, VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
-import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
-import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
-import { formatMdCompact } from '../../shared/format-md-compact.js';
+/**
+ * `peaks project *` — aggregate Peaks state for a target project (read-only).
+ *
+ * The umbrella verb plus the two memory verbs whose envelopes are pinned by
+ * source-scanning tests, which is why they stay in this file rather than moving
+ * to a sibling module beside the others:
+ *
+ *   - `tests/unit/services/memory/memory-kind-llm-surfaces.test.ts` requires the
+ *     literal `VALID_PROJECT_MEMORY_KINDS` here (the `--kind` help must stay
+ *     derived, never hand-maintained);
+ *   - `tests/unit/services/memory/memory-block-drop-diagnostics.test.ts` requires
+ *     the literal `describeMemoryBlockDrops(result.droppedBlocks)` here (the
+ *     drops must reach the `ok(..., warnings)` channel).
+ *
+ * The rest live one module per verb:
+ * `project-dashboard-command.ts`, `project-context-command.ts`,
+ * `project-memory-index-command.ts`, `project-memories-show-command.ts`,
+ * `project-knowledge-command.ts`.
+ */
+import { describeMemoryBlockDrops, describeSessionScanFailures, extractSessionMemories, readProjectMemories, VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { registerProjectDashboardCommand } from './project-dashboard-command.js';
+import { registerProjectContextCommand } from './project-context-command.js';
+import { registerProjectKnowledgeCommand } from './project-knowledge-command.js';
+import { registerProjectMemoriesShowCommand } from './project-memories-show-command.js';
+import { registerProjectMemoryIndexCommand } from './project-memory-index-command.js';
 /** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
 const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
+/** The `ok` payload for `memories:extract` — the counts the caller acts on. */
+function extractData(result) {
+    return {
+        scannedFiles: result.scannedFiles,
+        extractedCount: result.extractedCount,
+        writtenFiles: result.writtenFiles,
+        memoryDir: result.primaryMemoryDir,
+        indexUpdated: result.updatedIndex
+    };
+}
+/**
+ * Two drop axes, one channel. `droppedBlocks` = a block was found and rejected
+ * (or a marker-shaped comment was not findable at all); `scanFailures` = the
+ * whole artifact could not be read, so its blocks were never candidates.
+ * `data` is unchanged by either — same contract as `memory.extract`.
+ */
+function extractWarnings(result) {
+    return [
+        ...describeMemoryBlockDrops(result.droppedBlocks),
+        ...describeSessionScanFailures(result.scanFailures)
+    ];
+}
+function runProjectMemories(io, options) {
+    try {
+        const result = readProjectMemories(options.project);
+        if (options.kind) {
+            const memories = result.memories.filter((memory) => memory.kind === options.kind);
+            printResult(io, ok('project.memories', {
+                memoryDir: result.memoryDir,
+                kind: options.kind,
+                total: memories.length,
+                memories
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('project.memories', {
+            memoryDir: result.memoryDir,
+            total: result.total,
+            byKind: result.byKind,
+            memories: result.memories
+        }), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.memories', 'PROJECT_MEMORIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+function runMemoriesExtract(io, options) {
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('project.memories:extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', { sessionId: options.sessionId, projectRoot: options.project }, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const result = extractSessionMemories({
+            projectRoot: options.project,
+            sessionId: options.sessionId,
+            apply: options.apply === true
+        });
+        printResult(io, ok('project.memories:extract', extractData(result), extractWarnings(result)), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
+        process.exitCode = 1;
+    }
+}
 export function registerProjectCommands(program, io) {
     const project = program
         .command('project')
         .description('Aggregate Peaks state for a target project (read-only)');
-    addJsonOption(project
-        .command('dashboard')
-        .description('One-call snapshot of doctor / MCP / OpenSpec / requests / capabilities for a project')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--strict', 'ok follows the doctor aggregate (legacy semantics). Default: workspace-only (ok tracks the runbook health)', false)).action(async (options) => {
-        try {
-            const dashboard = await loadProjectDashboard({
-                projectRoot: options.project,
-                okPolicy: options.strict === true ? 'strict' : 'workspace-only'
-            });
-            if (!dashboard.runbookHealth.ok) {
-                const suggestions = [
-                    dashboard.runbookHealth.missingRunbook.length > 0
-                        ? `Add a ## Default runbook section to: ${dashboard.runbookHealth.missingRunbook.join(', ')}`
-                        : null,
-                    dashboard.runbookHealth.applyNoteFailed.length > 0
-                        ? `Add authorization/--dry-run notes next to destructive --apply lines in: ${dashboard.runbookHealth.applyNoteFailed.join(', ')}`
-                        : null
-                ].filter((line) => line !== null);
-                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_RUNBOOK_UNHEALTHY', `Skill runbook health failing: ${dashboard.runbookHealth.healthy}/${dashboard.runbookHealth.required} healthy`, dashboard, suggestions), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (dashboard.skillPresence.active && !dashboard.skillPresence.fresh) {
-                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_STALE_SKILL_PRESENCE', `Active Peaks skill presence ${dashboard.skillPresence.skill ?? '<unknown>'} is stale (set ${dashboard.skillPresence.setAt ?? '<unknown>'})`, dashboard, [
-                    'Run `peaks skill presence:clear` if the role has ended, or `peaks skill presence:set <skill>` to refresh it'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (!dashboard.doctor.ok && options.strict === true) {
-                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_DOCTOR_STRICT_FAIL', `Doctor reports ${dashboard.doctor.failed} failed check(s) (${dashboard.doctor.passed} passed) — --strict mode requires the doctor aggregate to pass`, dashboard, [
-                    'Run `peaks doctor --json` and resolve the failing checks, or drop --strict to use the workspace-only policy'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, ok('project.dashboard', dashboard), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(project
-        .command('context')
-        .description('Generate or read persistent project context for cross-session Peaks understanding. Generates BOTH `.peaks/PROJECT.md` (session history) AND `.peaks/project-scan/project-scan.md` (tech stack + archetypes) — see `peaks workspace init` for the full 5-template boot (G4b/AC9).')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--read', 'read existing PROJECT.md without regenerating')).action(async (options) => {
-        try {
-            if (options.read) {
-                const content = readProjectContext(options.project);
-                if (content === null) {
-                    printResult(io, ok('project.context', { exists: false, path: `${options.project}/.peaks/PROJECT.md` }), options.json);
-                    return;
-                }
-                printResult(io, ok('project.context', {
-                    exists: true,
-                    path: `${options.project}/.peaks/PROJECT.md`,
-                    content
-                }), options.json);
-                return;
-            }
-            const result = await generateProjectContext(options.project);
-            printResult(io, ok('project.context', {
-                path: result.path,
-                sessionCount: result.sessionCount,
-                content: result.content,
-                // context command also bootstraps the project-scan tree.
-                // The envelope surfaces write counts + duration so the LLM
-                // (and the user) see what landed.
-                projectScan: result.projectScan
-            }), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.context', 'PROJECT_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks directory']), options.json);
-            process.exitCode = 1;
-        }
-    });
+    registerProjectDashboardCommand(project, io);
+    registerProjectContextCommand(project, io);
     // --- Extract memories from a session's artifacts into .peaks/memory ---
     addJsonOption(project
         .command('memories:extract')
@@ -104,183 +112,14 @@ export function registerProjectCommands(program, io) {
         // opt-in; the mutual-exclusion check below is correct without a
         // special-case.
         .option('--dry-run', 'preview writes without changing files')
-        .option('--apply', 'write extracted memories into .peaks/memory/')).action((options) => {
-        if (options.dryRun === true && options.apply === true) {
-            printResult(io, fail('project.memories:extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', { sessionId: options.sessionId, projectRoot: options.project }, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const result = extractSessionMemories({
-                projectRoot: options.project,
-                sessionId: options.sessionId,
-                apply: options.apply === true
-            });
-            printResult(io, ok('project.memories:extract', {
-                scannedFiles: result.scannedFiles,
-                extractedCount: result.extractedCount,
-                writtenFiles: result.writtenFiles,
-                memoryDir: result.primaryMemoryDir,
-                indexUpdated: result.updatedIndex
-            }, [
-                // Two drop axes, one channel. `droppedBlocks` = a block was found and
-                // rejected (or a marker-shaped comment was not findable at all);
-                // `scanFailures` = the whole artifact could not be read, so its blocks
-                // were never candidates. `data` is unchanged by either — same contract
-                // as `memory.extract`.
-                ...describeMemoryBlockDrops(result.droppedBlocks),
-                ...describeSessionScanFailures(result.scanFailures)
-            ]), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // --- Read memory index (lightweight, always-safe to load) ---
-    addJsonOption(project
-        .command('memory-index')
-        .description('Read the memory index — lightweight hot/warm分层 view of all project memories')
-        .requiredOption('--project <path>', 'target project root')).action((options) => {
-        try {
-            const index = readMemoryIndex(options.project);
-            if (!index) {
-                printResult(io, ok('project.memory-index', {
-                    exists: false,
-                    message: 'No memory index found. Run `peaks project memories:extract` first.'
-                }), options.json);
-                return;
-            }
-            printResult(io, ok('project.memory-index', { exists: true, index }), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.memory-index', 'MEMORY_INDEX_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
-            process.exitCode = 1;
-        }
-    });
+        .option('--apply', 'write extracted memories into .peaks/memory/')).action((options) => runMemoriesExtract(io, options));
+    registerProjectMemoryIndexCommand(project, io);
     // --- Structured project memory (durable, LLM-authored, stored under .peaks/memory) ---
     addJsonOption(project
         .command('memories')
         .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
         .requiredOption('--project <path>', 'target project root')
-        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)).action((options) => {
-        try {
-            const result = readProjectMemories(options.project);
-            if (options.kind) {
-                const memories = result.memories.filter((memory) => memory.kind === options.kind);
-                printResult(io, ok('project.memories', {
-                    memoryDir: result.memoryDir,
-                    kind: options.kind,
-                    total: memories.length,
-                    memories
-                }), options.json);
-                return;
-            }
-            printResult(io, ok('project.memories', {
-                memoryDir: result.memoryDir,
-                total: result.total,
-                byKind: result.byKind,
-                memories: result.memories
-            }), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.memories', 'PROJECT_MEMORIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // --- Show one project memory's body (R3: default = compact) ---
-    addJsonOption(project
-        .command('memories:show <name>')
-        .description('Show one project memory body by name. Default format is `compact` (LLM-primary); pass --pretty for the disk verbatim. Stale entries (default ≥30 days) are excluded; pass --include-stale or --stale-days <N> to override.')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--pretty', 'return the on-disk body verbatim; overrides the compact default')
-        .option('--include-stale', 'include stale entries (the default excludes them)')
-        .option('--stale-days <n>', 'override the 30-day stale threshold (must be > 0)', (value) => Number(value))).action((name, options) => {
-        try {
-            const memory = readProjectMemoryBody(options.project, name);
-            if (memory === null) {
-                printResult(io, fail('project.memories:show', 'MEMORY_NOT_FOUND', `memory ${name} not found in .peaks/memory`, { name, projectRoot: options.project }, ['Run `peaks project memories --json` to see available names']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            // Compute the stale decision. R4: stale is computed at CLI load time
-            // only; the source `.md` file is never modified.
-            const updatedAt = memory.updatedAt;
-            const thresholdDays = options.staleDays !== undefined &&
-                Number.isFinite(options.staleDays) &&
-                options.staleDays > 0
-                ? options.staleDays
-                : DEFAULT_STALE_DAYS;
-            const policy = applyStalePolicy([{ name: memory.name, updatedAt }], {
-                thresholdDays,
-                includeStale: options.includeStale === true
-            });
-            if (policy.entries.length === 0) {
-                const ageDays = policy.entries.length === 0 && policy.droppedCount > 0
-                    ? (applyStalePolicy([{ name: memory.name, updatedAt }], {
-                        thresholdDays,
-                        includeStale: true
-                    }).entries[0]?.ageDays ?? 0)
-                    : 0;
-                printResult(io, fail('project.memories:show', 'MEMORY_STALE', `memory ${name} is stale (age ${ageDays} days > ${thresholdDays} day threshold); pass --include-stale to override`, { name, ageDays, thresholdDays }, [
-                    'Pass --include-stale to load stale memories; pass --stale-days <N> to override the threshold'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const ageDays = policy.entries[0]?.ageDays ?? 0;
-            const isStale = policy.entries[0]?.stale ?? false;
-            const format = options.pretty === true ? 'pretty' : 'compact';
-            const body = format === 'pretty' ? memory.body : formatMdCompact(memory.body);
-            printResult(io, ok('project.memories:show', {
-                name: memory.name,
-                title: memory.title,
-                kind: memory.kind,
-                sourcePath: memory.filePath,
-                updatedAt,
-                ageDays,
-                stale: isStale,
-                body,
-                format,
-                bodyBytes: Buffer.byteLength(body, 'utf8')
-            }), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.memories:show', 'PROJECT_MEMORY_SHOW_FAILED', getErrorMessage(error), { name, projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    // --- Read business-knowledge sediment (v2.11.0 Group B — D3) ---
-    addJsonOption(project
-        .command('knowledge')
-        .description('Read .peaks/project-scan/business-knowledge.md (the schema-sedimented concept table). LLM-consumable; use --filter for a concept substring.')
-        .requiredOption('--project <path>', 'target project root')
-        .option('--filter <glob>', 'substring filter on the concept name (case-insensitive)')).action(async (options) => {
-        try {
-            const knowledge = await readBusinessKnowledge(options.project);
-            if (knowledge === null) {
-                printResult(io, ok('project.knowledge', {
-                    exists: false,
-                    projectRoot: options.project,
-                    path: `${options.project}/.peaks/project-scan/business-knowledge.md`
-                }), options.json);
-                return;
-            }
-            const concepts = options.filter
-                ? knowledge.concepts.filter((c) => c.concept.toLowerCase().includes(options.filter.toLowerCase()))
-                : knowledge.concepts;
-            printResult(io, ok('project.knowledge', {
-                exists: true,
-                schemaVersion: knowledge.schemaVersion,
-                total: knowledge.concepts.length,
-                matched: concepts.length,
-                filter: options.filter ?? null,
-                concepts
-            }), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('project.knowledge', 'PROJECT_KNOWLEDGE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/project-scan directory']), options.json);
-            process.exitCode = 1;
-        }
-    });
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)).action((options) => runProjectMemories(io, options));
+    registerProjectMemoriesShowCommand(project, io);
+    registerProjectKnowledgeCommand(project, io);
 }

package/dist/cli/commands/project-context-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerProjectContextCommand(project: Command, io: ProgramIO): void;