peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/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 'peaks-loop-shared/fs';
+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/services/scan/scan-types.d.ts

@@ -0,0 +1,59 @@
+export type ProjectArchetype = 'greenfield' | 'legacy-frontend' | 'legacy-fullstack' | 'frontend-monorepo' | 'fullstack-monorepo' | 'unknown';
+export type ArchetypeSignal = {
+    name: string;
+    matched: boolean;
+    detail?: string;
+};
+export type ArchetypeReport = {
+    archetype: ProjectArchetype;
+    confidence: 'high' | 'medium' | 'low';
+    frontendOnly: boolean;
+    frontendOnlyReason: string;
+    signals: ArchetypeSignal[];
+    detected: {
+        hasPackageJson: boolean;
+        hasBackendFramework: boolean;
+        backendFrameworks: string[];
+        hasSwaggerOrProto: boolean;
+        swaggerPaths: string[];
+        hasMonorepoConfig: boolean;
+        monorepoConfigs: string[];
+        hasNextApiRoutes: boolean;
+        srcFileCount: number;
+        backendDirsPresent: string[];
+        lockfileAgeDays: number | null;
+    };
+};
+export type VisualTokenSource = {
+    path: string;
+    kind: 'less-vars' | 'sass-vars' | 'css-vars' | 'tailwind-config' | 'antd-config-provider' | 'theme-file';
+};
+export type VisualToken = {
+    name: string;
+    value: string;
+    source: string;
+};
+export type ConventionSample = {
+    path: string;
+    kind: 'component' | 'service' | 'hook' | 'page';
+};
+export type ExistingSystemReport = {
+    archetype: ProjectArchetype;
+    scanned: boolean;
+    scanSkippedReason?: string;
+    visualTokens: {
+        colors: VisualToken[];
+        spacing: VisualToken[];
+        typography: VisualToken[];
+        radii: VisualToken[];
+        sources: VisualTokenSource[];
+    };
+    conventions: {
+        componentNaming: 'PascalCase' | 'kebab-case' | 'mixed' | 'unknown';
+        componentDir: string | null;
+        serviceDir: string | null;
+        hookDir: string | null;
+        samples: ConventionSample[];
+    };
+    inconsistencies: string[];
+};

package/dist/services/share/bundle-reader.d.ts

@@ -0,0 +1,100 @@
+/**
+ * bundle-reader.ts — readBundle(inPath) (spec §7A.2).
+ *
+ * M7 / spec §7A.2 / §10 RL-9 / acceptance AC-25 / AC-26.
+ *
+ * Reads a `peaks.bundle/1` tar.gz and lands the contained release
+ * on the local SkillHub. The reader is the symmetrical counterpart
+ * of `bundle-writer.ts` — same layout, same content-addressed
+ * blobs/, but with three hard guards:
+ *
+ *   1. `format_version_major !== 1` is a HARD block. The reader
+ *      throws `SHARE_BUNDLE_MAJOR_VERSION_MISMATCH` before any
+ *      SQL side-effect. (Major-version bumps are reserved for
+ *      breaking schema changes; the receiver is not assumed to
+ *      know how to translate.)
+ *   2. `format_version_minor` mismatch is a non-fatal warn (the
+ *      reader collects it as a warning on the return envelope).
+ *   3. The imported release ALWAYS lands as `candidate`. The
+ *      reader refuses to write any other status; the receiver
+ *      MUST run an independent evaluation before promoting the
+ *      imported release to `stable` (AC-26 — peaks loop promote
+ *      reads evolution_evaluation rows).
+ *
+ * The reader is also the integration point for AC-26 — the loop
+ * promote path (which lives in a future slice / CLI command) checks
+ * `evolution_evaluation.independent_scorer_verdict` before allowing
+ * a candidate → stable transition; this slice does not add a new
+ * `peaks loop promote` because `peaks asset crystallize` already
+ * enforces the brief-section + pre-run gates and creates the
+ * initial `candidate` row. The integration test for AC-26 verifies
+ * that a freshly imported bundle has no `evolution_evaluation`
+ * row and that promotion therefore cannot proceed.
+ */
+import type Database from "better-sqlite3";
+import { SHARE_BUNDLE_ERROR_CODES, type PeaksBundleKind } from "./bundle-types.js";
+/**
+ * Thrown when `format_version_major !== 1`. This is the explicit
+ * HARD block per spec §7A.2 (major mismatch).
+ */
+export declare class BundleMajorVersionMismatchError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.MAJOR_VERSION_MISMATCH;
+    readonly receivedMajor: number;
+    constructor(receivedMajor: number);
+}
+/**
+ * Thrown when the schema-versions mapping is missing or carries
+ * non-canonical literals.
+ */
+export declare class BundleSchemaVersionsMismatchError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.SCHEMA_VERSIONS_MISMATCH;
+    readonly received: Record<string, unknown> | undefined;
+    constructor(received: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when the caller asks to land as anything other than
+ * `candidate` (the only allowed target status).
+ */
+export declare class BundleImportToStableForbiddenError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.IMPORT_TO_STABLE_FORBIDDEN;
+    constructor(receivedStatus: string);
+}
+/**
+ * Thrown when the bundle tarball is malformed (no manifest.json,
+ * bad JSON, etc.). Distinct from a ZodError so the CLI can map
+ * to a single BUNDLE_MALFORMED code.
+ */
+export declare class BundleMalformedError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.BUNDLE_MALFORMED;
+    constructor(message: string);
+}
+export type ReadBundleArgs = {
+    db: Database.Database;
+    /** Blobs root for content-addressed file write-back. */
+    blobsDir: string;
+    /** Input `.tar.gz` bundle path. */
+    inPath: string;
+    /**
+     * Optional rename for the anchor asset on import. For `loop`
+     * bundles this is the loop id to overwrite the source id; for
+     * `bee` bundles this is the `--as` bee name.
+     */
+    asName?: string;
+};
+/**
+ * Successful read result. The reader lands the bundle as a
+ * `candidate` regardless of any other lifecycle status on the
+ * source — this is the hard import rule per spec §7A.2 / AC-25.
+ */
+export type ReadBundleResult = {
+    /** Anchor asset id actually written. */
+    assetId: string | number;
+    kind: PeaksBundleKind;
+    /** Always `candidate` — the reader does not honor any other status. */
+    importedAs: "candidate";
+    /** Non-fatal warnings (e.g. minor-version mismatch). */
+    warnings: string[];
+    /** Count of crystallization_event rows imported. */
+    evidenceBriefCount: number;
+};
+export declare function readBundle(args: ReadBundleArgs): ReadBundleResult;