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

package/dist/cli/commands/runtime-commands.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `peaks runtime *` — vendor-runtime detection + compact CLI surface.
+ *
+ * Slice S2-a of RD-2 (2026-07-08 session). Four subcommands:
+ *
+ *   detect    — print which vendor is the active AI runtime
+ *               (claude-code / codex / copilot / unknown).
+ *   list      — list the built-in vendor adapters registered by
+ *               RuntimeService (Claude Code / Codex / Copilot).
+ *   compact   — invoke a vendor's compact verb via the adapter. The
+ *               adapter (NOT this file) chooses the vendor verb;
+ *               see src/services/runtime/vendors/<vendor>.ts.
+ *
+ * Vendor verb strings (`claude --compact`, `codex --compact`,
+ * `copilot compact`) MUST live ONLY in `src/services/runtime/vendors/`
+ * — verified by AC-1: `rg -n "claude --compact|codex --compact|copilot
+ * compact" src/services/code/` returns 0 matches.
+ *
+ * `peaks runtime compact --via <id>` first consults the user
+ * adapter registry (`.peaks/runtime/adapters.json`) for the id, then
+ * falls back to the built-in adapter list. Missing vendor CLI
+ * surfaces as exitCode=127 + warning, NOT as a fatal error — vendor
+ * neutrality demands peaks-loop stay alive.
+ */
+import type { Command } from 'commander';
+import { join } from 'node:path';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface RuntimeDetectOptions {
+    json?: boolean;
+}
+export interface RuntimeListOptions {
+    json?: boolean;
+}
+export interface RuntimeCompactOptions {
+    json?: boolean;
+    /** Vendor adapter id (built-in or registered). */
+    via?: string;
+    force?: boolean;
+    /** Override the project root (defaults to .peaks runtime lookup). */
+    project?: string;
+}
+export declare function registerRuntimeCommands(program: Command, io: ProgramIO): void;
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export declare function ensureRegistryDir(registryFile: string): void;
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export declare function registryFileFor(projectRoot: string): string;
+/** Re-export the path join helper for completeness; not strictly
+ *  needed by callers but keeps the module self-contained. */
+export { join };

