peaks-cli 1.2.3 → 1.2.5

package/dist/src/cli/commands/openspec-commands.js

@@ -4,6 +4,7 @@ import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridg
 import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
 import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
 import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
+import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function resolveScanOptions(project) {
@@ -166,4 +167,34 @@ export function registerOpenSpecCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(openspec
+        .command('init')
+        .description('Scaffold the openspec/ directory in the target project (changes/, archive/, README.md, CHANGES.md). Idempotent — refuses to overwrite an existing openspec/')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'write files to disk (default: dry-run preview)', false)).action(async (options) => {
+        try {
+            const result = await executeOpenSpecInit({
+                projectRoot: options.project,
+                apply: options.apply === true
+            });
+            const nextActions = [];
+            if (result.alreadyInitialized) {
+                nextActions.push('openspec/ already exists; no files were created or modified.');
+                if (result.existingFiles.length > 0) {
+                    nextActions.push(`Existing files preserved: ${result.existingFiles.join(', ')}`);
+                }
+            }
+            else if (!result.apply) {
+                nextActions.push('Re-run with --apply to write the planned files to disk.');
+            }
+            else {
+                nextActions.push('Run `peaks openspec render --request <path> --apply` to scaffold a first change proposal.');
+            }
+            printResult(io, ok('openspec.init', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.init', 'OPENSPEC_INIT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -1,6 +1,6 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
 import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
-import { readProjectMemories } from '../../services/memory/project-memory-service.js';
+import { extractSessionMemories, readMemoryIndex, readProjectMemories } from '../../services/memory/project-memory-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerProjectCommands(program, io) {
@@ -68,6 +68,56 @@ export function registerProjectCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // --- Extract memories from a session's artifacts into .peaks/memory ---
+    addJsonOption(project
+        .command('memories:extract')
+        .description('Scan a session artifact directory and extract <!-- peaks-memory:start --> blocks into .peaks/memory/')
+        .requiredOption('--session-id <id>', 'session id (e.g. 2026-05-29-session-89ff35)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--dry-run', 'preview writes without changing files', true)
+        .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
+            }), 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;
+        }
+    });
     // --- Structured project memory (durable, LLM-authored, stored under .peaks/memory) ---
     addJsonOption(project
         .command('memories')

package/dist/src/cli/commands/sop-commands.js

@@ -105,8 +105,8 @@ export function registerSopCommands(program, io) {
     });
     addJsonOption(sop
         .command('registry')
-        .description('List registered SOPs and gates (global; --project merges in the repo layer)')
-        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops)')).action(async (options) => {
+        .description('List registered SOPs and gates (global; merges in the cwd project layer by default)')
+        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops) (default: current directory)', '.')).action(async (options) => {
         try {
             const registry = await readRegistry(options.project);
             printResult(io, ok('sop.registry', registry), options.json);

package/dist/src/cli/commands/workspace-commands.js

@@ -1,16 +1,39 @@
-import { initWorkspace, InvalidSessionIdError } from '../../services/workspace/workspace-service.js';
+import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
+import { ensureSession } from '../../services/session/session-manager.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerWorkspaceCommands(program, io) {
     const workspace = program.command('workspace').description('Manage the Peaks per-session artifact workspace (.peaks/<session-id>/)');
     addJsonOption(workspace
         .command('init')
-        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) — validates the session id format')
+        .description('Create the .peaks/<session-id>/ directory structure (prd, ui, rd, qa, sc, txt, system) and bind the session as the project current one. Pass --session-id to use a specific id, or omit it to auto-generate one (and adopt an existing binding if present).')
         .requiredOption('--project <path>', 'target project root')
-        .requiredOption('--session-id <id>', 'session id in YYYY-MM-DD-<kebab-slug> format')).action(async (options) => {
+        .option('--session-id <id>', 'optional session id in YYYY-MM-DD-<kebab-slug> format. When omitted, the CLI is the single source of truth: an existing binding is reused, otherwise a fresh id is auto-generated.')
+        .option('--allow-session-rebind', 'overwrite an existing session binding when the requested session id differs from the project current one', false)).action(async (options) => {
         try {
-            const report = await initWorkspace({ projectRoot: options.project, sessionId: options.sessionId });
+            // Resolve the session id. Two paths:
+            //   - explicit --session-id: use it as the requested binding target
+            //     (ConflictingSessionError fires if it conflicts with an in-flight
+            //     session, unless --allow-session-rebind is set)
+            //   - omitted: defer to ensureSession(), which reuses an existing
+            //     binding or auto-generates a fresh one. The init then writes
+            //     .session.json so the binding sticks.
+            let sessionId;
+            if (options.sessionId !== undefined && options.sessionId.length > 0) {
+                sessionId = options.sessionId;
+            }
+            else {
+                sessionId = await ensureSession(options.project);
+            }
+            const report = await initWorkspace({
+                projectRoot: options.project,
+                sessionId,
+                allowSessionRebind: options.allowSessionRebind === true
+            });
             const nextActions = [];
+            if (report.previousSessionId !== null && report.bound) {
+                nextActions.push(`Replaced prior session binding "${report.previousSessionId}" with "${report.sessionId}".`);
+            }
             if (report.created.length === 0) {
                 nextActions.push('Workspace already initialized — proceed to project scan.');
             }
@@ -25,6 +48,17 @@ export function registerWorkspaceCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
+            if (error instanceof ConflictingSessionError) {
+                printResult(io, fail('workspace.init', error.code, error.message, {
+                    existingSessionId: error.existingSessionId,
+                    requestedSessionId: error.requestedSessionId
+                }, [
+                    `Finish or abandon session "${error.existingSessionId}" first, then re-run workspace init.`,
+                    'Or pass --allow-session-rebind to override the binding (overwrites the prior binding).'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
             printResult(io, fail('workspace.init', 'WORKSPACE_INIT_FAILED', getErrorMessage(error), { projectRoot: options.project, sessionId: options.sessionId }, ['Verify the project path exists and is writable']), options.json);
             process.exitCode = 1;
         }

package/dist/src/services/memory/project-memory-service.d.ts

@@ -74,6 +74,36 @@ export type ProjectMemoryReadResult = {
     byKind: Record<ProjectMemoryKind, StoredProjectMemory[]>;
     memories: StoredProjectMemory[];
 };
+export type MemoryIndexEntry = {
+    name: string;
+    kind: ProjectMemoryKind;
+    description: string;
+    sourcePath: string;
+    sourceArtifact: string | null;
+    updatedAt: string;
+};
+export type MemoryIndex = {
+    version: 1;
+    updatedAt: string;
+    hot: Record<ProjectMemoryKind, MemoryIndexEntry[]>;
+    warm: Record<ProjectMemoryKind, MemoryIndexEntry[]>;
+};
+export type ExtractSessionMemoriesOptions = {
+    projectRoot: string;
+    sessionId: string;
+    apply?: boolean;
+};
+export type ExtractSessionMemoriesResult = {
+    apply: boolean;
+    projectRoot: string;
+    sessionId: string;
+    primaryMemoryDir: string;
+    memoryIndexPath: string;
+    scannedFiles: number;
+    extractedCount: number;
+    writtenFiles: string[];
+    updatedIndex: boolean;
+};
 type ExtractPlanOptions = {
     projectRoot: string;
     artifactPaths: string[];
@@ -84,6 +114,8 @@ type BackupPlanOptions = {
     artifactWorkspacePath: string;
     apply?: boolean;
 };
+export declare function readMemoryIndex(projectRoot: string): MemoryIndex | null;
+export declare function extractSessionMemories(options: ExtractSessionMemoriesOptions): ExtractSessionMemoriesResult;
 export declare function extractStableProjectMemories(content: string, sourceArtifact: string): ExtractedProjectMemory[];
 export declare function createProjectMemoryExtractPlan(options: ExtractPlanOptions): ProjectMemoryExtractPlan;
 export declare function executeProjectMemoryExtract(options: ExtractPlanOptions): ProjectMemoryExtractResult;
@@ -91,5 +123,23 @@ export declare function createProjectMemoryBackupPlan(options: BackupPlanOptions
 export declare function executeProjectMemoryBackup(options: BackupPlanOptions): ProjectMemoryBackupResult;
 export declare function summarizeProjectMemoryExtractResult(result: ProjectMemoryExtractResult): ProjectMemoryExtractSummary;
 export declare function summarizeProjectMemoryBackupResult(result: ProjectMemoryBackupResult): ProjectMemoryBackupSummary;
+/**
+ * Ensure `.peaks/memory/` and its `index.json` exist for a project, with
+ * the same full-shape empty index the generator emits when there are zero
+ * memories. Idempotent — safe to call on every skill activation.
+ *
+ * Why this exists: before this helper, `.peaks/memory/` was only created
+ * by `extractSessionMemories` when at least one memory markdown was being
+ * written, and `index.json` was only emitted by the generator when at
+ * least one markdown was on disk. Stock projects therefore had no
+ * `.peaks/memory/` directory and no index, even after `peaks project
+ * memories` was read. Bootstrap closes that cold-start gap.
+ *
+ * This function is fail-open for the same reason the rest of the
+ * presence layer is fail-open: a failure here must NOT block skill
+ * activation. Any error is swallowed and surfaced only via the returned
+ * boolean. Callers that need the truth should check the result.
+ */
+export declare function ensureMemoryBootstrap(projectRoot: string): boolean;
 export declare function readProjectMemories(projectRoot: string): ProjectMemoryReadResult;
 export {};