peaks-cli 1.2.7 → 1.2.9

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/index.d.ts

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding, 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, setCurrentSessionBinding } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding } from './session-manager.js';

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

@@ -19,7 +19,32 @@ export type SessionMeta = {
     createdAt: string;
     lastActivity?: string;
     projectRoot: string;
+    /**
+     * The outer (harness / IDE / plugin) session id that
+     * `ensureSession` was called from. Sourced from
+     * `PEAKS_OUTER_SESSION_ID` env var, with `CLAUDE_CODE_SESSION_ID`
+     * as a Claude-Code fallback. Stamped once at session creation;
+     * later presence writes can compare against this to detect an
+     * outer-session swap and AskUserQuestion the user about rolling
+     * a new peaks session. Sessions predating the field simply
+     * have it undefined; presence-mismatch detection skips those
+     * (no false positives on legacy data).
+     */
+    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.
+ *
+ * Returns the id of the session that was unbound, or `null` if
+ * no binding was present. The caller is expected to do something
+ * with that — at minimum surface it in the CLI response so the
+ * user can find the directory again if they need to.
+ */
+export declare function rotateSessionBinding(projectRoot: string): string | null;
 /**
  * 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
@@ -50,14 +75,6 @@ export declare function setSessionTitle(projectRoot: string, sessionId: string,
  * Returns sessions sorted by sessionId descending (most recent first).
  */
 export declare function listSessionMetas(projectRoot: string): SessionMeta[];
-/**
- * Get or create the current session for a project.
- * If a valid session already exists, returns it.
- * Otherwise, creates a new session with auto-generated ID.
- *
- * @param projectRoot - Root directory of the project
- * @returns Session ID (e.g., "2026-05-26-session-a3f8b1")
- */
 export declare function ensureSession(projectRoot: string): Promise<string>;
 /**
  * Get the current session ID without creating a new one.
@@ -67,6 +84,34 @@ export declare function ensureSession(projectRoot: string): Promise<string>;
  * @returns Session ID or null
  */
 export declare function getSessionId(projectRoot: string): string | null;
+/**
+ * Resolve the current session id with canonicalize-on-read
+ * semantics. This is the variant the progress subcommands
+ * (step / watch / start / close) use, because the legacy
+ * `getSessionId` returns null any time the stored
+ * `projectRoot` form differs from the caller-passed form
+ * (e.g. stored is "." from inside the project dir; caller
+ * is the absolute realpath). When `getSessionId` returns
+ * null, callers like `ensureSession` create a brand-new
+ * session and overwrite the binding — which is what the
+ * user observed as the "mid-dogfood rebind" bug.
+ *
+ * The fix is to canonicalize both sides of the compare
+ * (realpath, then optionally resolve relative stored
+ * against the caller's project root). The two forms of
+ * the same physical directory now compare equal, and the
+ * existing binding is found instead of being overwritten.
+ *
+ * Use this instead of `getSessionId` only when the
+ * caller is operating on a user-supplied `--project` flag
+ * and the binding may have been written by a CLI invocation
+ * that was running from inside the project dir (the common
+ * peaks-solo / peaks-sop scenario). Other modules depend
+ * on the strict-equality semantics of `getSessionId` (the
+ * "no binding" fallback path is part of their contract),
+ * so this variant is opt-in.
+ */
+export declare function getSessionIdCanonical(projectRoot: string): string | null;
 /**
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.