package/dist/cli/commands/runtime-commands.js

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { getErrorMessage } from '../../shared/result.js';
+import { detectRuntime } from '../../services/runtime/runtime-detector.js';
+import { RuntimeService } from '../../services/runtime/runtime-service.js';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+function resolveProjectRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerRuntimeCommands(program, io) {
+    const runtime = program
+        .command('runtime')
+        .description('Vendor runtime detection + compact via adapter (--via <vendor-id>)');
+    // -----------------------------------------------------------------
+    // 1. peaks runtime detect [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('detect')
+        .description('Print the active AI runtime vendor (claude-code / codex / copilot / unknown)')).action((options) => {
+        try {
+            const result = detectRuntime();
+            printResult(io, ok('runtime.detect', result, [], [
+                result.vendor === 'unknown'
+                    ? 'No vendor sentinel detected. Use `peaks adapter register --id <vendor> --binary <cmd>` to wire a custom one.'
+                    : `Run \`peaks runtime compact --via ${result.vendor}\` to invoke its compact verb.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.detect', 'RUNTIME_DETECT_FAILED', getErrorMessage(error), {}, ['Retry with a clean env']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks runtime list [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('list')
+        .description('List the built-in vendor adapters registered by RuntimeService')).action((options) => {
+        try {
+            const svc = new RuntimeService();
+            const adapters = svc.listBuiltInAdapters().map((a) => ({ id: a.id, displayName: a.displayName }));
+            printResult(io, ok('runtime.list', { builtIn: adapters }, [], [
+                `Run \`peaks adapter register --id <vendor> --binary <cmd>\` to add a custom adapter (persists to .peaks/runtime/adapters.json).`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.list', 'RUNTIME_LIST_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks runtime compact [--via <id>] [--force] [--json] [--project <root>]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('compact')
+        .description('Compact the active vendor via the chosen adapter (--via <vendor-id>); vendor verbs live ONLY in adapter files')
+        .option('--via <id>', 'vendor adapter id (built-in or user-registered)')
+        .option('--force', 'ask the vendor to compact unconditionally')
+        .option('--project <path>', 'project root (defaults to cwd)')).action(async (options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const requested = options.via;
+            if (requested === undefined || requested.length === 0) {
+                // No explicit --via: try to detect first, then fall back.
+                const detected = detectRuntime();
+                if (detected.vendor === 'unknown') {
+                    printResult(io, fail('runtime.compact', 'NO_VENDOR_SPECIFIED', 'No --via <id> provided and no vendor detected.', { detected }, [
+                        'Pass --via <vendor-id>, or run `peaks runtime detect` to see what was detected.'
+                    ]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                await runCompact(projectRoot, detected.vendor, options.force === true, io, options.json);
+                return;
+            }
+            await runCompact(projectRoot, requested, options.force === true, io, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.compact', 'RUNTIME_COMPACT_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+async function runCompact(projectRoot, viaId, force, io, asJson) {
+    // Layer 1: user-registered adapter (via AdapterRegistry).
+    const registryFile = AdapterRegistry.defaultFile(projectRoot);
+    const registry = new AdapterRegistry();
+    if (existsSync(registryFile)) {
+        try {
+            registry.load(registryFile);
+        }
+        catch { // TODO(g2): vendor-neutrality — corrupt adapter registry must NOT block peaks runtime
+            // Treat corrupt registry as empty — vendor-neutrality: a corrupt
+            // .peaks/runtime/adapters.json must NOT block peaks runtime.
+            // We still try the built-in path below.
+        }
+    }
+    const registered = registry.resolve(viaId);
+    if (registered !== undefined) {
+        const r = await registered.compact({ force });
+        const warnings = [];
+        if (r.exitCode === 127) {
+            warnings.push(`binary for adapter "${viaId}" not found on PATH; compact is a no-op`);
+        }
+        printResult(io, ok('runtime.compact', { via: viaId, source: 'registry', compact: r }, warnings, [
+            r.exitCode === 0
+                ? 'Compact completed.'
+                : `Compact exited with code ${r.exitCode}. Check stderr above.`
+        ]), asJson);
+        if (r.exitCode !== 0)
+            process.exitCode = 1;
+        return;
+    }
+    // Layer 2: built-in adapter (via RuntimeService).
+    const svc = new RuntimeService();
+    const r = await svc.compactVia(viaId, force);
+    const warnings = [];
+    if (r.warning !== undefined)
+        warnings.push(r.warning);
+    if (r.exitCode === 127) {
+        warnings.push(`built-in adapter "${viaId}" binary not found on PATH; compact is a no-op`);
+    }
+    printResult(io, ok('runtime.compact', { via: viaId, source: 'built-in', compact: { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr } }, warnings, [
+        r.exitCode === 0
+            ? 'Compact completed.'
+            : `Compact exited with code ${r.exitCode}. Check stderr above.`
+    ]), asJson);
+    if (r.exitCode !== 0)
+        process.exitCode = 1;
+}
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export function ensureRegistryDir(registryFile) {
+    mkdirSync(dirname(registryFile), { recursive: true });
+}
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export function registryFileFor(projectRoot) {
+    const f = AdapterRegistry.defaultFile(projectRoot);
+    ensureRegistryDir(f);
+    return f;
+}
+/** Re-export the path join helper for completeness; not strictly
+ *  needed by callers but keeps the module self-contained. */
+export { join };

package/dist/cli/commands/sc-commands.js

@@ -0,0 +1,47 @@
+import { createArtifactRetentionReport, createChangeImpact, getChangeTraceabilityStatus, getScHelpText, recordCommitBoundary, validateArtifactRetention } from '../../services/sc/sc-service.js';
+import { ok } from '../../shared/result.js';
+import { addJsonOption, multipleOption, printResult } from '../cli-helpers.js';
+export function registerSCCommands(program, io) {
+    const sc = program
+        .command('sc', { hidden: true })
+        .description('Source control and change traceability (peaks-sc integration)');
+    registerSCStatusCommands(sc, io);
+    registerSCArtifactCommands(sc, io);
+}
+function registerSCStatusCommands(sc, io) {
+    addJsonOption(sc.command('status').description('Show change traceability status')).action((options) => {
+        printResult(io, ok('sc.status', getChangeTraceabilityStatus()), options.json);
+    });
+    addJsonOption(sc.command('help').description('Show peaks-sc help text')).action((options) => {
+        const helpText = getScHelpText().join('\n');
+        if (options.json) {
+            printResult(io, ok('sc.help', { helpText }), options.json);
+        }
+        else {
+            io.stdout(helpText);
+        }
+    });
+}
+function registerSCArtifactCommands(sc, io) {
+    // Slice 2026-06-29-change-id-root-removal: `--change-id` is no
+    // longer accepted on `peaks sc impact`. The CLI surfaces a
+    // per-`(module, file)` impact report without a top-level
+    // change-id binding.
+    addJsonOption(sc.command('impact').description('Generate change impact artifact').option('--module <module>', 'affected module', multipleOption).option('--file <file>', 'affected file', multipleOption)).action((options) => {
+        const impactOptions = {
+            sessionId: '',
+            ...(options.module ? { affectedModules: options.module } : {}),
+            ...(options.file ? { affectedFiles: options.file } : {})
+        };
+        printResult(io, ok('sc.impact', createChangeImpact(impactOptions)), options.json);
+    });
+    addJsonOption(sc.command('retention').description('Create artifact retention report').requiredOption('--slice-id <id>', 'slice identifier').option('--prd <artifact>', 'PRD artifact path', multipleOption).option('--rd <artifact>', 'RD artifact path', multipleOption).option('--qa <artifact>', 'QA artifact path', multipleOption).option('--coverage <artifact>', 'coverage artifact path', multipleOption).option('--review <artifact>', 'review artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
+        printResult(io, ok('sc.retention', createArtifactRetentionReport({ sliceId: options.sliceId, ...(options.prd ? { prdArtifacts: options.prd } : {}), ...(options.rd ? { rdArtifacts: options.rd } : {}), ...(options.qa ? { qaArtifacts: options.qa } : {}), ...(options.coverage ? { coverageArtifacts: options.coverage } : {}), ...(options.review ? { reviewArtifacts: options.review } : {}), ...(options.code ? { codeChanges: options.code } : {}) })), options.json);
+    });
+    addJsonOption(sc.command('validate').description('Validate artifact retention for a slice').requiredOption('--slice-id <id>', 'slice identifier')).action((options) => {
+        printResult(io, ok('sc.validate', validateArtifactRetention(options.sliceId)), options.json);
+    });
+    addJsonOption(sc.command('boundary').description('Record retention boundary for a slice').requiredOption('--slice-id <id>', 'slice identifier').option('--artifact <path>', 'artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
+        printResult(io, ok('sc.boundary', recordCommitBoundary({ sliceId: options.sliceId, ...(options.artifact ? { artifacts: options.artifact } : {}), ...(options.code ? { codeFiles: options.code } : {}) })), options.json);
+    });
+}

package/dist/cli/commands/security-audit-commands.js

@@ -0,0 +1,132 @@
+import { readFileSync } from 'node:fs';
+import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from '../../services/audit-independent/security-audit-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+function resolveEnvelope(envelopePath) {
+    if (envelopePath === undefined || envelopePath === '-') {
+        // Read from stdin
+        return readStdinSync();
+    }
+    try {
+        const raw = readFileSync(envelopePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to read envelope from ${envelopePath}: ${getErrorMessage(error)}`);
+    }
+}
+function readStdinSync() {
+    // Node 22: read stdin synchronously via fs.readFileSync(0, 'utf8').
+    // We use the file descriptor 0 convention.
+    try {
+        // Lazy import to avoid pulling readline at module load
+        const { readFileSync: rfs } = require('node:fs');
+        const raw = rfs(0, 'utf8');
+        if (raw.trim().length === 0) {
+            throw new Error('stdin was empty; expected JSON envelope on stdin or --envelope <path>');
+        }
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('stdin was empty')) {
+            throw error;
+        }
+        throw new Error(`Failed to read envelope from stdin: ${getErrorMessage(error)}`);
+    }
+}
+export function registerSecurityAuditCommands(program, io) {
+    const securityAudit = program
+        .command('security-audit', { hidden: true })
+        .description('Independent security audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level security-template.md, then writes a structured security-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). See skills/bee/peaks-security-audit/SKILL.md for the full workflow.');
+    addJsonOption(securityAudit
+        .command('detect')
+        .description('Read-only probe: returns the 5-state security-audit runtime as a JSON envelope (ready / handoff-missing / template-missing / dispatch-failed / envelope-malformed). The peaks-security-audit skill calls this first to decide whether to invoke `run`. Mirrors `peaks code-review detect-ocr` semantics.')
+        .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
+        .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        const sid = options.sid;
+        if (sid === undefined || sid.length === 0) {
+            printResult(io, fail('security-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.detect', { state: 'sid-missing' }, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)', 'Run `peaks session info --active --json` to find the active sid.']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const detect = detectSecurityAudit({
+                projectRoot,
+                sessionId: sid,
+            });
+            const envelope = detect.state === 'ready'
+                ? ok('security-audit.detect', detect, [...detect.warnings], [...detect.nextActions])
+                : fail('security-audit.detect', detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${detect.state}`, detect, [...detect.nextActions]);
+            printResult(io, envelope, options.json);
+            if (detect.state !== 'ready') {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('security-audit.detect', 'DETECT_SECURITY_AUDIT_FAILED', getErrorMessage(error), {
+                state: 'detection-failed',
+                handoffPresent: false,
+                templatePresent: false,
+                warnings: [],
+                nextActions: [],
+            }, ['Re-run with --project <path> pointing at a known-good project root.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(securityAudit
+        .command('run')
+        .description('Run the full security-audit pipeline: detect → read handoff + template → write audit artifact to `.peaks/_runtime/<sid>/audit/security-<rid>.md`. Reads the envelope JSON from --envelope <path> or stdin. The peaks-security-audit skill emits the envelope; this CLI validates the shape via isSecurityAuditEnvelope and writes the artifact. Exits 0 on success, 1 on any failure mode (detection, validation, or write).')
+        .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
+        .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        const sid = options.sid;
+        const rid = options.rid;
+        if (sid === undefined || sid.length === 0) {
+            printResult(io, fail('security-audit.run', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.run', {}, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (rid === undefined || rid.length === 0) {
+            printResult(io, fail('security-audit.run', 'RID_REQUIRED', 'request id (--rid) is required for security-audit.run', {}, ['Pass --rid <request-id> (e.g. 2026-06-27-v2-12-...)']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const envelopeValue = resolveEnvelope(options.envelope);
+            if (!isSecurityAuditEnvelope(envelopeValue)) {
+                printResult(io, fail('security-audit.run', 'ENVELOPE_MALFORMED', 'envelope failed isSecurityAuditEnvelope validation (expected { verdict, violations, summary })', { receivedType: typeof envelopeValue }, [
+                    'Verify the peaks-security-audit skill prompt matches the strict-shape contract.',
+                    'Re-emit the envelope; see skills/bee/peaks-security-audit/references/audit-protocol.md.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = runSecurityAudit({
+                projectRoot,
+                sessionId: sid,
+                rid,
+                generatedAt: new Date().toISOString(),
+                envelope: envelopeValue,
+            });
+            if (result.detect.state !== 'ready' || result.artifactPath === null) {
+                printResult(io, fail('security-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('security-audit.run', {
+                detect: result.detect,
+                artifactPath: result.artifactPath,
+                violationsCount: result.violationsCount,
+                verdict: result.verdict,
+            }, [...result.detect.warnings], [...result.detect.nextActions]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('security-audit.run', 'RUN_SECURITY_AUDIT_FAILED', getErrorMessage(error), {}, ['Verify the envelope JSON is well-formed and matches the strict-shape contract.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}