peaks-cli 1.4.2 → 2.0.0

package/dist/src/services/code-review/ocr-service.d.ts

@@ -0,0 +1,129 @@
+import type { OcrLlmConfig } from '../config/config-types.js';
+export type OcrDetectState = 'ready' | 'package-missing' | 'binary-missing' | 'config-missing' | 'detection-failed';
+export interface OcrDetectResult {
+    readonly state: OcrDetectState;
+    readonly packageInstalled: boolean;
+    readonly binaryPath: string | null;
+    readonly version: string | null;
+    /**
+     * The peaks-cli config path that holds `peaksConfig.ocr.llm`.
+     * The user pastes the `peaks code-review config-template` output
+     * here. Empty string when peaks-cli has not been bootstrapped.
+     */
+    readonly configPath: string;
+    readonly configValid: boolean;
+    readonly missingKeys: readonly string[];
+    readonly warnings: readonly string[];
+    readonly nextActions: readonly string[];
+}
+export interface OcrReviewInput {
+    readonly projectRoot: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly commit?: string;
+}
+export interface OcrReviewResult {
+    readonly spawned: boolean;
+    readonly state: OcrDetectState;
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    /** Parsed JSON envelope if the ocr subprocess emitted valid JSON. */
+    readonly parsed: unknown;
+    readonly warnings: readonly string[];
+    readonly nextActions: readonly string[];
+}
+export interface SubprocessRunner {
+    run(command: string, args: readonly string[], options: {
+        cwd?: string;
+        timeoutMs: number;
+        env?: NodeJS.ProcessEnv;
+    }): {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+        error?: string;
+    };
+}
+/**
+ * Locate the ocr launcher script (`bin/ocr.js`) inside our own
+ * node_modules tree. Returns null when the npm package is not
+ * present (peaks-cli was installed but its dependency tree is
+ * corrupt, or the user removed it).
+ *
+ * Walks up from this file (dist/src/services/code-review/) to
+ * find the project root, then checks node_modules.
+ */
+export declare function resolveOcrLauncher(searchRoots: readonly string[]): string | null;
+/**
+ * Resolve search roots for the ocr launcher. We look in two
+ * places: (1) the peaks-cli install root (next to our own dist/),
+ * (2) the user's cwd.
+ */
+export declare function defaultOcrSearchRoots(currentDirPath: string, cwd: string): readonly string[];
+/**
+ * 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-cli only ever reads
+ * from its own config; the env-var injection in `runOcrReview`
+ * makes the legacy file irrelevant.
+ */
+export declare function getOcrLlmMissingFields(llm: OcrLlmConfig | null): readonly string[];
+/**
+ * Build the env-var overlay peaks-cli injects into the ocr
+ * subprocess. Maps `peaksConfig.ocr.llm` onto the OCR package's
+ * env-var surface (its highest-priority config source).
+ */
+export declare function buildOcrEnv(llm: OcrLlmConfig): NodeJS.ProcessEnv;
+/**
+ * The JSON template the user pastes into their peaks-cli 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 declare function getOcrConfigTemplate(): string;
+export interface OcrDetectOptions {
+    readonly cwd: string;
+    /**
+     * The peaks-cli config path that holds `peaksConfig.ocr.llm`.
+     * Surfaced in the detect result so the user knows where to
+     * paste the template.
+     */
+    readonly peaksConfigPath: string;
+    /**
+     * The parsed `peaksConfig.ocr.llm` block. `null` when the user
+     * has not yet populated the config; the detector surfaces the
+     * `config-missing` state with a templated `nextActions`.
+     */
+    readonly peaksOcrConfig: OcrLlmConfig | null;
+    readonly searchRoots?: readonly string[];
+    readonly runner?: SubprocessRunner;
+}
+/**
+ * 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 declare function detectOcr(options: OcrDetectOptions): OcrDetectResult;
+export interface OcrReviewOptions extends OcrDetectOptions {
+    readonly input: OcrReviewInput;
+}
+/**
+ * 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-cli wires the user-managed config into the ocr
+ * subprocess without ever writing `~/.opencodereview/config.json`.
+ */
+export declare function runOcrReview(options: OcrReviewOptions): OcrReviewResult;

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

