peaks-cli 1.2.8 → 1.3.0

package/README.md

@@ -13,6 +13,18 @@ npm install -g peaks-cli
 
 安装后，Peaks 会把内置的 8 个 `peaks-*` 技能注册到 Claude Code，会话里直接通过技能名调用即可。
 
+## 本地开发（从源码跑 CLI）
+
+仓库自带 `peaks` CLI 源码。开发模式用 `tsx` 直接跑 `src/cli/index.ts`，所以**首次克隆后 `node_modules/` 里不会有 `chalk` / `ora` / `terminal-kit` 等运行时依赖**——直接 `tsx src/cli/index.ts` 会报 `ERR_MODULE_NOT_FOUND: chalk`。先执行一次 `pnpm install` 把依赖补齐，再验证：
+
+```bash
+pnpm install
+pnpm exec tsx src/cli/index.ts --version   # 应打印 1.2.9
+pnpm exec tsx src/cli/index.ts <cmd>       # 与全局 `peaks <cmd>` 行为一致
+```
+
+热重载开发循环可用 `pnpm dev:watch`。
+
 ## 5 分钟上手
 
 在 Claude Code 对话里，**直接对 Claude 说「用 X 技能做 Y」** 即可，技能会接管剩下的所有流程：

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

@@ -123,7 +123,7 @@ export function registerProjectCommands(program, io) {
         .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 kind: project, rule, decision, reference, feedback, convention, module')).action((options) => {
+        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module, lesson')).action((options) => {
         try {
             const result = readProjectMemories(options.project);
             if (options.kind) {

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

@@ -5,6 +5,7 @@ import { checkTypeSanity } from '../../services/scan/type-sanity-service.js';
 import { getAcceptanceCoverage, isAcceptanceCoverageError } from '../../services/scan/acceptance-coverage-service.js';
 import { getDiffVsScope, isDiffScopeError } from '../../services/scan/diff-scope-service.js';
 import { scanFileSize, DEFAULT_FILE_SIZE_THRESHOLD } from '../../services/scan/file-size-scan.js';
+import { scanLibraries } from '../../services/scan/libraries-service.js';
 import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
@@ -221,4 +222,25 @@ export function registerScanCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(scan
+        .command('libraries')
+        .description('Enumerate every dependency + devDependency + peerDependency + optionalDependency in package.json with parsed major version (read-only). Output goes to ## Library versions in rd/project-scan.md.')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        try {
+            const report = await scanLibraries({ projectRoot: options.project });
+            const nextActions = [];
+            if (report.libraries.length === 0) {
+                nextActions.push('No dependencies found — verify package.json exists and is valid JSON.');
+            }
+            else {
+                nextActions.push('Paste the report under `## Library versions` in .peaks/<sid>/rd/project-scan.md.');
+                nextActions.push('peaks-rd preflight will cross-check diff imports against schemas/library-breaking-changes.data.json.');
+            }
+            printResult(io, ok('scan.libraries', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('scan.libraries', 'SCAN_LIBRARIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -1,8 +1,11 @@
 import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
+import { reconcileWorkspace } from '../../services/workspace/reconcile-service.js';
 import { ensureSession } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_RECONCILE_AGE_DAYS = 7;
 export function registerWorkspaceCommands(program, io) {
     const workspace = program.command('workspace').description('Manage the Peaks per-session artifact workspace (.peaks/<session-id>/)');
     addJsonOption(workspace
@@ -18,7 +21,7 @@ export function registerWorkspaceCommands(program, io) {
             //     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.
+            //     .peaks/_runtime/session.json so the binding sticks.
             //
             // Before that: canonicalise the project root. If the user (or the
             // LLM via "$(pwd)") passed a sub-directory of a real git repo
@@ -75,4 +78,59 @@ export function registerWorkspaceCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(workspace
+        .command('reconcile')
+        .description('Scan .peaks/2026-MM-DD-session-*/ directories and re-point .peaks/_runtime/session.json ' +
+        'to the canonical session (4-tier heuristic: active-skill binding -> latest session.json mtime -> ' +
+        'latest any-file mtime -> dir-name sort). Also migrates any legacy .peaks/.session.json / ' +
+        '.peaks/.active-skill.json / .peaks/sop-state/ into .peaks/_runtime/ (idempotent; no-op on a ' +
+        'tree that is already on the new layout). By default the command is a dry-run: it reports empty / abandoned ' +
+        `session dirs older than ${DEFAULT_RECONCILE_AGE_DAYS} days as deletion candidates but does not delete them. ` +
+        'Pass --apply to actually remove the listed candidate dirs (destructive). ' +
+        'Override the age threshold with --older-than <days>.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually delete the deletion candidates (destructive); without it, dry-run only', false)
+        .option('--older-than <days>', `age threshold in days for deletion candidates (default: ${DEFAULT_RECONCILE_AGE_DAYS})`, (value) => Number.parseFloat(value))).action((options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const olderThanDays = options.olderThan ?? DEFAULT_RECONCILE_AGE_DAYS;
+            if (typeof olderThanDays !== 'number' || !Number.isFinite(olderThanDays) || olderThanDays <= 0) {
+                printResult(io, fail('workspace.reconcile', 'INVALID_AGE_THRESHOLD', `--older-than must be a positive number of days`, { provided: options.olderThan }, ['Use --older-than 7 (or omit it to accept the 7-day default)']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const olderThanMs = olderThanDays * MS_PER_DAY;
+            const apply = options.apply === true;
+            const result = reconcileWorkspace({
+                projectRoot,
+                apply,
+                olderThanMs
+            });
+            const warnings = [];
+            if (result.sessions.length === 0) {
+                warnings.push('No session directories found under .peaks/. Run peaks workspace init first.');
+            }
+            if (apply && result.deleted.length > 0) {
+                warnings.push(`Deleted ${result.deleted.length} session dir(s) older than ${olderThanDays} day(s).`);
+            }
+            const nextActions = [];
+            if (result.migratedFiles.length > 0) {
+                nextActions.push(`Migrated ${result.migratedFiles.length} legacy runtime file(s) into .peaks/_runtime/: ${result.migratedFiles.join(', ')}.`);
+            }
+            if (result.repointed) {
+                nextActions.push(`Re-pointed .peaks/_runtime/session.json from ${result.repointedFrom ?? '<unbound>'} to ${result.repointedTo}.`);
+            }
+            if (!apply && result.wouldDelete.length > 0) {
+                nextActions.push(`Re-run with --apply to delete ${result.wouldDelete.length} candidate dir(s).`);
+            }
+            printResult(io, ok('workspace.reconcile', result, warnings, nextActions), options.json);
+            if (result.errors.length > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('workspace.reconcile', 'WORKSPACE_RECONCILE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -1,4 +1,4 @@
-export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module';
+export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module' | 'lesson';
 export type ExtractedProjectMemory = {
     title: string;
     kind: ProjectMemoryKind;

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

@@ -3,13 +3,20 @@ import { dirname, basename, isAbsolute, join, relative, resolve } from 'node:pat
 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']);
+const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module', 'lesson']);
 // ---------------------------------------------------------------------------
 // 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']);
+const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback', 'convention', 'module', 'lesson']);
+// Length bounds for index entry descriptions. The numbers were chosen when
+// summarizeMemoryBody was first introduced; locking them in as named
+// constants is a doc-as-code move so the truncation rule is no longer
+// "magic". Bump MAX_DESCRIPTION_LENGTH deliberately if downstream UIs grow.
+const MIN_BODY_SENTENCE_LENGTH = 20; // skip fragments shorter than this when picking a leading sentence
+const MAX_DESCRIPTION_LENGTH = 120; // hard cap on description length in the memory index entry
+const ELLIPSIS_RESERVE = 3; // length of the trailing "..." when truncating with an ellipsis
 function normalizeRoot(path) {
     return resolveInputPath(path);
 }
@@ -214,15 +221,15 @@ function summarizeMemoryBody(body) {
         .replace(/^\s*[-*+]\s+/gm, '')
         .replace(/\n+/g, ' ')
         .trim();
-    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > 20 && !/^\[.+\]$/.test(s));
+    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > MIN_BODY_SENTENCE_LENGTH && !/^\[.+\]$/.test(s));
     if (sentences.length === 0) {
-        return cleaned.slice(0, 120) || 'Project memory';
+        return cleaned.slice(0, MAX_DESCRIPTION_LENGTH) || 'Project memory';
     }
     const first = sentences[0];
-    if (first.length <= 120) {
+    if (first.length <= MAX_DESCRIPTION_LENGTH) {
         return first;
     }
-    return first.slice(0, 117) + '...';
+    return first.slice(0, MAX_DESCRIPTION_LENGTH - ELLIPSIS_RESERVE) + '...';
 }
 // ---------------------------------------------------------------------------
 // Session memory extraction (new extract path)
@@ -296,7 +303,7 @@ function readStoredMemoryNames(memoryDir) {
 function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
     const memories = readProjectMemories(projectRoot);
     const hot = {
-        feedback: [], decision: [], rule: [], convention: [], module: []
+        feedback: [], decision: [], rule: [], convention: [], module: [], lesson: []
     };
     const warm = {
         project: [], reference: []
@@ -350,29 +357,49 @@ function readExistingIndex(indexPath) {
         return null;
     }
 }
+// Decide whether readMemoryIndex should rebuild the on-disk index.json.
+// The rule is: rebuild iff index.json is missing OR any memory.md has an
+// mtime strictly greater than index.json's mtime. Any statSync failure
+// falls back to "rebuild" — a safe default that matches the prior
+// always-rebuild behaviour and avoids serving a stale index from a
+// partially-corrupt dir.
+function shouldRegenerateIndex(indexPath, memoryFiles) {
+    let indexMtimeMs = 0;
+    try {
+        indexMtimeMs = statSync(indexPath).mtimeMs;
+    }
+    catch {
+        return true; // no index → must regenerate
+    }
+    for (const memoryPath of memoryFiles) {
+        try {
+            const memoryMtimeMs = statSync(memoryPath).mtimeMs;
+            if (memoryMtimeMs > indexMtimeMs)
+                return true;
+        }
+        catch {
+            return true; // unreadable file → safe default is regenerate
+        }
+    }
+    return false;
+}
 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.
+    // Read-side bootstrap: if the memory dir is missing entirely, build it and
+    // return whatever index is on disk (likely null on a fresh project). We
+    // deliberately do NOT pre-write an empty index here: the mtime-based
+    // regeneration guard below is the sole authority on whether index.json
+    // gets materialised, and pre-writing an empty index would race the guard
+    // (giving it a current-time mtime that defeats "memory older than index"
+    // detection on the first read).
     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) {
+    if (files.length > 0 && shouldRegenerateIndex(indexPath, files)) {
         try {
             generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
         }
@@ -659,7 +686,8 @@ function emptyByKind() {
         reference: [],
         feedback: [],
         convention: [],
-        module: []
+        module: [],
+        lesson: []
     };
 }
 function emptyIndex() {
@@ -676,7 +704,8 @@ function emptyIndex() {
             decision: [],
             rule: [],
             convention: [],
-            module: []
+            module: [],
+            lesson: []
         },
         warm: {
             project: [],

package/dist/src/services/sc/sc-service.d.ts

@@ -51,6 +51,52 @@ export type CommitBoundary = {
     syncState: 'synced' | 'pending' | 'failed';
     rollbackPoint: string | null;
 };
+/**
+ * Resolution sources for `resolveArtifactSession`, in priority order.
+ * - `active-skill`: the orchestrator's active-skill marker
+ *   (`.peaks/_runtime/active-skill.json`, with a one-minor-release
+ *   fallback to `.peaks/.active-skill.json`) `sessionId` points to a
+ *   session dir that owns the slice's marker artifact.
+ * - `session-json`: the workspace binding in
+ *   `.peaks/_runtime/session.json` (with back-compat fallback to
+ *   `.peaks/.session.json`) points to a session dir that owns the
+ *   slice's marker artifact (active-skill was checked but did not
+ *   own it; session-json is the next source).
+ * - `find-fallback`: neither binding owned the artifact, but a `find`
+ *   walk under `.peaks/` located a session dir that does own it.
+ */
+export type ArtifactSessionSource = 'active-skill' | 'session-json' | 'find-fallback';
+export type ResolvedArtifactSession = {
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
+};
+/**
+ * Resolve the session id that owns the slice's artifacts using a 3-tier
+ * precedence:
+ *
+ *   1. `.peaks/_runtime/active-skill.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.active-skill.json`) if it points to a real
+ *      session that owns the slice.
+ *   2. `.peaks/_runtime/session.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.session.json`) if it points to a real
+ *      session that owns the slice.
+ *   3. `find .peaks/ -name '<marker>'` — the first session dir under
+ *      `.peaks/` that owns the slice.
+ *   4. else `{ resolvedSessionId: null, candidateSources: [] }`.
+ *
+ * The back-compat fallbacks are tolerated for one minor release so
+ * users with pre-migration trees (or running an older CLI version)
+ * still get a clean resolution. After the migration (or after v1.3.0
+ * is installed and `peaks workspace reconcile` has been run), only
+ * the new paths exist and the fallbacks never fire.
+ *
+ * `candidateSources` reports which sources were checked before the
+ * resolver found (or did not find) a winner; the list is in the order
+ * the resolver consulted them. This makes the precedence observable in
+ * the JSON envelope so a human reviewer can see "active-skill was empty
+ * AND session-json was empty, so find-fallback won".
+ */
+export declare function resolveArtifactSession(projectRoot: string, sliceId: string): ResolvedArtifactSession;
 export declare function getChangeTraceabilityStatus(): ChangeTraceabilityStatus;
 export declare function createChangeImpact(options: {
     changeId: string;
@@ -71,10 +117,15 @@ export declare function recordCommitBoundary(options: {
     sliceId: string;
     artifacts?: string[];
     codeFiles?: string[];
-}): CommitBoundary;
+}): CommitBoundary & {
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
+};
 export declare function validateArtifactRetention(sliceId: string): {
     valid: boolean;
     missingArtifacts: string[];
     warnings: string[];
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
 };
 export declare function getScHelpText(): string[];