peaks-loop 3.0.0

package/dist/src/services/scan/acceptance-coverage-service.js

@@ -0,0 +1,140 @@
+import { join } from 'node:path';
+import { pathExists, readText } from '../../shared/fs.js';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+const ACCEPTANCE_SECTION_PATTERN = /^##\s+(?:Acceptance criteria|验收标准|Acceptance Criteria)\s*$/m;
+function extractAcceptanceItems(prdBody) {
+    const lines = prdBody.split(/\r?\n/);
+    const startMatch = ACCEPTANCE_SECTION_PATTERN.exec(prdBody);
+    if (startMatch === null) {
+        return [];
+    }
+    // Find the line where the header starts.
+    let headerLine = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (ACCEPTANCE_SECTION_PATTERN.test((lines[i] ?? '') + '\n')) {
+            headerLine = i;
+            break;
+        }
+    }
+    const items = [];
+    let counter = 0;
+    for (let i = headerLine + 1; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        if (/^##\s/.test(raw))
+            break; // next section
+        const bulletMatch = /^\s*-\s+(.+?)\s*$/.exec(raw);
+        if (bulletMatch === null)
+            continue;
+        const text = bulletMatch[1] ?? '';
+        if (text.length === 0)
+            continue;
+        // Skip placeholder-only bullets ("...", "<...>", etc.)
+        if (/^\.{2,}$/.test(text) || /^<[^>]+>$/.test(text))
+            continue;
+        counter += 1;
+        items.push({ id: `A${counter}`, text, line: i + 1 });
+    }
+    return items;
+}
+const TEST_CASE_HEADER_PATTERN = /^##\s+Test Case:\s*(.+?)\s*$/;
+const ACCEPTANCE_FIELD_PATTERN = /^\s*-\s+\*\*Acceptance:\*\*\s+(.+?)\s*$/i;
+function extractTestCases(qaBody) {
+    const lines = qaBody.split(/\r?\n/);
+    const cases = [];
+    let current = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        const headerMatch = TEST_CASE_HEADER_PATTERN.exec(raw);
+        if (headerMatch !== null) {
+            if (current !== null) {
+                cases.push({ title: current.title, acceptanceIds: current.ids, line: current.line });
+            }
+            current = { title: (headerMatch[1] ?? '').trim(), line: i + 1, ids: [] };
+            continue;
+        }
+        if (current === null)
+            continue;
+        const acceptanceMatch = ACCEPTANCE_FIELD_PATTERN.exec(raw);
+        if (acceptanceMatch !== null) {
+            const refs = (acceptanceMatch[1] ?? '').split(/[,\s]+/).map((part) => part.trim()).filter((part) => part.length > 0);
+            current.ids.push(...refs);
+        }
+    }
+    if (current !== null) {
+        cases.push({ title: current.title, acceptanceIds: current.ids, line: current.line });
+    }
+    return cases;
+}
+function buildCoverage(items, cases) {
+    const itemMap = new Map();
+    for (const item of items)
+        itemMap.set(item.id, item);
+    const coverageMap = new Map();
+    for (const item of items)
+        coverageMap.set(item.id, []);
+    const invalidReferences = [];
+    for (const testCase of cases) {
+        for (const ref of testCase.acceptanceIds) {
+            const normalized = ref.toUpperCase();
+            if (!itemMap.has(normalized)) {
+                invalidReferences.push({ testCaseTitle: testCase.title, reference: ref });
+                continue;
+            }
+            coverageMap.get(normalized)?.push(testCase.title);
+        }
+    }
+    const coverage = items.map((item) => ({
+        acceptanceId: item.id,
+        acceptanceText: item.text,
+        testCases: coverageMap.get(item.id) ?? []
+    }));
+    const uncovered = items.filter((item) => (coverageMap.get(item.id) ?? []).length === 0);
+    return { coverage, uncovered, invalidReferences };
+}
+export async function getAcceptanceCoverage(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'prd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const prdArtifact = await showRequestArtifact(showOptions);
+    if (prdArtifact === null) {
+        return { kind: 'prd-not-found' };
+    }
+    // As of slice 2026-06-05-change-id-as-unit-of-work, test-cases live
+    // under the same change-id dir as the PRD itself (the on-disk scope),
+    // not under the body's `- session:` line. Slice
+    // 2026-06-29-change-id-root-removal stripped the legacy
+    // `.peaks/_runtime/change/<id>/` indirection — test-cases now live
+    // under the canonical session dir `.peaks/_runtime/<sid>/qa/test-cases/`.
+    // `prdArtifact.sessionId` is the bare session id (the dir the PRD was
+    // found in), so we route through `_runtime/` here.
+    const sessionId = prdArtifact.sessionId;
+    const testCasesPath = join(options.projectRoot, '.peaks', '_runtime', sessionId, 'qa', 'test-cases', `${options.requestId}.md`);
+    if (!(await pathExists(testCasesPath))) {
+        return { kind: 'test-cases-not-found', expectedPath: testCasesPath };
+    }
+    const qaBody = await readText(testCasesPath);
+    const acceptanceItems = extractAcceptanceItems(prdArtifact.content);
+    const testCases = extractTestCases(qaBody);
+    const { coverage, uncovered, invalidReferences } = buildCoverage(acceptanceItems, testCases);
+    const unlinkedTestCases = testCases.filter((testCase) => testCase.acceptanceIds.length === 0);
+    const ok = uncovered.length === 0 && invalidReferences.length === 0 && acceptanceItems.length > 0;
+    return {
+        ok,
+        prdPath: prdArtifact.path,
+        testCasesPath,
+        acceptanceItems,
+        testCases,
+        coverage,
+        uncovered,
+        unlinkedTestCases,
+        invalidReferences
+    };
+}
+export function isAcceptanceCoverageError(value) {
+    return value.kind !== undefined;
+}

