peaks-cli 1.2.8 → 1.3.0

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('/');
+}

package/dist/src/services/scan/libraries-types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Library version scan types.
+ * Joins the existing scan family (archetype, existing-system, type-sanity,
+ * acceptance-coverage, diff-vs-scope, file-size) but is intentionally scoped
+ * to library version enumeration only. Does NOT extend scan-types.ts —
+ * each scan service ships its own types to keep the scan-types module
+ * focused on the archetype + existing-system pair (see src/services/scan/scan-types.ts).
+ */
+export type Ecosystem = 'npm';
+export type DependencyScope = 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies';
+export type LibraryEntry = {
+    /** npm package name (e.g. "antd", "@mui/material", "react-router-dom"). */
+    name: string;
+    /** Raw version spec as written in package.json (e.g. "^5.18.0", "workspace:*", "git+https://..."). */
+    version: string;
+    /**
+     * Parsed major version, or null when the spec is non-semver (e.g.
+     * "workspace:*", "file:../local", "git+https://..."). The LLM should
+     * treat null as "cannot determine major; consult breaking-changes table
+     * by other signals (e.g. lockfile or import statement shape)".
+     */
+    major: number | null;
+    scope: DependencyScope;
+    ecosystem: Ecosystem;
+};
+/**
+ * Per-workspace provenance for monorepo scans.
+ *
+ * `path` is the absolute path of the `package.json` that contributed
+ * libraries. `count` is the number of `LibraryEntry` rows produced by
+ * reading that single `package.json` (i.e. NOT the aggregate across
+ * the whole monorepo — use `LibraryReport.totalCount` for the aggregate).
+ *
+ * `name` and `version` are the workspace's own `name` / `version` from
+ * its `package.json`, when present. They are optional because some
+ * workspace `package.json` files omit them.
+ */
+export type WorkspaceEntry = {
+    path: string;
+    count: number;
+    name?: string;
+    version?: string;
+};
+export type LibraryReport = {
+    projectRoot: string;
+    libraries: LibraryEntry[];
+    totalCount: number;
+    byScope: Record<DependencyScope, number>;
+    /**
+     * Per-workspace provenance for monorepo (pnpm / npm / yarn workspaces,
+     * lerna) projects. Empty for single-package projects so the field is
+     * always present (additive; consumers can rely on the shape).
+     */
+    workspaces: WorkspaceEntry[];
+    /** ISO timestamp at scan time. */
+    scannedAt: string;
+    /** Soft signals — e.g. "package.json not found" or "package.json is not valid JSON". */
+    warnings: string[];
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Library version scan types.
+ * Joins the existing scan family (archetype, existing-system, type-sanity,
+ * acceptance-coverage, diff-vs-scope, file-size) but is intentionally scoped
+ * to library version enumeration only. Does NOT extend scan-types.ts —
+ * each scan service ships its own types to keep the scan-types module
+ * focused on the archetype + existing-system pair (see src/services/scan/scan-types.ts).
+ */
+export {};

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

@@ -33,11 +33,13 @@ export type SessionMeta = {
     outerSessionId?: string;
 };
 /**
- * Drop the project-level session binding (`.peaks/.session.json`)
- * so the next `ensureSession()` call auto-generates a fresh
- * session id. The on-disk session directory is left intact —
- * rotating does NOT delete the user's data, it just unbinds the
- * project from that session.
+ * Drop the project-level session binding at the canonical
+ * `.peaks/_runtime/session.json` so the next `ensureSession()` call
+ * auto-generates a fresh session id. The on-disk session directory
+ * is left intact — rotating does NOT delete the user's data, it
+ * just unbinds the project from that session. Also drops the legacy
+ * `.peaks/.session.json` if present so a stale read from another
+ * tool cannot re-bind the project after rotation.
  *
  * Returns the id of the session that was unbound, or `null` if
  * no binding was present. The caller is expected to do something

package/dist/src/services/session/session-manager.js

@@ -6,11 +6,20 @@
  * Each session gets a unique directory under .peaks/ with incrementing numbered files.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
-const SESSION_FILE = '.session.json';
+// As of slice 2026-06-05-peaks-runtime-layer the project-level session
+// binding lives under `.peaks/_runtime/session.json`. The legacy
+// `.peaks/.session.json` path is preserved as a read-only fallback for one
+// minor release so older CLI versions (or trees that have not been migrated
+// by `peaks workspace reconcile`) keep working without a forced re-init.
+const SESSION_FILE = join('_runtime', 'session.json');
+const LEGACY_SESSION_FILE = '.session.json';
 const META_FILE = 'session.json';
+function getLegacySessionFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', LEGACY_SESSION_FILE);
+}
 /**
  * Canonicalize a project root path. Returns the realpath
  * (resolving all symlinks — important on macOS where `/var`
@@ -68,7 +77,9 @@ function generateSessionId() {
     return `${date}-session-${random}`;
 }
 /**
- * Get the path to the session file for a project.
+ * Get the path to the session file for a project. The canonical home is
+ * `.peaks/_runtime/session.json`; the legacy `.peaks/.session.json` is
+ * read-only fallback (see `readSessionFile`).
  */
 function getSessionFilePath(projectRoot) {
     return join(projectRoot, '.peaks', SESSION_FILE);
@@ -92,10 +103,15 @@ function getSessionFilePath(projectRoot) {
  */
 function readSessionFile(projectRoot) {
     const sessionFile = getSessionFilePath(projectRoot);
-    if (!existsSync(sessionFile))
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` so older CLI versions or pre-migration
+    // trees keep working. When both exist, the new path wins.
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
         if (data.sessionId && data.projectRoot === projectRoot) {
             return data;
         }
@@ -116,10 +132,14 @@ function readSessionFile(projectRoot) {
  */
 function readSessionFileCanonical(projectRoot) {
     const sessionFile = getSessionFilePath(projectRoot);
-    if (!existsSync(sessionFile))
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` for one minor release.
+    const pathToRead = existsSync(sessionFile) ? sessionFile : legacyFile;
+    if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
         const storedRaw = typeof data.projectRoot === 'string' ? data.projectRoot : null;
         if (data.sessionId &&
             storedRaw !== null &&
@@ -133,22 +153,27 @@ function readSessionFileCanonical(projectRoot) {
     }
 }
 /**
- * Write session info to disk.
+ * Write session info to disk at the canonical new path
+ * `.peaks/_runtime/session.json`. The `.peaks/_runtime/` directory is
+ * created on demand. The legacy `.peaks/.session.json` is NOT written by
+ * this slice; it is only read for back-compat.
  */
 function writeSessionFile(projectRoot, info) {
     const sessionFile = getSessionFilePath(projectRoot);
-    const dir = join(projectRoot, '.peaks');
+    const dir = dirname(sessionFile);
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
 /**
- * Drop the project-level session binding (`.peaks/.session.json`)
- * so the next `ensureSession()` call auto-generates a fresh
- * session id. The on-disk session directory is left intact —
- * rotating does NOT delete the user's data, it just unbinds the
- * project from that session.
+ * Drop the project-level session binding at the canonical
+ * `.peaks/_runtime/session.json` so the next `ensureSession()` call
+ * auto-generates a fresh session id. The on-disk session directory
+ * is left intact — rotating does NOT delete the user's data, it
+ * just unbinds the project from that session. Also drops the legacy
+ * `.peaks/.session.json` if present so a stale read from another
+ * tool cannot re-bind the project after rotation.
  *
  * Returns the id of the session that was unbound, or `null` if
  * no binding was present. The caller is expected to do something
@@ -164,6 +189,15 @@ export function rotateSessionBinding(projectRoot) {
     if (existsSync(sessionFile)) {
         unlinkSync(sessionFile);
     }
+    const legacyFile = getLegacySessionFilePath(projectRoot);
+    if (existsSync(legacyFile)) {
+        try {
+            unlinkSync(legacyFile);
+        }
+        catch {
+            // best-effort: a stale legacy binding is not blocking
+        }
+    }
     return previous.sessionId;
 }
 /**