peaks-cli 1.2.8 → 1.2.9

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/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/scan/libraries-service.d.ts

@@ -0,0 +1,24 @@
+import type { LibraryReport } from './libraries-types.js';
+export type ScanLibrariesOptions = {
+    projectRoot: string;
+};
+/**
+ * Parse the major version from a semver-ish spec.
+ *
+ * Handles the common shapes:
+ *   "^5.18.0"      → 5
+ *   "~1.2.3"       → 1
+ *   "1.2.3"        → 1
+ *   ">=1.0.0"      → 1
+ *   "5"            → 5
+ *   "5.x"          → 5
+ *
+ * Returns null for non-semver specs that the LLM should not assume a
+ * major for:
+ *   "workspace:*"  → null
+ *   "file:../..."   → null
+ *   "git+https..." → null
+ *   "npm:@scope/x@1" → 1 (alias spec, we extract what we can)
+ */
+export declare function parseMajorVersion(spec: string): number | null;
+export declare function scanLibraries(options: ScanLibrariesOptions): Promise<LibraryReport>;

package/dist/src/services/scan/libraries-service.js

@@ -0,0 +1,419 @@
+import { readdir } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+const SCOPES = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies'
+];
+const SCOPE_ORDER = {
+    dependencies: 0,
+    devDependencies: 1,
+    peerDependencies: 2,
+    optionalDependencies: 3
+};
+/**
+ * Parse the major version from a semver-ish spec.
+ *
+ * Handles the common shapes:
+ *   "^5.18.0"      → 5
+ *   "~1.2.3"       → 1
+ *   "1.2.3"        → 1
+ *   ">=1.0.0"      → 1
+ *   "5"            → 5
+ *   "5.x"          → 5
+ *
+ * Returns null for non-semver specs that the LLM should not assume a
+ * major for:
+ *   "workspace:*"  → null
+ *   "file:../..."   → null
+ *   "git+https..." → null
+ *   "npm:@scope/x@1" → 1 (alias spec, we extract what we can)
+ */
+export function parseMajorVersion(spec) {
+    // Strip npm alias prefix "npm:" and take whatever comes after the LAST "@"
+    // (since alias specs are "npm:<name>@<version>")
+    let versionPart = spec;
+    if (versionPart.startsWith('npm:')) {
+        const atIdx = versionPart.lastIndexOf('@');
+        versionPart = atIdx >= 0 ? versionPart.slice(atIdx + 1) : versionPart.slice(4);
+    }
+    // Strip semver range operators (caret, tilde, comparison ops, exact)
+    versionPart = versionPart.replace(/^[\^~>=<]+\s*/, '').trim();
+    // Take the first numeric component
+    const match = /^(\d+)/.exec(versionPart);
+    if (!match)
+        return null;
+    const n = Number(match[1]);
+    return Number.isSafeInteger(n) ? n : null;
+}
+async function readPackageJson(packageJsonPath) {
+    if (!(await pathExists(packageJsonPath))) {
+        return { exists: false, record: null };
+    }
+    try {
+        const raw = await readText(packageJsonPath);
+        const record = JSON.parse(raw);
+        return { exists: true, record };
+    }
+    catch (error) {
+        return { exists: true, record: null, error: error.message };
+    }
+}
+/**
+ * Hand-rolled YAML parser for `pnpm-workspace.yaml`.
+ *
+ * Only consumes the top-level `packages:` list. Ignores all other top-level
+ * keys (`allowBuilds:`, `catalog:`, etc.) and indented blocks. Returns
+ * `null` when the file is present but does not contain a `packages:`
+ * list — callers should fall through to the next detection source.
+ *
+ * Supports the common shapes:
+ *   packages:
+ *     - 'packages/*'
+ *     - "apps/web"
+ *     - tools
+ *     - packages/hermes-agent/*
+ */
+function parsePnpmWorkspaceYaml(content) {
+    const lines = content.split(/\r?\n/);
+    let inPackagesList = false;
+    let packagesIndent = -1;
+    const result = [];
+    for (const rawLine of lines) {
+        // Strip comments (anything after # not inside quotes — close enough for our use)
+        const commentIdx = rawLine.indexOf('#');
+        const line = (commentIdx >= 0 ? rawLine.slice(0, commentIdx) : rawLine).replace(/\s+$/, '');
+        if (line.length === 0)
+            continue;
+        if (!inPackagesList) {
+            // Looking for the top-level `packages:` key.
+            const match = /^packages:\s*$/.exec(line);
+            if (match) {
+                inPackagesList = true;
+            }
+            continue;
+        }
+        // Inside the packages list. Items must be more indented than the key.
+        const indent = line.match(/^\s*/)?.[0].length ?? 0;
+        if (packagesIndent < 0) {
+            // First non-empty line after the key — this sets the indent.
+            if (indent === 0) {
+                // `packages:` was the last meaningful line; an unindented line
+                // means the list is empty or the format is unsupported.
+                break;
+            }
+            packagesIndent = indent;
+        }
+        else if (indent < packagesIndent) {
+            // Outdented — the list ended.
+            break;
+        }
+        else if (indent > packagesIndent) {
+            // Nested list (e.g. `packages: [{ ... }]`) — unsupported; stop.
+            break;
+        }
+        // Expect `- <value>` or `- '<value>'` or `- "<value>"`.
+        const itemMatch = /^\s*-\s+(['"]?)(.+?)\1\s*$/.exec(line);
+        if (itemMatch && itemMatch[2] !== undefined) {
+            result.push(itemMatch[2]);
+        }
+        else {
+            // Not a list item; the block ended.
+            break;
+        }
+    }
+    return result;
+}
+function extractNpmWorkspaces(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === 'object' && Array.isArray(value.packages)) {
+        return value.packages;
+    }
+    return null;
+}
+/**
+ * Discover workspace `package.json` paths from the supported monorepo
+ * manifest sources. Returns the list of absolute paths plus which
+ * detection source won. When no source is present, returns an empty
+ * list with `source: null` (caller should fall through to single-package
+ * behavior).
+ */
+async function discoverWorkspacePackageJsons(projectRoot, warnings) {
+    // 1. pnpm-workspace.yaml
+    const pnpmWsPath = join(projectRoot, 'pnpm-workspace.yaml');
+    if (await pathExists(pnpmWsPath)) {
+        try {
+            const yaml = await readText(pnpmWsPath);
+            const globs = parsePnpmWorkspaceYaml(yaml);
+            if (globs && globs.length > 0) {
+                const paths = await expandWorkspaceGlobs(projectRoot, globs, warnings);
+                return { paths, source: 'pnpm-workspace' };
+            }
+        }
+        catch (error) {
+            warnings.push(`pnpm-workspace.yaml present but unreadable: ${error.message}`);
+        }
+    }
+    // 2. package.json `workspaces` field (npm or yarn classic).
+    const rootPkgPath = join(projectRoot, 'package.json');
+    if (await pathExists(rootPkgPath)) {
+        const { record } = await readPackageJson(rootPkgPath);
+        if (record) {
+            const globs = extractNpmWorkspaces(record.workspaces);
+            if (globs && globs.length > 0) {
+                const paths = await expandWorkspaceGlobs(projectRoot, globs, warnings);
+                return { paths, source: 'package-json-workspaces' };
+            }
+        }
+    }
+    // 3. lerna.json `packages` field.
+    const lernaPath = join(projectRoot, 'lerna.json');
+    if (await pathExists(lernaPath)) {
+        try {
+            const lernaRaw = await readText(lernaPath);
+            const lerna = JSON.parse(lernaRaw);
+            if (Array.isArray(lerna.packages) && lerna.packages.every((p) => typeof p === 'string')) {
+                const paths = await expandWorkspaceGlobs(projectRoot, lerna.packages, warnings);
+                return { paths, source: 'lerna' };
+            }
+        }
+        catch (error) {
+            warnings.push(`lerna.json present but unreadable: ${error.message}`);
+        }
+    }
+    return { paths: [], source: null };
+}
+/**
+ * Resolve a list of workspace globs against the project tree.
+ *
+ * Supports shapes with up to two segments of `*` wildcards:
+ *   - `packages/*`
+ *   - `packages/hermes-agent/*`
+ *   - `apps/web` (literal, no wildcard)
+ *
+ * Deeper patterns (more than one `*` segment) are silently skipped and a
+ * warning is emitted. This is by design (no new dependency, narrow scope).
+ */
+async function expandWorkspaceGlobs(projectRoot, globs, warnings) {
+    const found = new Set();
+    for (const glob of globs) {
+        const segments = glob.split('/').filter((s) => s.length > 0);
+        const wildcardCount = segments.filter((s) => s === '*').length;
+        if (wildcardCount > 1) {
+            warnings.push(`workspace glob "${glob}" has more than one wildcard; skipped (unsupported).`);
+            continue;
+        }
+        if (segments.length === 0)
+            continue;
+        if (wildcardCount === 0) {
+            // Literal path — treat the last segment as a directory containing package.json.
+            const literalDir = join(projectRoot, ...segments);
+            if (await isDirectory(literalDir)) {
+                const candidate = join(literalDir, 'package.json');
+                if (await pathExists(candidate)) {
+                    found.add(candidate);
+                }
+            }
+            continue;
+        }
+        // Exactly one wildcard — it must be the LAST segment.
+        const wildcardIdx = segments.indexOf('*');
+        if (wildcardIdx !== segments.length - 1) {
+            warnings.push(`workspace glob "${glob}" has non-trailing wildcard; skipped.`);
+            continue;
+        }
+        const parentSegments = segments.slice(0, wildcardIdx);
+        const parentDir = join(projectRoot, ...parentSegments);
+        if (!(await isDirectory(parentDir)))
+            continue;
+        let entries;
+        try {
+            entries = await readdir(parentDir, { withFileTypes: true });
+        }
+        catch (error) {
+            warnings.push(`workspace glob "${glob}": could not read ${parentDir}: ${error.message}`);
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const childPkg = join(parentDir, entry.name, 'package.json');
+            if (await pathExists(childPkg)) {
+                found.add(childPkg);
+            }
+        }
+    }
+    return Array.from(found).sort();
+}
+/**
+ * Parse a single `package.json` record into `LibraryEntry` rows.
+ * Returns the entries and the per-scope tallies for that one package.
+ */
+function extractEntriesFromPackageJson(record) {
+    const byScope = {
+        dependencies: 0,
+        devDependencies: 0,
+        peerDependencies: 0,
+        optionalDependencies: 0
+    };
+    const entries = [];
+    for (const scope of SCOPES) {
+        const deps = record[scope];
+        if (!deps)
+            continue;
+        for (const [name, version] of Object.entries(deps)) {
+            entries.push({
+                name,
+                version,
+                major: parseMajorVersion(version),
+                scope,
+                ecosystem: 'npm'
+            });
+            byScope[scope] += 1;
+        }
+    }
+    return { entries, byScope };
+}
+export async function scanLibraries(options) {
+    const { projectRoot } = options;
+    const warnings = [];
+    const libraries = [];
+    const byScope = {
+        dependencies: 0,
+        devDependencies: 0,
+        peerDependencies: 0,
+        optionalDependencies: 0
+    };
+    const workspaces = [];
+    // 1. Discover monorepo workspaces (if any). Discovery is independent of
+    //    whether the root `package.json` exists; we still attempt it.
+    const { paths: workspacePkgPaths, source } = await discoverWorkspacePackageJsons(projectRoot, warnings);
+    const isMonorepo = source !== null && workspacePkgPaths.length > 0;
+    if (isMonorepo) {
+        // Monorepo mode: scan the root + every discovered workspace package.json.
+        const rootPkgPath = join(projectRoot, 'package.json');
+        const allPaths = [];
+        if (await pathExists(rootPkgPath)) {
+            allPaths.push(rootPkgPath);
+        }
+        // Dedupe: the root might also be matched by a glob (rare, but possible).
+        for (const p of workspacePkgPaths) {
+            if (!allPaths.includes(p))
+                allPaths.push(p);
+        }
+        // Recursive descent: for each discovered workspace dir, also pick up
+        // any nested `package.json` one level deeper. This matches the pnpm
+        // convention where a workspace package (e.g. `hermes-agent`) can be
+        // a container for sub-workspaces (e.g. `hermes-agent/ui-tui`). The
+        // outer pnpm-workspace.yaml often only declares the top-level glob,
+        // so a literal-glob-only scan would miss the nested packages.
+        const expanded = new Set(allPaths);
+        for (const pkgPath of allPaths) {
+            const dir = pkgPath.replace(/[\\/]package\.json$/, '');
+            if (!(await isDirectory(dir)))
+                continue;
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const nestedPkg = join(dir, entry.name, 'package.json');
+                if (await pathExists(nestedPkg)) {
+                    expanded.add(nestedPkg);
+                }
+            }
+        }
+        allPaths.length = 0;
+        allPaths.push(...Array.from(expanded).sort());
+        for (const pkgPath of allPaths) {
+            const { exists, record, error } = await readPackageJson(pkgPath);
+            if (!exists)
+                continue;
+            if (record === null) {
+                warnings.push(`${normalizePathForDisplay(pkgPath)} is not valid JSON: ${error ?? 'unknown parse error'}`);
+                continue;
+            }
+            const { entries, byScope: pkgByScope } = extractEntriesFromPackageJson(record);
+            libraries.push(...entries);
+            for (const scope of SCOPES) {
+                byScope[scope] += pkgByScope[scope];
+            }
+            // For per-workspace `workspaces[]`, only list non-root paths; the
+            // root is implicit and lives at `projectRoot`.
+            const isRoot = pkgPath === rootPkgPath;
+            if (!isRoot) {
+                const entry = {
+                    path: pkgPath,
+                    count: entries.length
+                };
+                if (record.name !== undefined)
+                    entry.name = record.name;
+                if (record.version !== undefined)
+                    entry.version = record.version;
+                workspaces.push(entry);
+            }
+        }
+    }
+    else {
+        // Single-package mode (today's behavior). Preserved byte-for-byte
+        // apart from the new additive `workspaces: []` field.
+        const { exists, record, error } = await readPackageJson(join(projectRoot, 'package.json'));
+        if (!exists) {
+            warnings.push('package.json not found; nothing to scan.');
+            return {
+                projectRoot,
+                libraries,
+                totalCount: 0,
+                byScope,
+                workspaces: [],
+                scannedAt: new Date().toISOString(),
+                warnings
+            };
+        }
+        if (record === null) {
+            warnings.push(`package.json is not valid JSON: ${error ?? 'unknown parse error'}`);
+            return {
+                projectRoot,
+                libraries,
+                totalCount: 0,
+                byScope,
+                workspaces: [],
+                scannedAt: new Date().toISOString(),
+                warnings
+            };
+        }
+        const { entries, byScope: pkgByScope } = extractEntriesFromPackageJson(record);
+        libraries.push(...entries);
+        for (const scope of SCOPES) {
+            byScope[scope] += pkgByScope[scope];
+        }
+    }
+    // Sort: by name (alphabetical), then by scope order (deps first, then dev, peer, optional)
+    libraries.sort((a, b) => {
+        if (a.name !== b.name)
+            return a.name.localeCompare(b.name);
+        return SCOPE_ORDER[a.scope] - SCOPE_ORDER[b.scope];
+    });
+    return {
+        projectRoot,
+        libraries,
+        totalCount: libraries.length,
+        byScope,
+        workspaces,
+        scannedAt: new Date().toISOString(),
+        warnings
+    };
+}
+function normalizePathForDisplay(p) {
+    // Surface posix-style separators in warnings for consistency with the
+    // existing 'package.json is not valid JSON' message shape.
+    return p.split(sep).join('/');
+}