peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/dist/services/runtime/vendors/copilot.js

@@ -0,0 +1,40 @@
+/**
+ * Copilot vendor adapter — slice S2-a.
+ *
+ * Stub adapter (PRD out-of-scope: full implementation lands in a
+ * future slice). Copilot's compact verb is `copilot compact`
+ * (subcommand form, not `--compact` flag — different from Claude
+ * Code + Codex). The adapter encapsulates that verb here so the
+ * runtime service + CLI never see it.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export class CopilotAdapter {
+    id = 'copilot';
+    displayName = 'GitHub Copilot';
+    async detect() {
+        if (process.env.GITHUB_COPILOT === '1' || process.env.GITHUB_COPILOT === 'true')
+            return true;
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        return home.length > 0 && existsSync(join(home, '.copilot'));
+    }
+    async compact(args = {}) {
+        const argv = ['compact'];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn('copilot', argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+            proc.on('error', (err) => {
+                resolveRun({ exitCode: 127, stdout, stderr: stderr + (stderr.length > 0 ? '\n' : '') + err.message });
+            });
+            proc.on('close', (code) => {
+                resolveRun({ exitCode: code ?? 0, stdout, stderr });
+            });
+        });
+    }
+}

package/dist/services/scan/archetype-service.js

@@ -0,0 +1,254 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+const BACKEND_DEP_NAMES = [
+    'express',
+    'koa',
+    'fastify',
+    '@nestjs/core',
+    '@nestjs/common',
+    'hapi',
+    '@hapi/hapi',
+    'restify',
+    'next' // treated separately for API routes
+];
+const BACKEND_DIR_CANDIDATES = ['server', 'backend', 'api', 'apps/server', 'apps/api', 'packages/server', 'packages/api'];
+const MONOREPO_CONFIG_FILES = ['pnpm-workspace.yaml', 'lerna.json', 'turbo.json', 'nx.json', 'rush.json'];
+const SWAGGER_CANDIDATE_PATHS = [
+    'swagger.json',
+    'swagger.yaml',
+    'openapi.json',
+    'openapi.yaml',
+    'openapi.yml',
+    'docs/swagger.json',
+    'docs/openapi.json',
+    'docs/openapi.yaml'
+];
+async function readPackageJsonDeps(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!(await pathExists(pkgPath))) {
+        return { exists: false, deps: {} };
+    }
+    try {
+        const raw = await readText(pkgPath);
+        const parsed = JSON.parse(raw);
+        const deps = {
+            ...(parsed.dependencies ?? {}),
+            ...(parsed.devDependencies ?? {}),
+            ...(parsed.peerDependencies ?? {}),
+            ...(parsed.optionalDependencies ?? {})
+        };
+        return { exists: true, deps };
+    }
+    catch {
+        return { exists: true, deps: {} };
+    }
+}
+async function detectBackendFrameworks(deps) {
+    return BACKEND_DEP_NAMES.filter((name) => name !== 'next' && Object.prototype.hasOwnProperty.call(deps, name));
+}
+async function detectNextApiRoutes(projectRoot, hasNext) {
+    if (!hasNext) {
+        return false;
+    }
+    const candidates = ['pages/api', 'src/pages/api', 'app/api', 'src/app/api'];
+    for (const candidate of candidates) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function detectBackendDirs(projectRoot) {
+    const found = [];
+    for (const candidate of BACKEND_DIR_CANDIDATES) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            found.push(candidate);
+        }
+    }
+    return found;
+}
+async function detectSwagger(projectRoot) {
+    const found = [];
+    for (const candidate of SWAGGER_CANDIDATE_PATHS) {
+        if (await pathExists(join(projectRoot, candidate))) {
+            found.push(candidate);
+        }
+    }
+    const protoDir = join(projectRoot, 'proto');
+    if (await isDirectory(protoDir)) {
+        found.push('proto/');
+    }
+    return found;
+}
+async function detectMonorepoConfigs(projectRoot) {
+    const found = [];
+    for (const file of MONOREPO_CONFIG_FILES) {
+        if (await pathExists(join(projectRoot, file))) {
+            found.push(file);
+        }
+    }
+    return found;
+}
+async function countSrcFiles(projectRoot, max = 500) {
+    const srcDir = join(projectRoot, 'src');
+    if (!(await isDirectory(srcDir))) {
+        return 0;
+    }
+    let count = 0;
+    const queue = [srcDir];
+    while (queue.length > 0 && count < max) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(full);
+            }
+            else if (/\.(tsx?|jsx?|vue|svelte)$/.test(entry.name)) {
+                count += 1;
+                if (count >= max)
+                    break;
+            }
+        }
+    }
+    return count;
+}
+async function lockfileAgeDays(projectRoot) {
+    const candidates = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb'];
+    for (const candidate of candidates) {
+        const full = join(projectRoot, candidate);
+        if (await pathExists(full)) {
+            const stats = await stat(full);
+            const ageMs = Date.now() - stats.mtimeMs;
+            return Math.floor(ageMs / (1000 * 60 * 60 * 24));
+        }
+    }
+    return null;
+}
+function decideArchetype(detected) {
+    const signals = [];
+    const hasBackend = detected.hasBackendFramework || detected.hasNextApiRoutes || detected.backendDirsPresent.length > 0;
+    signals.push({
+        name: 'backend-presence',
+        matched: hasBackend,
+        detail: hasBackend
+            ? [
+                detected.backendFrameworks.length > 0 ? `framework: ${detected.backendFrameworks.join(', ')}` : null,
+                detected.hasNextApiRoutes ? 'next-api-routes' : null,
+                detected.backendDirsPresent.length > 0 ? `dirs: ${detected.backendDirsPresent.join(', ')}` : null
+            ]
+                .filter(Boolean)
+                .join('; ')
+            : 'no backend framework, no next API routes, no backend dirs'
+    });
+    signals.push({
+        name: 'swagger-or-proto',
+        matched: detected.hasSwaggerOrProto,
+        detail: detected.hasSwaggerOrProto ? detected.swaggerPaths.join(', ') : 'no swagger/openapi/proto'
+    });
+    signals.push({
+        name: 'monorepo-config',
+        matched: detected.hasMonorepoConfig,
+        detail: detected.hasMonorepoConfig ? detected.monorepoConfigs.join(', ') : 'no monorepo config'
+    });
+    signals.push({
+        name: 'src-size',
+        matched: detected.srcFileCount >= 20,
+        detail: `${detected.srcFileCount} source files in src/`
+    });
+    signals.push({
+        name: 'lockfile-age',
+        matched: detected.lockfileAgeDays !== null && detected.lockfileAgeDays > 180,
+        detail: detected.lockfileAgeDays === null ? 'no lockfile' : `${detected.lockfileAgeDays} days`
+    });
+    if (!detected.hasPackageJson) {
+        return { archetype: 'unknown', confidence: 'low', signals };
+    }
+    // Monorepo detection runs BEFORE the backend check: a monorepo with
+    // a packages/server dir is a fullstack-monorepo, NOT legacy-fullstack.
+    // Slice 2026-07-15 ice-cola hot-fix: previously a monorepo with a
+    // backend sub-package fell through to `legacy-fullstack` because
+    // `hasBackend` includes `backendDirsPresent.length > 0`, which the
+    // L199 guard above couldn't handle. We now treat `hasMonorepoConfig`
+    // as a top-level classifier: any monorepo with a backend sub-package
+    // is `fullstack-monorepo`; without a backend it is `frontend-monorepo`.
+    if (detected.hasMonorepoConfig) {
+        return {
+            archetype: hasBackend ? 'fullstack-monorepo' : 'frontend-monorepo',
+            confidence: 'high',
+            signals
+        };
+    }
+    if (hasBackend && detected.srcFileCount >= 20) {
+        return { archetype: 'legacy-fullstack', confidence: 'high', signals };
+    }
+    const greenfieldSignals = [
+        detected.srcFileCount < 20,
+        detected.lockfileAgeDays === null || detected.lockfileAgeDays <= 30,
+        !detected.hasSwaggerOrProto
+    ];
+    const greenfieldSignalCount = greenfieldSignals.filter(Boolean).length;
+    // Greenfield must show both a small src AND a fresh/missing lockfile — otherwise an empty-src legacy stub still looks like greenfield.
+    if (!hasBackend && greenfieldSignals[0] === true && greenfieldSignals[1] === true) {
+        return { archetype: 'greenfield', confidence: greenfieldSignalCount === 3 ? 'high' : 'medium', signals };
+    }
+    const legacySignalCount = [
+        !hasBackend,
+        !detected.hasSwaggerOrProto,
+        (detected.lockfileAgeDays !== null && detected.lockfileAgeDays > 180) || detected.srcFileCount >= 20
+    ].filter(Boolean).length;
+    if (!hasBackend && legacySignalCount >= 2) {
+        return { archetype: 'legacy-frontend', confidence: legacySignalCount === 3 ? 'high' : 'medium', signals };
+    }
+    if (hasBackend) {
+        return { archetype: 'legacy-fullstack', confidence: 'medium', signals };
+    }
+    return { archetype: 'unknown', confidence: 'low', signals };
+}
+function decideFrontendOnly(report) {
+    if (report.archetype === 'legacy-frontend' || report.archetype === 'frontend-monorepo') {
+        return { frontendOnly: true, reason: `archetype=${report.archetype}` };
+    }
+    const noBackend = !report.detected.hasBackendFramework && !report.detected.hasNextApiRoutes && report.detected.backendDirsPresent.length === 0;
+    if (noBackend && !report.detected.hasSwaggerOrProto) {
+        return { frontendOnly: true, reason: 'no-backend-no-swagger' };
+    }
+    if (report.detected.hasBackendFramework || report.detected.hasNextApiRoutes || report.detected.backendDirsPresent.length > 0) {
+        return { frontendOnly: false, reason: 'backend-detected' };
+    }
+    return { frontendOnly: false, reason: 'swagger-or-proto-present' };
+}
+export async function scanArchetype(options) {
+    const { projectRoot } = options;
+    const { exists: hasPackageJson, deps } = await readPackageJsonDeps(projectRoot);
+    const backendFrameworks = await detectBackendFrameworks(deps);
+    const hasNext = Object.prototype.hasOwnProperty.call(deps, 'next');
+    const hasNextApiRoutes = await detectNextApiRoutes(projectRoot, hasNext);
+    const backendDirsPresent = await detectBackendDirs(projectRoot);
+    const swaggerPaths = await detectSwagger(projectRoot);
+    const monorepoConfigs = await detectMonorepoConfigs(projectRoot);
+    const srcFileCount = await countSrcFiles(projectRoot);
+    const ageDays = await lockfileAgeDays(projectRoot);
+    const detected = {
+        hasPackageJson,
+        hasBackendFramework: backendFrameworks.length > 0,
+        backendFrameworks,
+        hasSwaggerOrProto: swaggerPaths.length > 0,
+        swaggerPaths,
+        hasMonorepoConfig: monorepoConfigs.length > 0,
+        monorepoConfigs,
+        hasNextApiRoutes,
+        srcFileCount,
+        backendDirsPresent,
+        lockfileAgeDays: ageDays
+    };
+    const { archetype, confidence, signals } = decideArchetype(detected);
+    const base = { archetype, confidence, signals, detected };
+    const { frontendOnly, reason } = decideFrontendOnly(base);
+    return { ...base, frontendOnly, frontendOnlyReason: reason };
+}

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;