peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,62 @@
+/**
+ * Runtime detector — slice S2-a of RD-2.
+ *
+ * Given the current process environment, decide which vendor (if any)
+ * is the active AI runtime. Detection order matters: Claude Code is
+ * checked first because it is the default runtime for peaks-loop
+ * (the project literally runs inside Claude Code). Codex + Copilot
+ * are checked second; if none match we report `unknown`.
+ *
+ * Detectors MUST be cheap (no process spawn, no network). They look
+ * at env vars + filesystem sentinels + home-dir shapes only. This
+ * keeps `peaks runtime detect` sub-100ms even on cold paths.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Heuristic: Claude Code sets CLAUDE_CODE_ENTRYPOINT or has a
+ *  .claude/skills directory under HOME (peaks-loop installs there). */
+function detectClaudeCode(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CLAUDE_CODE === '1' || env.CLAUDE_CODE === 'true')
+        return true;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined && env.CLAUDE_CODE_ENTRYPOINT.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.claude')))
+        return true;
+    return false;
+}
+/** Heuristic: Codex sets CODEX_HOME or has a .codex dir under HOME. */
+function detectCodex(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CODEX_HOME !== undefined && env.CODEX_HOME.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.codex')))
+        return true;
+    return false;
+}
+/** Heuristic: Copilot sets GITHUB_COPILOT or has a .copilot dir. */
+function detectCopilot(opts) {
+    const env = opts.env ?? process.env;
+    if (env.GITHUB_COPILOT === '1' || env.GITHUB_COPILOT === 'true')
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.copilot')))
+        return true;
+    return false;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export function detectRuntime(opts = {}) {
+    if (detectClaudeCode(opts)) {
+        return { vendor: 'claude-code', reason: 'CLAUDE_CODE_ENTRYPOINT / CLAUDE_CODE / ~/.claude matched' };
+    }
+    if (detectCodex(opts)) {
+        return { vendor: 'codex', reason: 'CODEX_HOME / ~/.codex matched' };
+    }
+    if (detectCopilot(opts)) {
+        return { vendor: 'copilot', reason: 'GITHUB_COPILOT / ~/.copilot matched' };
+    }
+    return { vendor: 'unknown', reason: 'no vendor sentinel detected' };
+}

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 });
+            });
+        });
+    }
+}