package/dist/src/services/scan/api-surface-service.d.ts

@@ -0,0 +1,69 @@
+/**
+ * API surface scan service.
+ *
+ * Walks the project for CLI subcommands, service-level public exports,
+ * public types, and module-level constants. Output feeds the tech-doc
+ * "Existing API / Component Inventory" section. Read-only — no writes.
+ *
+ * Pattern follows `libraries-service.ts` (readFileSync + readdir; pure
+ * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
+ */
+export type ApiSurfaceOptions = {
+    projectRoot: string;
+    /** Maximum entries per kind in output (after filtering). */
+    maxPerKind?: number;
+    /** Comma-separated globs (substring match) to limit the walk. */
+    includeDirs?: string;
+};
+export type CliEntry = {
+    name: string;
+    description: string;
+    sourceFile: string;
+};
+export type ServiceEntry = {
+    name: string;
+    kind: 'function' | 'class' | 'const';
+    isAsync: boolean;
+    sourceFile: string;
+    line: number;
+};
+export type TypeEntry = {
+    name: string;
+    kind: 'interface' | 'type' | 'enum';
+    sourceFile: string;
+    line: number;
+};
+export type ConstantEntry = {
+    name: string;
+    sourceFile: string;
+    line: number;
+};
+export type ApiSurfaceReport = {
+    projectRoot: string;
+    scannedAt: string;
+    counts: {
+        cli: number;
+        service: number;
+        type: number;
+        constant: number;
+    };
+    cli: CliEntry[];
+    service: ServiceEntry[];
+    type: TypeEntry[];
+    constant: ConstantEntry[];
+    warnings: string[];
+};
+/**
+ * Scan the project for API surfaces. Read-only. Never throws; failures
+ * surface as warnings in the report.
+ */
+export declare function scanApiSurface(options: ApiSurfaceOptions): Promise<ApiSurfaceReport>;
+export declare function formatApiSurfaceMarkdown(report: ApiSurfaceReport, opts?: {
+    maxPerKind?: number;
+    truncatedCounts?: {
+        cli: number;
+        service: number;
+        type: number;
+        constant: number;
+    };
+}): string;

package/dist/src/services/scan/api-surface-service.js

