peaks-cli 1.2.3 → 1.2.5

package/dist/src/services/memory/project-memory-service.js

@@ -1,7 +1,12 @@
-import { closeSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { closeSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
 import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../config/config-service.js';
+// Hot kinds: full body kept in index for always-available context
+const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module']);
+// ---------------------------------------------------------------------------
+// Internal helpers (kept from original, sorted by dependency order)
+// ---------------------------------------------------------------------------
 const START_MARKER = '<!-- peaks-memory:start -->';
 const END_MARKER = '<!-- peaks-memory:end -->';
 const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback', 'convention', 'module']);
@@ -171,47 +176,25 @@ function parseStoredMemoryFile(content, filePath) {
         filePath
     };
 }
-function summarizeExtractResult(result) {
-    return {
-        apply: result.apply,
-        projectRoot: result.projectRoot,
-        primaryMemoryDir: result.primaryMemoryDir,
-        backupPolicy: result.backupPolicy,
-        extractedCount: result.extractedMemories.length,
-        plannedWrites: result.plannedWrites.map((write) => ({
-            filePath: write.filePath,
-            title: write.memory.title,
-            kind: write.memory.kind,
-            sourceArtifact: write.memory.sourceArtifact
-        })),
-        writtenFiles: result.writtenFiles
-    };
-}
-function summarizeBackupResult(result) {
-    return {
-        apply: result.apply,
-        projectRoot: result.projectRoot,
-        artifactWorkspacePath: result.artifactWorkspacePath,
-        primaryMemoryDir: result.primaryMemoryDir,
-        backupMemoryDir: result.backupMemoryDir,
-        plannedCopies: result.plannedCopies,
-        copiedFiles: result.copiedFiles
-    };
-}
-function listMarkdownFiles(dirPath) {
+function listMarkdownFiles(dirPath, options = {}) {
     if (!existsSync(dirPath))
         return [];
+    const { maxDepth = Infinity, skipDotfiles = true } = options;
     const files = [];
-    const stack = [dirPath];
+    const stack = [{ path: dirPath, depth: 0 }];
     while (stack.length > 0) {
-        const currentDir = stack.pop();
-        for (const entry of readdirSync(currentDir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
-            const entryPath = join(currentDir, entry.name);
+        const frame = stack.pop();
+        if (frame.depth > maxDepth)
+            continue;
+        for (const entry of readdirSync(frame.path, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            if (skipDotfiles && entry.name.startsWith('.'))
+                continue;
+            const entryPath = join(frame.path, entry.name);
             if (entry.isSymbolicLink()) {
                 continue;
             }
             if (entry.isDirectory()) {
-                stack.push(entryPath);
+                stack.push({ path: entryPath, depth: frame.depth + 1 });
                 continue;
             }
             if (entry.isFile() && entry.name.endsWith('.md')) {
@@ -221,6 +204,285 @@ function listMarkdownFiles(dirPath) {
     }
     return files.sort((left, right) => left.localeCompare(right));
 }
+// ---------------------------------------------------------------------------
+// Description summarization (deterministic, no LLM call)
+// ---------------------------------------------------------------------------
+function summarizeMemoryBody(body) {
+    const cleaned = body
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/`{1,3}[^`]*`{1,3}/g, '')
+        .replace(/^\s*[-*+]\s+/gm, '')
+        .replace(/\n+/g, ' ')
+        .trim();
+    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > 20 && !/^\[.+\]$/.test(s));
+    if (sentences.length === 0) {
+        return cleaned.slice(0, 120) || 'Project memory';
+    }
+    const first = sentences[0];
+    if (first.length <= 120) {
+        return first;
+    }
+    return first.slice(0, 117) + '...';
+}
+// ---------------------------------------------------------------------------
+// Session memory extraction (new extract path)
+// ---------------------------------------------------------------------------
+function assertSafeSessionDir(projectRoot, sessionId) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const realRoot = normalizeRealRoot(projectRoot);
+    const sessionDir = join(normalizedRoot, '.peaks', sessionId);
+    if (!existsSync(sessionDir)) {
+        // Distinguish "not found" (caller will treat as no-op) from "escapes project
+        // root" (caller must surface a hard error). We probe by checking whether the
+        // joined path, after realpath, would still be inside the project root.
+        if (isAbsolute(join(normalizedRoot, '.peaks', sessionId))) {
+            const realJoined = safeRealpath(join(normalizedRoot, '.peaks', sessionId));
+            if (realJoined && !isInsidePath(realJoined, realRoot)) {
+                throw new Error('Session directory must stay inside the project root');
+            }
+        }
+        throw new Error('SESSION_DIR_NOT_FOUND');
+    }
+    const stats = lstatSync(sessionDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    const realSessionDir = realpathSync(sessionDir);
+    if (!isInsidePath(realSessionDir, realRoot)) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    return sessionDir;
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function readMemoryFileMtime(filePath) {
+    try {
+        return statSync(filePath).mtime.toISOString().slice(0, 10);
+    }
+    catch {
+        return new Date().toISOString().slice(0, 10);
+    }
+}
+function readStoredMemoryNames(memoryDir) {
+    // Two source-of-truth fallbacks for the slug-collision check:
+    //   1. Parse frontmatter (the canonical form rendered by
+    //      renderMemoryFile / written by both extract paths).
+    //   2. Fall back to the bare filename stem, so user-dropped files
+    //      without frontmatter (e.g. hand-written memories, legacy
+    //      content) still count as a collision and are not overwritten
+    //      by an idempotent re-extract.
+    const names = new Set();
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        const stem = basename(filePath, '.md');
+        if (stem.length > 0 && stem !== 'index')
+            names.add(stem);
+        try {
+            const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+            if (parsed)
+                names.add(parsed.name);
+        }
+        catch {
+            // ignore unreadable files
+        }
+    }
+    return names;
+}
+function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
+    const memories = readProjectMemories(projectRoot);
+    const hot = {
+        feedback: [], decision: [], rule: [], convention: [], module: []
+    };
+    const warm = {
+        project: [], reference: []
+    };
+    for (const memory of memories.memories) {
+        const entry = {
+            name: memory.name,
+            kind: memory.kind,
+            description: memory.body ? summarizeMemoryBody(memory.body) : memory.title,
+            sourcePath: memory.filePath,
+            sourceArtifact: memory.sourceArtifact,
+            updatedAt: readMemoryFileMtime(memory.filePath)
+        };
+        if (HOT_KINDS.has(memory.kind)) {
+            hot[memory.kind].push(entry);
+        }
+        else {
+            warm[memory.kind].push(entry);
+        }
+    }
+    for (const kind of [...Object.keys(hot), ...Object.keys(warm)]) {
+        const arr = hot[kind] ?? warm[kind];
+        if (arr)
+            arr.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    const index = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        hot: hot,
+        warm: warm
+    };
+    const fd = openSync(indexPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC, 0o644);
+    try {
+        writeFileSync(fd, JSON.stringify(index, null, 2), 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readExistingIndex(indexPath) {
+    if (!existsSync(indexPath))
+        return null;
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version === 1)
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readMemoryIndex(projectRoot) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    const indexPath = join(memoryDir, 'index.json');
+    // Read-side bootstrap: if the memory dir is missing entirely, build a full
+    // empty index so downstream readers always see a well-formed result. We
+    // also fall through if the dir is present but the index is missing — the
+    // user may have nuked the index file, or never had one because no
+    // memory has ever been extracted in this project.
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+        return readExistingIndex(indexPath);
+    }
+    if (!existsSync(indexPath)) {
+        try {
+            writeFileSync(indexPath, renderEmptyIndex(), { mode: 0o644 });
+        }
+        catch {
+            // fall through — readExistingIndex will return null
+        }
+    }
+    const files = listMarkdownFiles(memoryDir);
+    if (files.length > 0) {
+        try {
+            generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
+        }
+        catch {
+            // fall through to read existing
+        }
+    }
+    return readExistingIndex(indexPath);
+}
+export function extractSessionMemories(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const apply = options.apply ?? false;
+    const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const memoryIndexPath = join(primaryMemoryDir, 'index.json');
+    // Resolve sessionDir through realpath + inside-project guard so a hostile
+    // sessionId (`..`, abs path, symlink chain) cannot walk the scanner outside
+    // the project root. A sentinel "SESSION_DIR_NOT_FOUND" distinguishes a
+    // benign miss from an escape attempt.
+    let sessionDir;
+    try {
+        sessionDir = assertSafeSessionDir(projectRoot, options.sessionId);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'SESSION_DIR_NOT_FOUND') {
+            return {
+                apply,
+                projectRoot,
+                sessionId: options.sessionId,
+                primaryMemoryDir,
+                memoryIndexPath,
+                scannedFiles: 0,
+                extractedCount: 0,
+                writtenFiles: [],
+                updatedIndex: false
+            };
+        }
+        throw error;
+    }
+    const scannedFiles = listMarkdownFiles(sessionDir, { maxDepth: 6, skipDotfiles: true });
+    const allExtracted = [];
+    for (const filePath of scannedFiles) {
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            const relativePath = relative(projectRoot, filePath).replaceAll('\\', '/');
+            const extracted = extractStableProjectMemories(content, relativePath);
+            allExtracted.push(...extracted);
+        }
+        catch {
+            // skip unreadable files
+        }
+    }
+    if (allExtracted.length === 0) {
+        return {
+            apply,
+            projectRoot,
+            sessionId: options.sessionId,
+            primaryMemoryDir,
+            memoryIndexPath,
+            scannedFiles: scannedFiles.length,
+            extractedCount: 0,
+            writtenFiles: [],
+            updatedIndex: false
+        };
+    }
+    const slugCounts = new Map();
+    for (const memory of allExtracted) {
+        const slug = slugify(memory.title);
+        slugCounts.set(slug, (slugCounts.get(slug) ?? 0) + 1);
+    }
+    const duplicateTitles = [...slugCounts.entries()].filter(([, count]) => count > 1).map(([slug]) => slug);
+    if (duplicateTitles.length > 0) {
+        throw new Error(`Duplicate memory titles are not allowed: ${duplicateTitles.join(', ')}`);
+    }
+    // Idempotency: pre-read existing memory names so a re-run of the same
+    // session does not throw EEXIST. `writtenFiles` reports only the new
+    // writes so callers can still tell what the run actually produced.
+    const existingNames = apply ? readStoredMemoryNames(primaryMemoryDir) : new Set();
+    const writtenFiles = [];
+    if (apply) {
+        mkdirSync(primaryMemoryDir, { recursive: true });
+        for (const memory of allExtracted) {
+            const slug = slugify(memory.title);
+            if (existingNames.has(slug))
+                continue;
+            const targetPath = join(primaryMemoryDir, `${slug}.md`);
+            const safePath = resolveInputPath(targetPath);
+            const stableSafePath = stablePath(safePath);
+            if (!isInsidePath(stableSafePath, stableRealPath(primaryMemoryDir))) {
+                throw new Error('Project memory write target must stay inside the project memory directory');
+            }
+            writeNewFile(safePath, renderMemoryFile(memory));
+            writtenFiles.push(safePath);
+        }
+        generateMemoryIndexFile(projectRoot, primaryMemoryDir, memoryIndexPath);
+    }
+    return {
+        apply,
+        projectRoot,
+        sessionId: options.sessionId,
+        primaryMemoryDir,
+        memoryIndexPath,
+        scannedFiles: scannedFiles.length,
+        extractedCount: allExtracted.length,
+        writtenFiles,
+        updatedIndex: apply && writtenFiles.length > 0
+    };
+}
+// ---------------------------------------------------------------------------
+// Old extract path (kept for core-artifact-commands.ts)
+// ---------------------------------------------------------------------------
 export function extractStableProjectMemories(content, sourceArtifact) {
     const memories = [];
     let searchStart = 0;
@@ -241,6 +503,33 @@ export function extractStableProjectMemories(content, sourceArtifact) {
     }
     return memories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
 }
+function summarizeExtractResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupPolicy: result.backupPolicy,
+        extractedCount: result.extractedMemories.length,
+        plannedWrites: result.plannedWrites.map((write) => ({
+            filePath: write.filePath,
+            title: write.memory.title,
+            kind: write.memory.kind,
+            sourceArtifact: write.memory.sourceArtifact
+        })),
+        writtenFiles: result.writtenFiles
+    };
+}
+function summarizeBackupResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        artifactWorkspacePath: result.artifactWorkspacePath,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupMemoryDir: result.backupMemoryDir,
+        plannedCopies: result.plannedCopies,
+        copiedFiles: result.copiedFiles
+    };
+}
 export function createProjectMemoryExtractPlan(options) {
     const projectRoot = normalizeRoot(options.projectRoot);
     const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
@@ -278,7 +567,18 @@ export function executeProjectMemoryExtract(options) {
     if (plan.apply) {
         mkdirSync(plan.primaryMemoryDir, { recursive: true });
         const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
+        // Idempotency: skip writes for memories whose slug already lives in
+        // .peaks/memory/. Re-running `peaks memory extract --apply` on the
+        // same handoff is a normal peaks-solo / peaks-txt retry pattern (the
+        // skill prompt may invoke extract more than once when a handoff is
+        // edited and re-extracted). Without this, writeNewFile's O_EXCL
+        // throws EEXIST and aborts the whole batch. Symmetric with
+        // extractSessionMemories (line ~614) which does the same skip.
+        const existingNames = readStoredMemoryNames(plan.primaryMemoryDir);
         for (const write of plan.plannedWrites) {
+            const slug = slugify(write.memory.title);
+            if (existingNames.has(slug))
+                continue;
             const targetPath = resolveInputPath(write.filePath);
             const stableTargetPath = stablePath(targetPath);
             if (!isInsidePath(stableTargetPath, stableRealPath(safeMemoryDir))) {
@@ -287,6 +587,18 @@ export function executeProjectMemoryExtract(options) {
             writeNewFile(targetPath, write.content);
             writtenFiles.push(targetPath);
         }
+        // After writing any markdown, regenerate the index so downstream
+        // readers (peaks project memory-index, peaks-txt re-runs, the next
+        // session's presence-set bootstrap) see the new memory. Without
+        // this, `peaks memory extract --apply` would leave the index stale
+        // and `readMemoryIndex` would either return the empty bootstrap or
+        // — pre-bootstrap-fix — return null. Symmetric with
+        // extractSessionMemories, which already regenerates the index on
+        // apply (see line ~626). We regen whenever --apply is set, even
+        // if every write was skipped by idempotency, so the index is
+        // always rebuilt against the current .peaks/memory/ directory.
+        const indexPath = join(plan.primaryMemoryDir, 'index.json');
+        generateMemoryIndexFile(plan.projectRoot, plan.primaryMemoryDir, indexPath);
     }
     return { ...plan, writtenFiles };
 }
@@ -350,9 +662,74 @@ function emptyByKind() {
         module: []
     };
 }
+function emptyIndex() {
+    // Cast through unknown: we *intend* the two halves to together cover the
+    // union `ProjectMemoryKind`, but TS does not know that. The `MemoryIndex`
+    // type's `hot` / `warm` fields together cover the union; we split the
+    // construction so the JSON output mirrors the hot/warm layout the reader
+    // expects.
+    return {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        hot: {
+            feedback: [],
+            decision: [],
+            rule: [],
+            convention: [],
+            module: []
+        },
+        warm: {
+            project: [],
+            reference: []
+        }
+    };
+}
+function renderEmptyIndex() {
+    return JSON.stringify(emptyIndex(), null, 2) + '\n';
+}
+/**
+ * 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 function ensureMemoryBootstrap(projectRoot) {
+    try {
+        const normalizedRoot = normalizeRoot(projectRoot);
+        const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+        const indexPath = join(memoryDir, 'index.json');
+        mkdirSync(memoryDir, { recursive: true });
+        if (!existsSync(indexPath)) {
+            writeFileSync(indexPath, renderEmptyIndex(), { mode: 0o644 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function readProjectMemories(projectRoot) {
     const normalizedRoot = normalizeRoot(projectRoot);
     const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    // Read-side bootstrap: on a stock project the directory does not exist
+    // yet. Reading must not return an error, but we also want the directory
+    // to materialise (along with a full-shape empty index) so subsequent
+    // `peaks project memories` invocations, `readMemoryIndex`, and any
+    // extraction call find a stable target. The helper is fail-open.
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+    }
     const memories = [];
     for (const filePath of listMarkdownFiles(memoryDir)) {
         const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);

package/dist/src/services/openspec/openspec-init-service.d.ts

@@ -0,0 +1,23 @@
+export type OpenSpecInitOptions = {
+    projectRoot: string;
+    apply?: boolean;
+};
+export type OpenSpecInitPlan = {
+    apply: boolean;
+    projectRoot: string;
+    openspecRoot: string;
+    plannedWrites: Array<{
+        path: string;
+        kind: 'directory' | 'file';
+        bytes: number;
+        content: string;
+    }>;
+    alreadyInitialized: boolean;
+    existingFiles: string[];
+};
+export type OpenSpecInitResult = OpenSpecInitPlan & {
+    writtenFiles: string[];
+    createdDirectories: string[];
+};
+export declare function planOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitPlan>;
+export declare function executeOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitResult>;

package/dist/src/services/openspec/openspec-init-service.js

@@ -0,0 +1,122 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists } from '../../shared/fs.js';
+const README_BODY = `# OpenSpec — change proposals for this project
+
+This directory hosts the \`peaks openspec\` change proposal lifecycle:
+
+  render → validate → show → to-rd → ... → archive
+
+Each in-flight proposal lives in \`changes/<id>/\` and contains:
+
+- \`proposal.md\`  — why, what, non-goals, impact
+- \`tasks.md\`     — concrete slices and commit boundaries (consumed by peaks-sc)
+- \`design.md\`   — optional, for non-trivial designs
+- \`specs/\`       — optional, delta-style spec changes (## ADDED / ## MODIFIED / ## REMOVED)
+- \`*.md\`         — any additional narrative the change needs
+
+When a change ships, \`peaks openspec archive <id> --apply\` moves it into
+\`changes/archive/<id>/\`. The archive is the historical record of what
+landed and why.
+
+To scaffold a fresh change in this project:
+
+  peaks openspec render --request <path-to-render-request.json> --apply
+
+For the full lifecycle see \`peaks openspec --help\` and the
+peaks-clause-code skill family.
+`;
+const CHANGES_INDEX_HEADER = `# OpenSpec — change log
+
+This file is the human-readable index of every change that has shipped in
+this project. New entries are added by \`peaks openspec archive\` (when
+\`.apply\` is used); do not hand-edit.
+
+| Date | Change | Status |
+|------|--------|--------|
+`;
+function renderReadme() {
+    return README_BODY;
+}
+function renderChangesIndex() {
+    return CHANGES_INDEX_HEADER;
+}
+function buildPlan(projectRoot, apply) {
+    const openspecRoot = join(projectRoot, 'openspec');
+    const changesRoot = join(openspecRoot, 'changes');
+    const archiveRoot = join(changesRoot, 'archive');
+    const plannedWrites = [
+        { path: openspecRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: changesRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: archiveRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: join(openspecRoot, 'README.md'), kind: 'file', bytes: 0, content: renderReadme() },
+        { path: join(openspecRoot, 'CHANGES.md'), kind: 'file', bytes: 0, content: renderChangesIndex() }
+    ];
+    // Stamp byte counts now that content is finalised.
+    for (const write of plannedWrites) {
+        if (write.kind === 'file') {
+            write.bytes = Buffer.byteLength(write.content, 'utf8');
+        }
+    }
+    return {
+        apply,
+        projectRoot,
+        openspecRoot,
+        plannedWrites,
+        alreadyInitialized: false,
+        existingFiles: []
+    };
+}
+export async function planOpenSpecInit(options) {
+    const openspecRoot = join(options.projectRoot, 'openspec');
+    const plan = buildPlan(options.projectRoot, options.apply ?? false);
+    if (await isDirectory(openspecRoot)) {
+        // Already initialised. Report the existing files so the user can audit
+        // before re-running with --apply. We never overwrite an existing
+        // openspec/ — that is a destructive action and out of scope for init.
+        const existing = [];
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'file' && (await pathExists(write.path))) {
+                existing.push(write.path);
+            }
+        }
+        // Pre-compute which directory writes to keep (those whose target does
+        // not exist yet). .filter cannot be async, so resolve the boolean
+        // set up front.
+        const directoryKeep = new Set();
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory' && !(await isDirectory(write.path))) {
+                directoryKeep.add(write.path);
+            }
+        }
+        plan.plannedWrites = plan.plannedWrites.filter((write) => {
+            if (write.kind === 'directory')
+                return directoryKeep.has(write.path);
+            return !existing.includes(write.path);
+        });
+        plan.alreadyInitialized = existing.length > 0 || (await isDirectory(join(openspecRoot, 'changes')));
+        plan.existingFiles = existing;
+    }
+    return plan;
+}
+export async function executeOpenSpecInit(options) {
+    const plan = await planOpenSpecInit(options);
+    const writtenFiles = [];
+    const createdDirectories = [];
+    if (plan.apply && !plan.alreadyInitialized) {
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory') {
+                if (!(await isDirectory(write.path))) {
+                    await mkdir(write.path, { recursive: true });
+                    createdDirectories.push(write.path);
+                }
+                continue;
+            }
+            if (write.content.length === 0)
+                continue;
+            await writeFile(write.path, write.content, 'utf8');
+            writtenFiles.push(write.path);
+        }
+    }
+    return { ...plan, writtenFiles, createdDirectories };
+}

package/dist/src/services/session/index.d.ts

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, type SessionInfo, type SessionMeta } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';

package/dist/src/services/session/index.js

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding } from './session-manager.js';

package/dist/src/services/session/session-manager.d.ts

@@ -20,6 +20,17 @@ export type SessionMeta = {
     lastActivity?: string;
     projectRoot: string;
 };
+/**
+ * Bind the project's current session to the given session id by writing
+ * `.peaks/.session.json`. The single-session binding is the source of truth
+ * for `ensureSession()` and any other path that needs to discover the
+ * active session without an explicit --session-id flag.
+ *
+ * This does NOT touch the per-session `session.json` inside `.peaks/<id>/`;
+ * that file is owned by `setSessionMeta` and records session-scoped
+ * metadata (title, skill, mode, gate, etc.).
+ */
+export declare function setCurrentSessionBinding(projectRoot: string, sessionId: string): SessionInfo;
 /**
  * Read metadata for a specific session directory.
  * Returns null if the session directory or its session.json does not exist.