@@ -0,0 +1,362 @@
+/**
+ * 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-cli's own config.json ===
+ *
+ * peaks-cli 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-cli 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:dependencies (was
+ * previously optionalDependencies) so `npm i -g peaks-cli@2.0.x`
+ * pulls it automatically (npm runs the ocr postinstall by default,
+ * which downloads the Go binary). pnpm-based installs need
+ * `pnpm approve-builds @alibaba-group/open-code-review`. Either
+ * way, peaks-cli detects the install state and reports 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` (it is a hard dependency of peaks-cli 2.0.x and ships in the regular `npm install` flow). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste.';
+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-cli was installed but its dependency tree is
+ * corrupt, or the user removed it).
+ *
+ * Walks up from this file (dist/src/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-cli install root (next to our own dist/),
+ * (2) the user's cwd.
+ */
+export function defaultOcrSearchRoots(currentDirPath, cwd) {
+    // currentDirPath is dist/src/services/code-review/; walk up 4 to repo root.
+    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-cli 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-cli 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-cli 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-cli 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-cli'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-cli 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-cli'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 {
+            // 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/src/services/config/config-migration.d.ts

@@ -0,0 +1,32 @@
+export declare const CONFIG_SCHEMA_VERSION_V2 = "2.0.0";
+/**
+ * Per-project fields that the 1.x → 2.0 migration moves
+ * from `~/.peaks/config.json` (global) to `<project>/.peaks/preferences.json`
+ * (per-project). Per spec §10.4 line 1215: "economyMode / swarmMode
+ * 字段从 global 迁移到当前 workspace 的 .peaks/preferences.json".
+ */
+declare const PER_PROJECT_FIELDS: readonly ["economyMode", "swarmMode"];
+type PerProjectField = (typeof PER_PROJECT_FIELDS)[number];
+export interface MigrationOptions {
+    currentProjectRoot: string;
+}
+export interface MigrationPlan {
+    alreadyAtV2: boolean;
+    detectedSchemaVersion: string | null;
+    newConfigSchemaVersion: string;
+    /** Field names that would be migrated on apply (1.x → 2.0). */
+    willMigrateFields: readonly PerProjectField[];
+}
+export interface MigrationResult extends MigrationPlan {
+    applied: boolean;
+    backupPath?: string;
+    newConfigPath?: string;
+    error?: string;
+}
+export declare function globalConfigPath(): string;
+export declare function backupConfigPath(): string;
+export declare function planMigration(opts: MigrationOptions): MigrationPlan;
+export declare function executeMigration(opts: MigrationOptions & {
+    apply: boolean;
+}): MigrationResult;
+export {};

package/dist/src/services/config/config-migration.js

@@ -0,0 +1,92 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { savePreferences } from '../preferences/preferences-service.js';
+export const CONFIG_SCHEMA_VERSION_V2 = '2.0.0';
+const BACKUP_NAME = 'config.json.1.x.bak';
+/**
+ * Per-project fields that the 1.x → 2.0 migration moves
+ * from `~/.peaks/config.json` (global) to `<project>/.peaks/preferences.json`
+ * (per-project). Per spec §10.4 line 1215: "economyMode / swarmMode
+ * 字段从 global 迁移到当前 workspace 的 .peaks/preferences.json".
+ */
+const PER_PROJECT_FIELDS = ['economyMode', 'swarmMode'];
+export function globalConfigPath() {
+    return join(homedir(), '.peaks', 'config.json');
+}
+export function backupConfigPath() {
+    return join(homedir(), '.peaks', BACKUP_NAME);
+}
+/**
+ * Inspect the on-disk 1.x config and return the subset of
+ * per-project fields that are present and would be migrated on
+ * apply. The list is used both by `planMigration` (to populate
+ * `willMigrateFields`) and by `executeMigration` (to know which
+ * fields to forward to `savePreferences`).
+ */
+function discoverMigratableFields(raw) {
+    const out = [];
+    for (const f of PER_PROJECT_FIELDS) {
+        if (typeof raw[f] === 'boolean')
+            out.push(f);
+    }
+    return out;
+}
+export function planMigration(opts) {
+    const configPath = globalConfigPath();
+    let detectedSchemaVersion = null;
+    let willMigrateFields = [];
+    if (existsSync(configPath)) {
+        const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+        detectedSchemaVersion = raw.version ?? null;
+        willMigrateFields = discoverMigratableFields(raw);
+    }
+    if (detectedSchemaVersion === CONFIG_SCHEMA_VERSION_V2) {
+        return {
+            alreadyAtV2: true,
+            detectedSchemaVersion,
+            newConfigSchemaVersion: CONFIG_SCHEMA_VERSION_V2,
+            willMigrateFields: [],
+        };
+    }
+    return {
+        alreadyAtV2: false,
+        detectedSchemaVersion,
+        newConfigSchemaVersion: CONFIG_SCHEMA_VERSION_V2,
+        willMigrateFields,
+    };
+}
+export function executeMigration(opts) {
+    const configPath = globalConfigPath();
+    if (!existsSync(configPath)) {
+        throw new Error('NO_CONFIG: ~/.peaks/config.json not found');
+    }
+    const plan = planMigration(opts);
+    if (plan.alreadyAtV2) {
+        return { ...plan, applied: false };
+    }
+    if (!opts.apply) {
+        return { ...plan, applied: false };
+    }
+    const original = JSON.parse(readFileSync(configPath, 'utf8'));
+    // 1. Backup
+    const bak = backupConfigPath();
+    writeFileSync(bak, JSON.stringify(original, null, 2) + '\n', 'utf8');
+    // 2. Forward per-project fields to <projectRoot>/.peaks/preferences.json
+    //    (per spec §10.4). The preferences service merges over the existing
+    //    schema-valid preferences.json; boolean fields only, with the
+    //    discoverMigratableFields() allowlist as the source of truth.
+    if (plan.willMigrateFields.length > 0) {
+        const overrides = {};
+        for (const f of plan.willMigrateFields) {
+            const v = original[f];
+            if (typeof v === 'boolean')
+                overrides[f] = v;
+        }
+        savePreferences(opts.currentProjectRoot, overrides);
+    }
+    // 3. Slim config.json — only the schema version remains.
+    mkdirSync(join(homedir(), '.peaks'), { recursive: true });
+    writeFileSync(configPath, JSON.stringify({ version: CONFIG_SCHEMA_VERSION_V2 }, null, 2) + '\n', 'utf8');
+    return { ...plan, applied: true, backupPath: bak, newConfigPath: configPath };
+}

package/dist/src/services/config/config-restore.d.ts

@@ -0,0 +1,10 @@
+export interface RestoreResult {
+    field: string;
+    applied: boolean;
+    sidecarPath?: string;
+}
+export declare function listAvailableFields(): string[];
+export declare function restoreField(opts: {
+    field: string;
+    apply: boolean;
+}): RestoreResult;

package/dist/src/services/config/config-restore.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { backupConfigPath } from './config-migration.js';
+/**
+ * Spec §8.6 — restore a single archived field from `config.json.1.x.bak`.
+ * Does NOT modify `config.json` itself (which is now slim v2).
+ * Instead writes a sidecar `config.json.restore-<field>.json` so the user
+ * can review before adopting. Fields in the deferred-design set
+ * (workspaces, providers, proxy) throw RESTORE_GUARDED so the user has
+ * to acknowledge explicitly.
+ */
+const GUARDED_FIELDS = new Set(['workspaces', 'providers', 'proxy']);
+function readBakContent() {
+    const bak = backupConfigPath();
+    if (!existsSync(bak)) {
+        throw new Error('NO_BACKUP: ~/.peaks/config.json.1.x.bak not found');
+    }
+    return JSON.parse(readFileSync(bak, 'utf8'));
+}
+export function listAvailableFields() {
+    const bak = readBakContent();
+    return Object.keys(bak).filter((k) => k !== 'version');
+}
+export function restoreField(opts) {
+    const bak = readBakContent();
+    if (!(opts.field in bak)) {
+        throw new Error(`FIELD_NOT_FOUND: ${opts.field} is not in config.json.1.x.bak`);
+    }
+    if (GUARDED_FIELDS.has(opts.field)) {
+        throw new Error(`RESTORE_GUARDED: restoring "${opts.field}" is discouraged because the deferred design intentionally avoids it; add it to config.json manually if you really need it`);
+    }
+    const home = homedir();
+    const sidecar = join(home, '.peaks', `config.json.restore-${opts.field}.json`);
+    if (!opts.apply) {
+        return { field: opts.field, applied: false };
+    }
+    mkdirSync(join(home, '.peaks'), { recursive: true });
+    const payload = {
+        field: opts.field,
+        value: bak[opts.field],
+        source: 'config.json.1.x.bak',
+        restoredAt: new Date().toISOString(),
+    };
+    writeFileSync(sidecar, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    return { field: opts.field, applied: true, sidecarPath: sidecar };
+}

package/dist/src/services/config/config-rollback.d.ts

@@ -0,0 +1,13 @@
+export interface RollbackPlan {
+    available: boolean;
+    detectedVersion: string | null;
+    backupPath: string;
+}
+export interface RollbackResult extends RollbackPlan {
+    applied: boolean;
+    restoredConfigPath?: string;
+}
+export declare function planRollback(): RollbackPlan;
+export declare function executeRollback(opts: {
+    apply: boolean;
+}): RollbackResult;