peaks-loop 4.0.0-beta.3 → 4.0.0-beta.30

package/dist/services/runtime/runtime-service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime service — slice S2-a of RD-2.
+ *
+ * Orchestrator that wires the runtime detector + vendor adapter
+ * registry into a small surface that the CLI commands call. The
+ * service owns the canonical list of built-in adapters (claude-code /
+ * codex / copilot) and decides which adapter handles a given
+ * `--via <id>` request.
+ *
+ * Design notes (Karpathy #2 Simplicity First):
+ *
+ *  - The service is a thin orchestrator — it does NOT contain any
+ *    vendor verb strings (claude / codex / copilot). All vendor verbs
+ *    live in `src/services/runtime/vendors/<vendor>.ts`. Verified by
+ *    AC-1.
+ *  - When `compactVia(id)` is called with an unknown id, the service
+ *    returns a "no-op" result with exitCode=0 and a warning instead of
+ *    throwing — vendor-neutrality means peaks-loop MUST keep working
+ *    even when the requested vendor adapter isn't registered.
+ *  - The service is the SOLE owner of the built-in adapter list. Tests
+ *    and CLI commands should never instantiate adapters directly;
+ *    they should call `listBuiltInAdapters()` or `getAdapter(id)`.
+ */
+import type { VendorAdapter, VendorCompactResult } from './vendor-adapter.js';
+export interface RuntimeServiceOptions {
+    /** Override the built-in adapter list (used by tests + the
+     *  adapter-registry's `register()` flow). */
+    readonly builtIns?: VendorAdapter[];
+    /** Override the home dir used by adapter detect() helpers. */
+    readonly home?: string;
+}
+/** Pure orchestrator. The runtime service holds built-in adapters as
+ *  the baseline registry; the AdapterRegistry layer (`src/services/
+ *  adapter/adapter-registry.ts`) extends this baseline at runtime via
+ *  user-registered adapters persisted to `.peaks/runtime/adapters.json`.
+ *  The two layers are intentionally separate:
+ *    - runtime-service: built-in vendor adapters for the runtime-detect
+ *      compact flow (S2-a).
+ *    - adapter-registry: persisted user-registered adapters (S2-a).
+ *  runtime-service itself does NOT consult the adapter registry —
+ *  callers (`peaks runtime compact --via <id>`) layer them: first look
+ *  up the id in the persisted registry, fall back to the built-in list.
+ */
+export declare class RuntimeService {
+    private readonly builtIns;
+    constructor(opts?: RuntimeServiceOptions);
+    /** Return all built-in adapters. Order: claude-code, codex, copilot. */
+    listBuiltInAdapters(): VendorAdapter[];
+    /** Resolve a built-in adapter by id. Returns undefined when not
+     *  found — caller should fall back to adapter registry or unknown. */
+    getBuiltInAdapter(id: string): VendorAdapter | undefined;
+    /** Compact via a built-in adapter. When the id is unknown, returns
+     *  a no-op result with a warning rather than throwing — vendor
+     *  neutrality demands peaks-loop stay alive even when a vendor is
+     *  not wired up. */
+    compactVia(id: string, force: boolean | undefined): Promise<VendorCompactResult & {
+        warning?: string;
+    }>;
+}

package/dist/services/runtime/runtime-service.js

@@ -0,0 +1,51 @@
+import { ClaudeCodeAdapter } from './vendors/claude-code.js';
+import { CodexAdapter } from './vendors/codex.js';
+import { CopilotAdapter } from './vendors/copilot.js';
+const DEFAULT_BUILT_INS = [
+    new ClaudeCodeAdapter(),
+    new CodexAdapter(),
+    new CopilotAdapter()
+];
+/** Pure orchestrator. The runtime service holds built-in adapters as
+ *  the baseline registry; the AdapterRegistry layer (`src/services/
+ *  adapter/adapter-registry.ts`) extends this baseline at runtime via
+ *  user-registered adapters persisted to `.peaks/runtime/adapters.json`.
+ *  The two layers are intentionally separate:
+ *    - runtime-service: built-in vendor adapters for the runtime-detect
+ *      compact flow (S2-a).
+ *    - adapter-registry: persisted user-registered adapters (S2-a).
+ *  runtime-service itself does NOT consult the adapter registry —
+ *  callers (`peaks runtime compact --via <id>`) layer them: first look
+ *  up the id in the persisted registry, fall back to the built-in list.
+ */
+export class RuntimeService {
+    builtIns;
+    constructor(opts = {}) {
+        this.builtIns = opts.builtIns ?? [...DEFAULT_BUILT_INS];
+    }
+    /** Return all built-in adapters. Order: claude-code, codex, copilot. */
+    listBuiltInAdapters() {
+        return [...this.builtIns];
+    }
+    /** Resolve a built-in adapter by id. Returns undefined when not
+     *  found — caller should fall back to adapter registry or unknown. */
+    getBuiltInAdapter(id) {
+        return this.builtIns.find((a) => a.id === id);
+    }
+    /** Compact via a built-in adapter. When the id is unknown, returns
+     *  a no-op result with a warning rather than throwing — vendor
+     *  neutrality demands peaks-loop stay alive even when a vendor is
+     *  not wired up. */
+    async compactVia(id, force) {
+        const adapter = this.getBuiltInAdapter(id);
+        if (adapter === undefined) {
+            return {
+                exitCode: 0,
+                stdout: '',
+                stderr: '',
+                warning: `no built-in adapter registered for id="${id}" — falling back to no-op; use \`peaks adapter register --id ${id} --binary <cmd>\` to wire one`
+            };
+        }
+        return adapter.compact({ force: force === true });
+    }
+}

package/dist/services/runtime/vendor-adapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Vendor adapter contract — slice S2-a of RD-2 (2026-07-08 session).
+ *
+ * Each `VendorAdapter` is a thin wrapper around ONE AI runtime (Claude
+ * Code / Codex / Copilot / custom) that knows how to:
+ *
+ *   1. Detect whether the current environment is that vendor
+ *      (env vars, sentinel binaries, environment shape).
+ *   2. Issue a compact command through that vendor without forcing
+ *      peaks-loop's core code to know vendor-specific verbs.
+ *
+ * The interface is intentionally MINIMAL (Karpathy #2 Simplicity First):
+ * two methods (`detect`, `compact`) plus an `id` + `displayName`.
+ * New verbs (status, refactor, etc.) are NOT in scope — they would
+ * bloat the surface and force every vendor to implement every verb
+ * whether the vendor supports it or not. When a future verb is needed
+ * it can either be added to the interface (with all vendors forced to
+ * implement) or — preferred — handled through a separate
+ * verb-specific adapter family.
+ *
+ * Vendor-specific verb strings (`claude --compact`, `codex --compact`,
+ * `copilot compact`) MUST live ONLY in adapter implementations under
+ * `src/services/runtime/vendors/<vendor>.ts`. The runtime service that
+ * orchestrates these adapters (runtime-service.ts) and the CLI commands
+ * (`peaks runtime compact --via <id>`) MUST NOT contain vendor verbs
+ * — verified by AC-1: `rg -n "claude --compact|codex --compact|copilot
+ * compact" src/services/code/` must return 0 matches.
+ *
+ * See `.peaks/_runtime/2026-07-08-session-17918f/prd/002-adapter-runtime-and-polyrepo.md`
+ * for the source PRD.
+ */
+export interface VendorCompactArgs {
+    /** When `true`, the vendor is asked to compact unconditionally even
+     *  if its auto-detector says it would not normally do so. */
+    readonly force?: boolean;
+}
+export interface VendorCompactResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface VendorAdapter {
+    /** Stable identifier used by `peaks runtime compact --via <id>` and
+     *  by the adapter registry. Convention: lowercase, dash-separated,
+     *  e.g. `claude-code`, `codex`, `copilot`. */
+    readonly id: string;
+    /** Human-readable name shown in `peaks runtime list` output. */
+    readonly displayName: string;
+    /** Whether the CURRENT environment is this vendor. Detectors MUST
+     *  be pure functions of env + filesystem; they MUST NOT spawn
+     *  processes or call vendor CLIs (a detect that itself runs the
+     *  vendor would defeat the purpose of asking whether the vendor is
+     *  present). */
+    detect(): Promise<boolean>;
+    /** Issue a compact command for this vendor. The adapter chooses
+     *  which binary + args + env to invoke; callers MUST NOT pass
+     *  vendor verbs through this method. */
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

package/dist/services/runtime/vendors/claude-code.d.ts

@@ -0,0 +1,7 @@
+import type { VendorAdapter, VendorCompactArgs, VendorCompactResult } from '../vendor-adapter.js';
+export declare class ClaudeCodeAdapter implements VendorAdapter {
+    readonly id = "claude-code";
+    readonly displayName = "Claude Code";
+    detect(): Promise<boolean>;
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

package/dist/services/runtime/vendors/claude-code.js

@@ -0,0 +1,39 @@
+/**
+ * Claude Code vendor adapter — slice S2-a.
+ *
+ * Stubs the compact verb to `claude --compact` (the canonical vendor
+ * verb for Claude Code). The actual binary is invoked via spawn so
+ * the adapter does NOT block peaks-loop. When the `claude` binary is
+ * not on PATH the adapter returns exitCode=127 + stderr explaining
+ * the missing binary, which the runtime service surfaces as a warning
+ * + no-op rather than a fatal error (vendor-neutrality: peaks-loop
+ * should still work even when the host vendor CLI is absent).
+ */
+import { spawn } from 'node:child_process';
+export class ClaudeCodeAdapter {
+    id = 'claude-code';
+    displayName = 'Claude Code';
+    async detect() {
+        return process.env.CLAUDE_CODE === '1'
+            || process.env.CLAUDE_CODE === 'true'
+            || (process.env.CLAUDE_CODE_ENTRYPOINT?.length ?? 0) > 0;
+    }
+    async compact(args = {}) {
+        const argv = ['--compact'];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn('claude', 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/runtime/vendors/codex.d.ts

@@ -0,0 +1,7 @@
+import type { VendorAdapter, VendorCompactArgs, VendorCompactResult } from '../vendor-adapter.js';
+export declare class CodexAdapter implements VendorAdapter {
+    readonly id = "codex";
+    readonly displayName = "Codex";
+    detect(): Promise<boolean>;
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Codex vendor adapter — slice S2-a.
+ *
+ * Stub adapter (PRD out-of-scope: full implementation lands in a
+ * future slice). The detect() heuristic is intentionally permissive:
+ * if CODEX_HOME or ~/.codex is present we report detected=true so
+ * `peaks runtime detect` exercises the codex branch. compact() uses
+ * the canonical `codex --compact` invocation; missing-binary is
+ * reported as exitCode=127, not a thrown error (the runtime service
+ * surfaces that as a warning + no-op so a missing vendor CLI does
+ * not break peaks-loop).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export class CodexAdapter {
+    id = 'codex';
+    displayName = 'Codex';
+    async detect() {
+        if (process.env.CODEX_HOME !== undefined && process.env.CODEX_HOME.length > 0)
+            return true;
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        return home.length > 0 && existsSync(join(home, '.codex'));
+    }
+    async compact(args = {}) {
+        const argv = ['--compact'];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn('codex', 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/runtime/vendors/copilot.d.ts

@@ -0,0 +1,7 @@
+import type { VendorAdapter, VendorCompactArgs, VendorCompactResult } from '../vendor-adapter.js';
+export declare class CopilotAdapter implements VendorAdapter {
+    readonly id = "copilot";
+    readonly displayName = "GitHub Copilot";
+    detect(): Promise<boolean>;
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

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/acceptance-coverage-service.js

@@ -0,0 +1,140 @@
+import { join } from 'node:path';
+import { pathExists, readText } from 'peaks-loop-shared/fs';
+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;
+}