@@ -0,0 +1,239 @@
+/**
+ * API surface scan service.
+ *
+ * Walks the project for CLI subcommands, service-level public exports,
+ * public types, and module-level constants. Output feeds the tech-doc
+ * "Existing API / Component Inventory" section. Read-only — no writes.
+ *
+ * Pattern follows `libraries-service.ts` (readFileSync + readdir; pure
+ * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const DEFAULT_DIRS = ['src/cli', 'src/services'];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+const COMMAND_RE = /\.command\(\s*['"]([^'"]+)['"]\s*\)\s*\.description\(\s*['"]([^'"]+)['"]/g;
+const EXPORT_FUNCTION_RE = /^export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_CLASS_RE = /^export\s+class\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_CONST_RE = /^export\s+const\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_INTERFACE_RE = /^export\s+interface\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_TYPE_RE = /^export\s+type\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_ENUM_RE = /^export\s+enum\s+([A-Za-z_$][\w$]*)/gm;
+async function walkProject(projectRoot, includeDirs) {
+    const files = [];
+    for (const rel of includeDirs) {
+        const abs = join(projectRoot, rel);
+        if (!(await isDir(abs)))
+            continue;
+        await walkDir(abs, projectRoot, files);
+    }
+    return files;
+}
+async function walkDir(dir, projectRoot, out) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walkDir(full, projectRoot, out);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+            out.push(relative(projectRoot, full));
+        }
+    }
+}
+async function isDir(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function lineOf(content, matchIndex) {
+    return content.slice(0, matchIndex).split('\n').length;
+}
+function uniqueByName(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item.name))
+            continue;
+        seen.add(item.name);
+        out.push(item);
+    }
+    return out;
+}
+function parseIncludeDirs(raw) {
+    if (!raw)
+        return [...DEFAULT_DIRS];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Scan the project for API surfaces. Read-only. Never throws; failures
+ * surface as warnings in the report.
+ */
+export async function scanApiSurface(options) {
+    const includeDirs = parseIncludeDirs(options.includeDirs);
+    const maxPerKind = options.maxPerKind ?? Number.POSITIVE_INFINITY;
+    const warnings = [];
+    const files = await walkProject(options.projectRoot, includeDirs);
+    const cli = [];
+    const service = [];
+    const types = [];
+    const constants = [];
+    for (const rel of files) {
+        const full = join(options.projectRoot, rel);
+        let content;
+        try {
+            content = await readFile(full, 'utf8');
+        }
+        catch (error) {
+            warnings.push(`unreadable: ${rel}: ${error.message}`);
+            continue;
+        }
+        if (rel.startsWith('src/cli/commands/')) {
+            let m;
+            COMMAND_RE.lastIndex = 0;
+            while ((m = COMMAND_RE.exec(content)) !== null) {
+                cli.push({
+                    name: m[1],
+                    description: m[2].slice(0, 120),
+                    sourceFile: rel
+                });
+            }
+        }
+        if (rel.startsWith('src/services/')) {
+            for (const re of [EXPORT_FUNCTION_RE, EXPORT_CLASS_RE, EXPORT_CONST_RE,
+                EXPORT_INTERFACE_RE, EXPORT_TYPE_RE, EXPORT_ENUM_RE]) {
+                re.lastIndex = 0;
+            }
+            let m;
+            while ((m = EXPORT_FUNCTION_RE.exec(content)) !== null) {
+                service.push({
+                    name: m[1],
+                    kind: 'function',
+                    isAsync: /export\s+async\s+function/.test(content.slice(Math.max(0, m.index - 10), m.index + 30)),
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_CLASS_RE.exec(content)) !== null) {
+                service.push({
+                    name: m[1],
+                    kind: 'class',
+                    isAsync: false,
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_INTERFACE_RE.exec(content)) !== null) {
+                types.push({
+                    name: m[1],
+                    kind: 'interface',
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_TYPE_RE.exec(content)) !== null) {
+                types.push({
+                    name: m[1],
+                    kind: 'type',
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_ENUM_RE.exec(content)) !== null) {
+                types.push({
+                    name: m[1],
+                    kind: 'enum',
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_CONST_RE.exec(content)) !== null) {
+                constants.push({
+                    name: m[1],
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+        }
+    }
+    const cliUnique = uniqueByName(cli).sort((a, b) => a.name.localeCompare(b.name));
+    const serviceUnique = uniqueByName(service).sort((a, b) => a.sourceFile.localeCompare(b.sourceFile) || a.name.localeCompare(b.name));
+    const typeUnique = uniqueByName(types).sort((a, b) => a.name.localeCompare(b.name));
+    const constantUnique = uniqueByName(constants).sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        projectRoot: options.projectRoot,
+        scannedAt: new Date().toISOString(),
+        counts: {
+            cli: cliUnique.length,
+            service: serviceUnique.length,
+            type: typeUnique.length,
+            constant: constantUnique.length
+        },
+        cli: Number.isFinite(maxPerKind) ? cliUnique.slice(0, maxPerKind) : cliUnique,
+        service: Number.isFinite(maxPerKind) ? serviceUnique.slice(0, maxPerKind) : serviceUnique,
+        type: Number.isFinite(maxPerKind) ? typeUnique.slice(0, maxPerKind) : typeUnique,
+        constant: Number.isFinite(maxPerKind) ? constantUnique.slice(0, maxPerKind) : constantUnique,
+        warnings
+    };
+}
+export function formatApiSurfaceMarkdown(report, opts = {}) {
+    const max = opts.maxPerKind ?? Number.POSITIVE_INFINITY;
+    const truncated = opts.truncatedCounts;
+    const lines = [];
+    lines.push('## API surface inventory');
+    lines.push('');
+    lines.push(`**Project:** ${report.projectRoot}`);
+    lines.push(`**Generated:** ${report.scannedAt}`);
+    lines.push(`**Counts:** cli=${report.counts.cli} service=${report.counts.service} type=${report.counts.type} constant=${report.counts.constant}`);
+    lines.push('');
+    const sections = [
+        ['CLI subcommands', report.counts.cli, (n) => `\`peaks ${n}\``],
+        ['Service exports', report.counts.service, (n) => `\`${n}\``],
+        ['Public types', report.counts.type, (n) => `\`${n}\``],
+        ['Module constants', report.counts.constant, (n) => `\`${n}\``]
+    ];
+    const arrays = [report.cli, report.service, report.type, report.constant];
+    const trunc = truncated
+        ? [truncated.cli - report.cli.length, truncated.service - report.service.length, truncated.type - report.type.length, truncated.constant - report.constant.length]
+        : [0, 0, 0, 0];
+    for (let i = 0; i < sections.length; i++) {
+        const [title, count, fmt] = sections[i];
+        const arr = arrays[i];
+        const more = trunc[i];
+        lines.push(`### ${title} (${count})`);
+        lines.push('');
+        for (const entry of arr) {
+            if (title === 'CLI subcommands') {
+                const e = entry;
+                lines.push(`- ${fmt(e.name)} — ${e.description}`);
+            }
+            else if (title === 'Service exports') {
+                const e = entry;
+                lines.push(`- \`${e.sourceFile}:${e.name}\` — ${e.isAsync ? 'async ' : ''}${e.kind}`);
+            }
+            else {
+                const e = entry;
+                lines.push(`- ${fmt(e.name)} — \`${e.kind ?? 'const'}\` (from \`${e.sourceFile}\`)`);
+            }
+        }
+        if (more > 0) {
+            lines.push(`- ... and ${more} more`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/src/services/scan/archetype-service.d.ts

@@ -0,0 +1,5 @@
+import type { ArchetypeReport } from './scan-types.js';
+export type ArchetypeScanOptions = {
+    projectRoot: string;
+};
+export declare function scanArchetype(options: ArchetypeScanOptions): Promise<ArchetypeReport>;

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

@@ -0,0 +1,242 @@
+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 };
+    }
+    if (detected.hasMonorepoConfig && !hasBackend) {
+        return { archetype: '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 };
+}