peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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

@@ -0,0 +1,369 @@
+/**
+ * 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/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-loop 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-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/codegraph/codegraph-process-runner.d.ts

@@ -0,0 +1,2 @@
+import type { CodegraphExecutionResult, CodegraphInvocation } from './codegraph-service.js';
+export declare function defaultCodegraphProcessRunner(invocation: CodegraphInvocation): Promise<CodegraphExecutionResult>;

package/dist/services/codegraph/codegraph-process-runner.js

@@ -0,0 +1,93 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+const CODEGRAPH_PROCESS_TIMEOUT_MS = 600_000;
+const CODEGRAPH_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
+function createCodegraphEnvironment(sourceEnv = process.env) {
+    const preservedKeys = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'WINDIR'];
+    const environment = {};
+    for (const key of preservedKeys) {
+        const value = sourceEnv[key];
+        if (value !== undefined) {
+            environment[key] = value;
+        }
+    }
+    return environment;
+}
+function assertOutputLimit(currentSize, chunkSize) {
+    const nextSize = currentSize + chunkSize;
+    if (nextSize > CODEGRAPH_OUTPUT_LIMIT_BYTES) {
+        throw new Error(`codegraph output exceeded ${CODEGRAPH_OUTPUT_LIMIT_BYTES} bytes`);
+    }
+    return nextSize;
+}
+function terminateCodegraphProcess(childProcess) {
+    if (childProcess.pid === undefined) {
+        childProcess.kill();
+        return;
+    }
+    if (process.platform === 'win32') {
+        if (process.env.SystemRoot) {
+            spawn(join(process.env.SystemRoot, 'System32', 'taskkill.exe'), ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+        }
+        else {
+            childProcess.kill();
+        }
+        return;
+    }
+    try {
+        process.kill(-childProcess.pid, 'SIGTERM');
+    }
+    catch {
+        childProcess.kill('SIGTERM');
+    }
+}
+export function defaultCodegraphProcessRunner(invocation) {
+    return new Promise((resolveResult, reject) => {
+        const childProcess = spawn(invocation.executable, invocation.args, {
+            cwd: invocation.cwd,
+            detached: process.platform !== 'win32',
+            env: createCodegraphEnvironment(),
+            shell: false
+        });
+        const timeout = setTimeout(() => {
+            terminateCodegraphProcess(childProcess);
+            reject(new Error(`codegraph process timed out after ${CODEGRAPH_PROCESS_TIMEOUT_MS}ms`));
+        }, CODEGRAPH_PROCESS_TIMEOUT_MS);
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutSize = 0;
+        let stderrSize = 0;
+        childProcess.stdout.on('data', (chunk) => {
+            try {
+                stdoutSize = assertOutputLimit(stdoutSize, chunk.length);
+                stdoutChunks.push(chunk);
+            }
+            catch (error) {
+                terminateCodegraphProcess(childProcess);
+                reject(error);
+            }
+        });
+        childProcess.stderr.on('data', (chunk) => {
+            try {
+                stderrSize = assertOutputLimit(stderrSize, chunk.length);
+                stderrChunks.push(chunk);
+            }
+            catch (error) {
+                terminateCodegraphProcess(childProcess);
+                reject(error);
+            }
+        });
+        childProcess.on('error', (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        childProcess.on('close', (exitCode) => {
+            clearTimeout(timeout);
+            resolveResult({
+                exitCode,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8')
+            });
+        });
+    });
+}

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

@@ -0,0 +1,43 @@
+declare const CODEGRAPH_PACKAGE_NAME = "@colbymchenry/codegraph";
+declare const CODEGRAPH_PACKAGE_VERSION = "0.7.10";
+declare const CODEGRAPH_EXECUTABLE: string;
+declare const ALLOWED_SUBCOMMANDS: readonly ["status", "init", "index", "query", "files", "context", "affected"];
+type CodegraphSubcommand = (typeof ALLOWED_SUBCOMMANDS)[number];
+type BaseCodegraphInvocationOptions = {
+    subcommand: CodegraphSubcommand;
+    project: string;
+    search?: string;
+    files?: string[];
+    json?: boolean;
+    quiet?: boolean;
+    yes?: boolean;
+    force?: boolean;
+    limit?: number;
+    maxDepth?: number;
+};
+type ContextCodegraphInvocationOptions = Omit<BaseCodegraphInvocationOptions, 'subcommand'> & {
+    subcommand: 'context';
+    task: string;
+};
+type NonContextCodegraphInvocationOptions = BaseCodegraphInvocationOptions & {
+    subcommand: Exclude<CodegraphSubcommand, 'context'>;
+    task?: never;
+};
+export type CodegraphInvocationOptions = ContextCodegraphInvocationOptions | NonContextCodegraphInvocationOptions;
+export type CodegraphInvocation = {
+    executable: typeof CODEGRAPH_EXECUTABLE;
+    args: string[];
+    cwd: string;
+    packageName: typeof CODEGRAPH_PACKAGE_NAME;
+    packageVersion: typeof CODEGRAPH_PACKAGE_VERSION;
+    subcommand: CodegraphSubcommand;
+};
+export type CodegraphExecutionResult = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+};
+export type CodegraphProcessRunner = (invocation: CodegraphInvocation) => Promise<CodegraphExecutionResult>;
+export declare function createCodegraphInvocation(options: CodegraphInvocationOptions): CodegraphInvocation;
+export declare function executeCodegraphInvocation(invocation: CodegraphInvocation, runner?: CodegraphProcessRunner): Promise<CodegraphExecutionResult>;
+export {};

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

@@ -0,0 +1,160 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
+const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
+const CODEGRAPH_EXECUTABLE = process.execPath;
+const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
+const POSITIONAL_ARGUMENT_PREFIX = '-';
+const ALLOWED_SUBCOMMANDS = ['status', 'init', 'index', 'query', 'files', 'context', 'affected'];
+const NUMERIC_FLAG_NAMES = ['limit', 'maxDepth'];
+const COMMON_OPTION_KEYS = ['subcommand', 'project'];
+const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
+    status: [],
+    init: ['yes'],
+    index: ['force', 'quiet'],
+    query: ['search', 'json', 'limit'],
+    files: ['json', 'maxDepth'],
+    context: ['task'],
+    affected: ['files', 'json']
+};
+function resolveCodegraphBinaryPath() {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
+    const binaryPath = resolve(dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js');
+    return binaryPath;
+}
+function assertSupportedSubcommand(subcommand) {
+    if (!ALLOWED_SUBCOMMANDS.includes(subcommand)) {
+        throw new Error(`Unsupported codegraph subcommand: ${subcommand}`);
+    }
+}
+function resolveProjectRoot(project) {
+    const projectRoot = resolve(project);
+    try {
+        if (!statSync(projectRoot).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        return realpathSync.native(projectRoot);
+    }
+    catch {
+        throw new Error('Project path must exist and be a directory');
+    }
+}
+function assertPositiveInteger(value, flagName) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${flagName} must be a positive integer`);
+    }
+}
+function assertPositionalArgument(value, argumentName) {
+    if (value.startsWith(POSITIONAL_ARGUMENT_PREFIX)) {
+        throw new Error(`${argumentName} must not start with -`);
+    }
+}
+function assertSupportedOptions(options) {
+    const allowedOptions = new Set(ALLOWED_OPTIONS_BY_SUBCOMMAND[options.subcommand]);
+    const presentOptionKeys = Object.keys(options).filter((key) => !COMMON_OPTION_KEYS.includes(key));
+    const unsupportedOption = presentOptionKeys.find((key) => !allowedOptions.has(key));
+    if (unsupportedOption) {
+        throw new Error(`Unsupported option ${unsupportedOption} for codegraph ${options.subcommand}`);
+    }
+}
+function assertRequiredOptions(options) {
+    if (options.subcommand === 'query' && (!options.search || options.search.trim() === '')) {
+        throw new Error('search must be non-empty');
+    }
+    if (options.subcommand === 'query' && options.search) {
+        assertPositionalArgument(options.search, 'search');
+    }
+    if (options.subcommand === 'context') {
+        assertPositionalArgument(options.task, 'task');
+    }
+}
+function assertInsideProject(projectRoot, absolutePath) {
+    const relativePath = relative(projectRoot, absolutePath);
+    if (relativePath === '' || relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        throw new Error('Affected files must stay inside the project');
+    }
+}
+function resolveExistingBoundary(absoluteFilePath) {
+    if (existsSync(absoluteFilePath)) {
+        return absoluteFilePath;
+    }
+    let currentPath = dirname(absoluteFilePath);
+    while (!existsSync(currentPath)) {
+        const parentPath = dirname(currentPath);
+        currentPath = parentPath;
+    }
+    return currentPath;
+}
+function normalizeProjectRelativeFile(projectRoot, file) {
+    assertPositionalArgument(file, 'Affected files');
+    const absoluteFilePath = resolve(projectRoot, file);
+    assertInsideProject(projectRoot, absoluteFilePath);
+    const realBoundary = realpathSync.native(resolveExistingBoundary(absoluteFilePath));
+    assertInsideProject(projectRoot, realBoundary);
+    return relative(projectRoot, absoluteFilePath).split(sep).join('/');
+}
+function buildAffectedFileArgs(projectRoot, files) {
+    if (!files || files.length < 1) {
+        throw new Error('affected requires at least one file');
+    }
+    return files.map((file) => normalizeProjectRelativeFile(projectRoot, file));
+}
+function buildCommandArgs(options, projectRoot) {
+    const args = [CODEGRAPH_BINARY_PATH, options.subcommand];
+    if (options.subcommand === 'query' && options.search) {
+        args.push(options.search);
+    }
+    if (options.subcommand === 'context') {
+        if (options.task.trim() === '') {
+            throw new Error('task must be non-empty');
+        }
+        args.push(options.task);
+    }
+    if (options.subcommand === 'affected') {
+        args.push(...buildAffectedFileArgs(projectRoot, options.files));
+    }
+    if (options.yes === true) {
+        args.push('--yes');
+    }
+    if (options.force === true) {
+        args.push('--force');
+    }
+    if (options.json === true) {
+        args.push('--json');
+    }
+    if (options.quiet === true) {
+        args.push('--quiet');
+    }
+    if (options.limit !== undefined) {
+        args.push('--limit', String(options.limit));
+    }
+    if (options.maxDepth !== undefined) {
+        args.push('--max-depth', String(options.maxDepth));
+    }
+    return args;
+}
+export function createCodegraphInvocation(options) {
+    assertSupportedSubcommand(options.subcommand);
+    const projectRoot = resolveProjectRoot(options.project);
+    assertSupportedOptions(options);
+    assertRequiredOptions(options);
+    assertPositiveInteger(options.limit, 'limit');
+    assertPositiveInteger(options.maxDepth, 'maxDepth');
+    return {
+        executable: CODEGRAPH_EXECUTABLE,
+        args: buildCommandArgs(options, projectRoot),
+        cwd: projectRoot,
+        packageName: CODEGRAPH_PACKAGE_NAME,
+        packageVersion: CODEGRAPH_PACKAGE_VERSION,
+        subcommand: options.subcommand
+    };
+}
+export async function executeCodegraphInvocation(invocation, runner = defaultCodegraphProcessRunner) {
+    return runner(invocation);
+}