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

package/dist/services/code-review/ocr-service.js

@@ -0,0 +1,372 @@
+/**
+ * Open Code Review (ocr) integration — soft-optional augmentation
+ * for peaks-rd's Gate B3 (code review evidence).
+ *
+ * Per the "skill-first / CLI-auxiliary" tenet, peaks-rd SKILL.md
+ * is the primary surface; this CLI primitive returns a structured
+ * JSON envelope the skill consumes to produce a second-opinion
+ * code review alongside its own LLM review.
+ *
+ * Mirrors the ECC 64-agents soft-optional pattern
+ * (`src/services/agent/ecc-agent-service.ts`):
+ *   - same subprocessRunner injection seam (testability),
+ *   - same multi-state reason enum (clear failure-mode reporting),
+ *   - same soft-fail policy (never blocks the umbrella).
+ *
+ * === Source of truth: peaks-loop's own config.json ===
+ *
+ * peaks-loop does NOT auto-configure the LLM endpoint, and it does
+ * NOT write `~/.opencodereview/config.json`. The user is the only
+ * party that touches their LLM token / URL / model. The single
+ * discoverable place they declare those values is
+ * `peaksConfig.ocr.llm` under their `~/.peaks/config.json` (or
+ * `.peaks/config.json` in a project root).
+ *
+ *   peaksConfig.ocr.llm.url          → OCR_LLM_URL
+ *   peaksConfig.ocr.llm.authToken    → OCR_LLM_TOKEN
+ *   peaksConfig.ocr.llm.model        → OCR_LLM_MODEL
+ *   peaksConfig.ocr.llm.useAnthropic → OCR_USE_ANTHROPIC
+ *   peaksConfig.ocr.llm.authHeader   → OCR_LLM_AUTH_HEADER
+ *
+ * When `runOcrReview` spawns the ocr subprocess it injects those
+ * values as env vars. The ocr package treats env vars as the
+ * highest-priority config source, so peaks-loop never has to
+ * materialise `~/.opencodereview/config.json` itself.
+ *
+ * To see the JSON template to paste, run:
+ *   `peaks code-review config-template`
+ *
+ * The ocr package is declared in package.json:peerDependencies
+ * (was promoted to `dependencies` in 2.0.1, demoted to
+ * `optionalDependencies` in 2.0.3, then to `peerDependencies` in
+ * 2.8.2 — the ocr postinstall downloads a Go binary via HTTPS,
+ * which fails in restricted/proxied environments and would
+ * otherwise slow or abort the whole `npm i -g peaks-loop` flow).
+ * Peaks-cli ships with ocr *not* installed; if the user wants it,
+ * they run
+ *   `npm i -g @alibaba-group/open-code-review`
+ * and peaks-loop's 5-state detector (below) reports whether the
+ * binary is actually usable. pnpm-based installs additionally need
+ * `pnpm approve-builds @alibaba-group/open-code-review` for the
+ * binary download to run. Either way, peaks-loop never blocks on it.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+const OCR_DETECT_TIMEOUT_MS = 5000;
+const OCR_REVIEW_TIMEOUT_MS = 180000;
+const OCR_INSTALL_HINT = 'Install: `npm i -g @alibaba-group/open-code-review` (peaks-loop 2.8.2 ships with ocr as a peer dependency — its postinstall downloads a Go binary via HTTPS, which fails in some restricted/proxied environments; that\'s why peaks-loop does not auto-install it). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste. Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review` to allow the binary download.';
+const OCR_CONFIG_TEMPLATE = JSON.stringify({
+    ocr: {
+        llm: {
+            url: 'https://api.example.com/v1/messages',
+            authToken: '<your-api-key>',
+            model: 'claude-3-5-sonnet-latest',
+            useAnthropic: true,
+            authHeader: 'x-api-key'
+        }
+    }
+}, null, 2);
+const DEFAULT_RUNNER = {
+    run(command, args, options) {
+        try {
+            const r = spawnSync(command, args, {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                timeout: options.timeoutMs,
+                cwd: options.cwd,
+                env: options.env,
+            });
+            return {
+                status: r.status,
+                stdout: r.stdout ?? '',
+                stderr: r.stderr ?? '',
+            };
+        }
+        catch (err) {
+            return {
+                status: null,
+                stdout: '',
+                stderr: '',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    },
+};
+/**
+ * Locate the ocr launcher script (`bin/ocr.js`) inside our own
+ * node_modules tree. Returns null when the npm package is not
+ * present (peaks-loop was installed but its dependency tree is
+ * corrupt, or the user removed it).
+ *
+ * Walks up from this file (dist/services/code-review/) to
+ * find the project root, then checks node_modules.
+ */
+export function resolveOcrLauncher(searchRoots) {
+    const candidates = [];
+    for (const root of searchRoots) {
+        candidates.push(join(root, 'node_modules', '@alibaba-group', 'open-code-review', 'bin', 'ocr.js'));
+    }
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve search roots for the ocr launcher. We look in two
+ * places: (1) the peaks-loop install root (next to our own dist/),
+ * (2) the user's cwd.
+ */
+export function defaultOcrSearchRoots(currentDirPath, cwd) {
+    // currentDirPath is dist/services/code-review/ under tsc rootDir=src;
+    // walk up 3 to repo root. If tsconfig.build.json#rootDir ever reverts
+    // to "." (emits dist/src/services/code-review/), this must become
+    // walk-4 — keep these two in lockstep.
+    const peaksRoot = join(currentDirPath, '..', '..', '..');
+    return [peaksRoot, cwd];
+}
+/**
+ * Validate the `peaksConfig.ocr.llm` block the caller (CLI / test)
+ * read out of `~/.peaks/config.json`. Returns the list of missing
+ * required keys (`url`, `authToken`, `model`); empty array means
+ * the block is ready to drive the ocr subprocess.
+ *
+ * The block is independent of the OCR package's own
+ * `~/.opencodereview/config.json` file. peaks-loop only ever reads
+ * from its own config; the env-var injection in `runOcrReview`
+ * makes the legacy file irrelevant.
+ */
+export function getOcrLlmMissingFields(llm) {
+    if (llm === null) {
+        return ['ocr.llm.url', 'ocr.llm.authToken', 'ocr.llm.model'];
+    }
+    const missing = [];
+    if (typeof llm.url !== 'string' || llm.url.length === 0)
+        missing.push('ocr.llm.url');
+    if (typeof llm.authToken !== 'string' || llm.authToken.length === 0)
+        missing.push('ocr.llm.authToken');
+    if (typeof llm.model !== 'string' || llm.model.length === 0)
+        missing.push('ocr.llm.model');
+    return missing;
+}
+/**
+ * Build the env-var overlay peaks-loop injects into the ocr
+ * subprocess. Maps `peaksConfig.ocr.llm` onto the OCR package's
+ * env-var surface (its highest-priority config source).
+ */
+export function buildOcrEnv(llm) {
+    const env = {};
+    if (typeof llm.url === 'string' && llm.url.length > 0)
+        env.OCR_LLM_URL = llm.url;
+    if (typeof llm.authToken === 'string' && llm.authToken.length > 0)
+        env.OCR_LLM_TOKEN = llm.authToken;
+    if (typeof llm.model === 'string' && llm.model.length > 0)
+        env.OCR_LLM_MODEL = llm.model;
+    if (typeof llm.useAnthropic === 'boolean')
+        env.OCR_USE_ANTHROPIC = String(llm.useAnthropic);
+    if (typeof llm.authHeader === 'string' && llm.authHeader.length > 0)
+        env.OCR_LLM_AUTH_HEADER = llm.authHeader;
+    return env;
+}
+/**
+ * The JSON template the user pastes into their peaks-loop config
+ * (`peaksConfig.ocr.llm`). Returned as a stable string so the
+ * `peaks code-review config-template` CLI command can print it
+ * verbatim, and so the detector's `nextActions` payload embeds
+ * the same shape the user is told to add.
+ */
+export function getOcrConfigTemplate() {
+    return OCR_CONFIG_TEMPLATE;
+}
+/**
+ * Detect the full ocr install + config state. The 5 reason states
+ * are unchanged from the soft-optional 2.0.0 contract; only the
+ * source of `config-missing` moved from `~/.opencodereview/config.json`
+ * to `peaksConfig.ocr.llm`.
+ */
+export function detectOcr(options) {
+    const currentDirPath = dirname(fileURLToPath(import.meta.url));
+    const roots = options.searchRoots ?? defaultOcrSearchRoots(currentDirPath, options.cwd);
+    const launcher = resolveOcrLauncher(roots);
+    const warnings = [];
+    const nextActions = [];
+    if (launcher === null) {
+        const missing = getOcrLlmMissingFields(options.peaksOcrConfig);
+        return {
+            state: 'package-missing',
+            packageInstalled: false,
+            binaryPath: null,
+            version: null,
+            configPath: options.peaksConfigPath,
+            configValid: missing.length === 0,
+            missingKeys: missing,
+            warnings,
+            nextActions: [
+                '@alibaba-group/open-code-review is not installed in this project or peaks-loop root.',
+                OCR_INSTALL_HINT,
+            ],
+        };
+    }
+    // Check whether the platform-specific binary downloaded
+    // successfully. The launcher's own check is identical:
+    // bin/opencodereview(.exe) next to bin/ocr.js.
+    const isWindows = process.platform === 'win32';
+    const binaryName = isWindows ? 'opencodereview.exe' : 'opencodereview';
+    const binaryPath = join(dirname(launcher), binaryName);
+    if (!existsSync(binaryPath)) {
+        const missing = getOcrLlmMissingFields(options.peaksOcrConfig);
+        return {
+            state: 'binary-missing',
+            packageInstalled: true,
+            binaryPath: null,
+            version: null,
+            configPath: options.peaksConfigPath,
+            configValid: missing.length === 0,
+            missingKeys: missing,
+            warnings: [
+                'ocr npm package is installed but the platform binary failed to download (likely network or postinstall blocked).',
+            ],
+            nextActions: [
+                'For npm installs the binary downloads automatically; for pnpm run: `pnpm approve-builds @alibaba-group/open-code-review`.',
+                'Or run the installer directly: `node node_modules/@alibaba-group/open-code-review/scripts/install.js`.',
+                'Network-blocked installs can pre-download from https://github.com/alibaba/open-code-review/releases and place the binary at: ' + binaryPath,
+            ],
+        };
+    }
+    // Probe the binary for its version. We invoke through the
+    // node launcher so the upstream's update-check + arg-parse
+    // logic stays canonical.
+    const runner = options.runner ?? DEFAULT_RUNNER;
+    const probe = runner.run('node', [launcher, 'version'], { timeoutMs: OCR_DETECT_TIMEOUT_MS });
+    let version = null;
+    if (probe.status === 0 && probe.stdout.length > 0) {
+        const match = /(\d+\.\d+\.\d+)/.exec(probe.stdout);
+        version = match !== null ? match[1] ?? null : probe.stdout.trim().slice(0, 32);
+    }
+    const missing = getOcrLlmMissingFields(options.peaksOcrConfig);
+    if (missing.length > 0) {
+        return {
+            state: 'config-missing',
+            packageInstalled: true,
+            binaryPath,
+            version,
+            configPath: options.peaksConfigPath,
+            configValid: false,
+            missingKeys: missing,
+            warnings: [
+                `ocr is installed but peaks-loop's ocr.llm config is incomplete: missing ${missing.join(', ')}.`,
+            ],
+            nextActions: [
+                `Paste the following into ${options.peaksConfigPath} under "ocr.llm":`,
+                OCR_CONFIG_TEMPLATE,
+                'Or run `peaks code-review config-template` to print the snippet again.',
+                'Until configured, peaks-rd skips the ocr second-opinion step and proceeds with its own LLM review only.',
+            ],
+        };
+    }
+    return {
+        state: 'ready',
+        packageInstalled: true,
+        binaryPath,
+        version,
+        configPath: options.peaksConfigPath,
+        configValid: true,
+        missingKeys: [],
+        warnings,
+        nextActions,
+    };
+}
+/**
+ * Run ocr review and return the structured result. Detects state
+ * first; soft-fails when ocr isn't ready (the caller — typically
+ * peaks-rd — proceeds without the second-opinion review).
+ *
+ * The LLM endpoint config from `peaksConfig.ocr.llm` is injected
+ * as env vars (`OCR_LLM_URL` / `OCR_LLM_TOKEN` / ...), which the
+ * ocr package treats as the highest-priority config source. This
+ * is how peaks-loop wires the user-managed config into the ocr
+ * subprocess without ever writing `~/.opencodereview/config.json`.
+ */
+export function runOcrReview(options) {
+    const detect = detectOcr(options);
+    if (detect.state !== 'ready') {
+        return {
+            spawned: false,
+            state: detect.state,
+            exitCode: null,
+            stdout: '',
+            stderr: '',
+            durationMs: 0,
+            parsed: null,
+            warnings: detect.warnings,
+            nextActions: detect.nextActions,
+        };
+    }
+    // Resolve the launcher path again (we know it exists because detect.state === 'ready')
+    const currentDirPath = dirname(fileURLToPath(import.meta.url));
+    const roots = options.searchRoots ?? defaultOcrSearchRoots(currentDirPath, options.cwd);
+    const launcher = resolveOcrLauncher(roots);
+    if (launcher === null) {
+        // Should never happen given state === 'ready', but stay safe.
+        return {
+            spawned: false,
+            state: 'detection-failed',
+            exitCode: null,
+            stdout: '',
+            stderr: 'ocr launcher disappeared between detect and run',
+            durationMs: 0,
+            parsed: null,
+            warnings: ['ocr was detected as ready but the launcher path is no longer resolvable.'],
+            nextActions: ['Re-run `peaks code-review detect-ocr --json` to refresh.'],
+        };
+    }
+    // Inject the LLM endpoint config from peaks-loop's config.json
+    // as env vars — the ocr package's highest-priority config path.
+    const env = options.peaksOcrConfig === null
+        ? process.env
+        : { ...process.env, ...buildOcrEnv(options.peaksOcrConfig) };
+    const args = ['review', '--format', 'json'];
+    if (typeof options.input.from === 'string' && options.input.from.length > 0) {
+        args.push('--from', options.input.from);
+    }
+    if (typeof options.input.to === 'string' && options.input.to.length > 0) {
+        args.push('--to', options.input.to);
+    }
+    if (typeof options.input.commit === 'string' && options.input.commit.length > 0) {
+        args.push('--commit', options.input.commit);
+    }
+    const runner = options.runner ?? DEFAULT_RUNNER;
+    const start = Date.now();
+    const r = runner.run('node', [launcher, ...args], {
+        cwd: options.input.projectRoot,
+        timeoutMs: OCR_REVIEW_TIMEOUT_MS,
+        env,
+    });
+    const durationMs = Date.now() - start;
+    let parsed = null;
+    if (r.status === 0 && r.stdout.length > 0) {
+        try {
+            parsed = JSON.parse(r.stdout);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // Leave parsed=null; the caller can read raw stdout.
+        }
+    }
+    return {
+        spawned: true,
+        state: 'ready',
+        exitCode: r.status,
+        stdout: r.stdout,
+        stderr: r.stderr,
+        durationMs,
+        parsed,
+        warnings: r.status === 0 ? [] : [`ocr review exited with status ${r.status}`],
+        nextActions: r.status === 0
+            ? []
+            : ['Inspect stderr for the failure. Re-run `peaks code-review detect-ocr --json` to verify config still valid.'],
+    };
+}

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

@@ -0,0 +1,58 @@
+import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, ConfigV2, OcrAuthHeader, OcrConfig, OcrLlmConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
+/**
+ * Load the slim 2.0 `~/.peaks/config.json` file. Returns the parsed
+ * object when the file is at schema 2.0.0; returns null when the
+ * file is absent (fresh install, no global config yet).
+ *
+ * Throws `CONFIG_LEGACY_VERSION` when the file exists at a 1.x
+ * schema version — the caller is expected to run
+ * `peaks config migrate --apply` to bring it forward before
+ * continuing. This gate is intentional: a slim 2.0 reader must
+ * not silently pass through a 1.x shape, because every field it
+ * ignores is a field the caller is going to look for elsewhere
+ * (preferences.json, .bak, _state/).
+ */
+export declare function loadGlobalConfig(): ConfigV2 | null;
+export declare function isConfigLayer(value: string): value is ConfigLayer;
+export declare function isSensitiveConfigPath(path: string): boolean;
+export declare function isLegacyConfigKey(path: string): boolean;
+export declare function containsSensitiveConfigValue(value: unknown): boolean;
+export type RedactedConfigValue = string | number | boolean | null | RedactedConfigValue[] | {
+    [key: string]: RedactedConfigValue;
+};
+export declare function redactConfigSecrets(value: unknown, path?: string): RedactedConfigValue;
+/**
+ * Read the ocr LLM endpoint config from the user-layer
+ * `~/.peaks/config.json`. The user populates this themselves by
+ * pasting the `peaks code-review config-template` output (or by
+ * running `peaks config set --key ocr.llm.url --value '...'`).
+ * peaks-loop never auto-writes these values.
+ */
+export declare function getOcrConfig(): OcrConfig;
+/**
+ * Return the resolved `OcrLlmConfig` block (`peaksConfig.ocr.llm`)
+ * or `null` when the user has not populated the user config. The
+ * 5-state OCR detector uses this as the source of truth; when the
+ * returned block is missing required fields it produces a
+ * `config-missing` state with a templated `nextActions` payload
+ * the user can paste into their config.
+ */
+export declare function getOcrLlmConfig(): OcrLlmConfig | null;
+export declare function bootstrapProjectLanguageConfig(projectRoot: string, language: string): void;
+export declare function readConfig(projectRoot?: string | null): PeaksConfig;
+export declare function writeConfig(partial: Partial<PeaksConfig>, layer?: ConfigLayer): void;
+export declare function getConfig(options?: ConfigGetOptions): unknown;
+export declare function setConfig(options: ConfigSetOptions): void;
+export declare function getWorkspaceConfig(workspaceId: string, _projectRoot?: string | null): WorkspaceConfig | null;
+export declare function addWorkspace(workspace: WorkspaceConfig, layer?: ConfigLayer): void;
+export declare function removeWorkspace(workspaceId: string, layer?: ConfigLayer): boolean;
+export declare function setCurrentWorkspace(workspaceId: string, layer?: ConfigLayer): boolean;
+export declare function getCurrentWorkspaceConfig(): WorkspaceConfig | null;
+export declare function getWorkspaceConfigForPath(path?: string): WorkspaceConfig | null;
+export declare function ensureWorkspaceConfigForPath(path?: string): WorkspaceConfig | null;
+export declare function getWorkspaceConfigForCurrentPath(): WorkspaceConfig | null;
+export declare function ensureWorkspaceConfigForCurrentPath(): WorkspaceConfig | null;
+export type { OcrAuthHeader, OcrConfig, OcrLlmConfig, TokenRef, WorkspaceConfig, PeaksConfig, ConfigLayer };
+export { getUserConfigPath } from './config-safety.js';
+export { globalConfigPath } from './config-migration.js';