gitnexus 1.6.6-rc.98 → 1.6.6

package/dist/cli/i18n/zh-CN.js

@@ -143,7 +143,7 @@ export const zhCN = {
     'help.option.analyze.maxFileSize': '跳过大于该值的文件（KB）。默认：512。硬上限：32768（tree-sitter 限制）。',
     'help.option.analyze.workerTimeout': 'Worker 子批次空闲超时，超时后重试/回退。默认：30。',
     'help.option.analyze.walCheckpointThreshold': 'analyze 期间 LadybugDB WAL 自动 checkpoint 阈值（字节，整数 >= -1；默认：67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。',
-    'help.option.analyze.workers': '解析 worker 池大小。默认：cores-1，最多 16。传 0 禁用 worker（顺序执行）。',
+    'help.option.analyze.workers': '解析 worker 池大小（>=1）。默认：cores-1，最多 16，按仓库规模自适应。',
     'help.option.analyze.embeddingThreads': '限制本地 ONNX 嵌入 CPU 线程数',
     'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
     'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',
@@ -156,7 +156,7 @@ export const zhCN = {
     'help.option.clean.all': '清理所有已索引仓库',
     'help.option.clean.lbugSidecars': '清理已隔离的 LadybugDB missing-shadow WAL sidecar',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
-    'help.option.wiki.provider': 'LLM 提供商：openai、openrouter、azure、custom、cursor、claude 或 codex（默认：openai）',
+    'help.option.wiki.provider': 'LLM 提供商：openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：openai）',
     'help.option.wiki.model': 'LLM 模型或 Azure deployment 名称（默认：minimax/minimax-m2.5）',
     'help.option.wiki.baseUrl': 'LLM API base URL。Azure v1：https://{resource}.openai.azure.com/openai/v1',
     'help.option.wiki.apiKey': 'LLM API key 或 Azure api-key（保存到 ~/.gitnexus/config.json）',

package/dist/cli/index.js

@@ -27,6 +27,8 @@ program
     .option('--skills', 'Generate repo-specific skill files from detected communities ' +
     '(no-op when --index-only is also set).')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
+    .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
+    'Falls back to .gitnexusrc, then auto-detected origin/HEAD, then "main".')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-skills', 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
     'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +
@@ -42,7 +44,7 @@ program
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
     .option('--wal-checkpoint-threshold <bytes>', 'LadybugDB WAL auto-checkpoint threshold in bytes during analyze ' +
     '(integer >= -1; default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).')
-    .option('--workers <n>', 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).')
+    .option('--workers <n>', 'Parse worker pool size (>=1). Default: cores-1 capped at 16, auto-sized to the repo.')
     .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
@@ -94,7 +96,7 @@ program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')
     .option('-f, --force', 'Force full regeneration even if up to date')
-    .option('--provider <provider>', 'LLM provider: openai, openrouter, azure, custom, cursor, claude, or codex (default: openai)')
+    .option('--provider <provider>', 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)')
     .option('--model <model>', 'LLM model or Azure deployment name (default: minimax/minimax-m2.5)')
     .option('--base-url <url>', 'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1')
     .option('--api-key <key>', 'LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)')

package/dist/cli/resolve-invocation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * npm 11.x npx-install-crash nudge for the `analyze` command (#1939).
+ *
+ * The gitnexus/pnpm/npx selection itself lives in the canonical hook helper
+ * (hooks/claude/resolve-analyze-cmd.cjs) — self-contained CJS because the copied
+ * hook runtime cannot import from the package. We reuse it here via createRequire
+ * instead of re-implementing it, so there is one source of truth for the
+ * invocation decision. This module adds only the npm-version probe and the
+ * warning, which are CLI-only. The relative path resolves identically from
+ * src/cli/ (tsx, vitest) and dist/cli/ (shipped), since both sit one level under
+ * the package root and `hooks/` is published.
+ */
+declare const NPX_REF: string;
+export { NPX_REF };
+export declare function getNpmMajorVersion(): number | null;
+/**
+ * One-line stderr nudge when an npm 11+ user is on the npx install path (#1939).
+ * Skipped when a global `gitnexus` or `pnpm` is already preferred, so it never
+ * nags users who are not exposed to the npx/arborist crash.
+ */
+export declare function warnIfNpm11NpxRisk(): void;

package/dist/cli/resolve-invocation.js

@@ -0,0 +1,68 @@
+/**
+ * npm 11.x npx-install-crash nudge for the `analyze` command (#1939).
+ *
+ * The gitnexus/pnpm/npx selection itself lives in the canonical hook helper
+ * (hooks/claude/resolve-analyze-cmd.cjs) — self-contained CJS because the copied
+ * hook runtime cannot import from the package. We reuse it here via createRequire
+ * instead of re-implementing it, so there is one source of truth for the
+ * invocation decision. This module adds only the npm-version probe and the
+ * warning, which are CLI-only. The relative path resolves identically from
+ * src/cli/ (tsx, vitest) and dist/cli/ (shipped), since both sit one level under
+ * the package root and `hooks/` is published.
+ */
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+const { resolveInvocationMode, formatDocumentationDlxCommand, NPX_REF } = createRequire(import.meta.url)('../../hooks/claude/resolve-analyze-cmd.cjs');
+// Fail loud at module load if the canonical cjs export shape drifts (e.g. a
+// renamed export), rather than as a late TypeError inside warnIfNpm11NpxRisk.
+if (typeof resolveInvocationMode !== 'function' ||
+    typeof formatDocumentationDlxCommand !== 'function' ||
+    typeof NPX_REF !== 'string') {
+    throw new Error('resolve-analyze-cmd.cjs must export resolveInvocationMode (function), formatDocumentationDlxCommand (function), and NPX_REF (string)');
+}
+export { NPX_REF };
+// Re-implemented here (rather than reusing the cjs export) so vitest's
+// `vi.mock('node:child_process')` intercepts it — the cjs uses bare
+// `require('child_process')`, which the mock cannot reach. Timeout matches the
+// cjs PROBE_TIMEOUT_MS (1s) so this CLI probe shares the same hook-budget cap;
+// `npm --version` is a sub-second local call.
+export function getNpmMajorVersion() {
+    try {
+        const output = execFileSync('npm', ['--version'], {
+            encoding: 'utf-8',
+            timeout: 1000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            // Windows `npm` is a `.cmd` shim; without a shell execFileSync ENOENTs
+            // (CVE-2024-27980) and the npm-11 npx-crash warning below would never
+            // fire on Windows. Mirrors probeVersion in resolve-analyze-cmd.cjs.
+            shell: process.platform === 'win32',
+        });
+        // Read the first version-shaped line so a Corepack/update banner on stdout
+        // doesn't defeat the parse (mirrors the cjs probeVersion hardening).
+        const major = output
+            .split('\n')
+            .map((l) => l.trim())
+            .find((l) => /^v?\d+\./.test(l))
+            ?.match(/^v?(\d+)\./);
+        return major ? Number(major[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One-line stderr nudge when an npm 11+ user is on the npx install path (#1939).
+ * Skipped when a global `gitnexus` or `pnpm` is already preferred, so it never
+ * nags users who are not exposed to the npx/arborist crash.
+ */
+export function warnIfNpm11NpxRisk() {
+    if (resolveInvocationMode() !== 'npx')
+        return;
+    const major = getNpmMajorVersion();
+    if (major === null || major < 11)
+        return;
+    process.stderr.write(`Warning: npm ${major}.x can crash while installing gitnexus via npx ` +
+        `(npm/arborist "node.target is null"). Prefer: ${formatDocumentationDlxCommand('analyze')} ` +
+        `or npm install -g ${NPX_REF}. See https://github.com/abhigyanpatwari/GitNexus/issues/1939\n`);
+}

package/dist/cli/setup.d.ts

@@ -5,4 +5,37 @@
  * Detects installed AI editors and writes the appropriate MCP config
  * so the GitNexus MCP server is available in all projects.
  */
+/**
+ * Build the `command` string written into an editor's hook settings, which the
+ * editor shell-evaluates. `hookPath` is already forward-slash-normalized.
+ *
+ * On POSIX, single-quote the path: a single-quoted shell string expands nothing,
+ * so spaces and metacharacters ($, backtick, ;, |, &, newline, parens) in the
+ * install path cannot run as commands. The only character needing escaping
+ * inside single quotes is the single quote, via the standard `'\''` idiom
+ * (close, literal-quote, reopen). The previous double-quoted `node "..."` form
+ * left $/backtick live — a code-execution risk for an adversarial $HOME.
+ *
+ * On Windows, filenames cannot contain these POSIX metacharacters and the path
+ * is forward-slashed, so keep the double-quoted form with backslash-then-quote
+ * escaping (CodeQL js/incomplete-sanitization safe ordering).
+ */
+export declare function formatHookCommand(hookPath: string, isWindows?: boolean): string;
+interface SetupResult {
+    configured: string[];
+    skipped: string[];
+    errors: string[];
+}
+/**
+ * Copy the shared hook helpers from `srcDir` into `destDir`. The adapters
+ * top-level `require()` the `.cjs` helpers, so a missing required helper makes
+ * the installed hook crash with MODULE_NOT_FOUND. A failed copy is recorded as a
+ * setup error, and the names of any failed REQUIRED helpers are returned so the
+ * caller can fail closed (skip hook registration) instead of registering a hook
+ * that crashes at runtime. `win-rm-list-json.ps1` is best-effort — its absence is
+ * recorded but does not gate registration. Both the Claude and Antigravity
+ * install paths copy this same list from hooks/claude/ (the canonical source).
+ */
+export declare function copyHookHelpers(srcDir: string, destDir: string, label: string, result: SetupResult): Promise<string[]>;
 export declare const setupCommand: () => Promise<void>;
+export {};

package/dist/cli/setup.js

@@ -28,7 +28,38 @@ const _pkg = _require('../../package.json');
 if (typeof _pkg.version !== 'string' || !_pkg.version) {
     throw new Error('gitnexus/package.json#version is missing or not a string — cannot generate MCP fallback config.');
 }
-const NPX_REF = `gitnexus@${_pkg.version}`;
+// Version-pinned ref for the persisted MCP entry — deliberately distinct from
+// the cjs's exported `gitnexus@latest` hint ref (resolve-analyze-cmd.cjs); the
+// two are not unified (see the comment above and that file's MCP_PINNED_REF).
+const MCP_PINNED_REF = `gitnexus@${_pkg.version}`;
+/**
+ * Build the `command` string written into an editor's hook settings, which the
+ * editor shell-evaluates. `hookPath` is already forward-slash-normalized.
+ *
+ * On POSIX, single-quote the path: a single-quoted shell string expands nothing,
+ * so spaces and metacharacters ($, backtick, ;, |, &, newline, parens) in the
+ * install path cannot run as commands. The only character needing escaping
+ * inside single quotes is the single quote, via the standard `'\''` idiom
+ * (close, literal-quote, reopen). The previous double-quoted `node "..."` form
+ * left $/backtick live — a code-execution risk for an adversarial $HOME.
+ *
+ * On Windows, filenames cannot contain these POSIX metacharacters and the path
+ * is forward-slashed, so keep the double-quoted form with backslash-then-quote
+ * escaping (CodeQL js/incomplete-sanitization safe ordering).
+ */
+export function formatHookCommand(hookPath, isWindows = process.platform === 'win32') {
+    if (isWindows) {
+        const escaped = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return `node "${escaped}"`;
+    }
+    return `node '${hookPath.replace(/'/g, "'\\''")}'`;
+}
+// The exact source line each hook adapter ships, rewritten at install time to
+// point cliPath at the installed CLI. Kept as a named constant so the install
+// patch and its drift guard reference one string — if the adapter source ever
+// changes this literal, the guard records an actionable error instead of
+// silently shipping a hook with an unresolved relative cliPath.
+const CLI_PATH_SOURCE_LITERAL = "let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');";
 /**
  * Resolve the absolute path to the `gitnexus` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
@@ -83,12 +114,12 @@ function getMcpEntry() {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', NPX_REF, 'mcp'],
+            args: ['/c', 'npx', '-y', MCP_PINNED_REF, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', NPX_REF, 'mcp'],
+        args: ['-y', MCP_PINNED_REF, 'mcp'],
     };
 }
 /**
@@ -101,9 +132,9 @@ function getOpenCodeMcpEntry() {
         return { type: 'local', command: [bin, 'mcp'] };
     }
     if (process.platform === 'win32') {
-        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', NPX_REF, 'mcp'] };
+        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', MCP_PINNED_REF, 'mcp'] };
     }
-    return { type: 'local', command: ['npx', '-y', NPX_REF, 'mcp'] };
+    return { type: 'local', command: ['npx', '-y', MCP_PINNED_REF, 'mcp'] };
 }
 /**
  * Detect indentation style from file content.
@@ -281,6 +312,42 @@ async function mergeHooksJsonc(filePath, entries) {
     await fs.writeFile(filePath, current, 'utf-8');
     return true;
 }
+const HOOK_HELPERS = [
+    'hook-lock.cjs',
+    'hook-db-lock-probe.cjs',
+    'win-rm-list-json.ps1',
+    'resolve-analyze-cmd.cjs',
+];
+// win-rm-list-json.ps1 is best-effort: it is read (not require()'d) by
+// hook-db-lock-probe.cjs only on Windows, and that probe fails open when the
+// script is absent. Every other helper is top-level require()'d by the adapters,
+// so its absence crashes the installed hook — those are the ones a failed copy
+// must gate hook registration on (see copyHookHelpers' return value).
+const BEST_EFFORT_HOOK_HELPERS = new Set(['win-rm-list-json.ps1']);
+/**
+ * Copy the shared hook helpers from `srcDir` into `destDir`. The adapters
+ * top-level `require()` the `.cjs` helpers, so a missing required helper makes
+ * the installed hook crash with MODULE_NOT_FOUND. A failed copy is recorded as a
+ * setup error, and the names of any failed REQUIRED helpers are returned so the
+ * caller can fail closed (skip hook registration) instead of registering a hook
+ * that crashes at runtime. `win-rm-list-json.ps1` is best-effort — its absence is
+ * recorded but does not gate registration. Both the Claude and Antigravity
+ * install paths copy this same list from hooks/claude/ (the canonical source).
+ */
+export async function copyHookHelpers(srcDir, destDir, label, result) {
+    const failedRequired = [];
+    for (const helper of HOOK_HELPERS) {
+        try {
+            await fs.copyFile(path.join(srcDir, helper), path.join(destDir, helper));
+        }
+        catch {
+            result.errors.push(`${label}: failed to copy ${helper} — hook may crash at runtime`);
+            if (!BEST_EFFORT_HOOK_HELPERS.has(helper))
+                failedRequired.push(helper);
+        }
+    }
+    return failedRequired;
+}
 /**
  * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
  * Merges hook config without overwriting existing hooks, preserving
@@ -304,37 +371,32 @@ async function installClaudeCodeHooks(result) {
             const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
-            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
+            if (!content.includes(CLI_PATH_SOURCE_LITERAL)) {
+                result.errors.push('Claude Code hooks: gitnexus-hook.cjs no longer contains the cliPath literal to patch — the installed hook may fail to resolve the CLI. Update CLI_PATH_SOURCE_LITERAL in setup.ts.');
+            }
+            content = content.replace(CLI_PATH_SOURCE_LITERAL, `let cliPath = ${jsonCli};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {
             // Script not found in source — skip
         }
+        // Fail closed: registering the hook without its adapter would crash on every
+        // tool invocation. Mirrors the Antigravity adapter guard below (this path
+        // previously registered regardless of whether the adapter wrote).
         try {
-            await fs.copyFile(path.join(pluginHooksPath, 'hook-lock.cjs'), path.join(destHooksDir, 'hook-lock.cjs'));
+            await fs.access(dest);
         }
         catch {
-            // Helper not found in source — skip
-        }
-        try {
-            await fs.copyFile(path.join(pluginHooksPath, 'hook-db-lock-probe.cjs'), path.join(destHooksDir, 'hook-db-lock-probe.cjs'));
-        }
-        catch {
-            // Helper not found in source — skip
-        }
-        try {
-            await fs.copyFile(path.join(pluginHooksPath, 'win-rm-list-json.ps1'), path.join(destHooksDir, 'win-rm-list-json.ps1'));
+            result.errors.push('Claude Code hooks: adapter script was not installed — skipping hook registration');
+            return;
         }
-        catch {
-            // Helper not found in source — skip
+        const failedRequired = await copyHookHelpers(pluginHooksPath, destHooksDir, 'Claude Code hooks', result);
+        if (failedRequired.length > 0) {
+            result.errors.push(`Claude Code hooks: required helper(s) ${failedRequired.join(', ')} failed to copy — skipping hook registration`);
+            return;
         }
         const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
-        // Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization).
-        // The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote`
-        // become `path\with\"quote`, where the trailing `\` before `"` could
-        // unescape the quote inside the surrounding double-quoted shell context.
-        const escapedHookPath = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        const hookCmd = `node "${escapedHookPath}"`;
+        const hookCmd = formatHookCommand(hookPath);
         // Check which hook events need entries (idempotent: skip if already registered)
         const parsed = await (async () => {
             try {
@@ -483,7 +545,10 @@ async function installAntigravityHooks(result) {
             const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
-            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
+            if (!content.includes(CLI_PATH_SOURCE_LITERAL)) {
+                result.errors.push('Antigravity hooks: gitnexus-antigravity-hook.cjs no longer contains the cliPath literal to patch — the installed hook may fail to resolve the CLI. Update CLI_PATH_SOURCE_LITERAL in setup.ts.');
+            }
+            content = content.replace(CLI_PATH_SOURCE_LITERAL, `let cliPath = ${jsonCli};`);
             await fs.writeFile(adapterDest, content, 'utf-8');
         }
         catch {
@@ -503,17 +568,13 @@ async function installAntigravityHooks(result) {
         // required by hook-db-lock-probe.cjs on Windows — without it, the MCP
         // server ownership probe silently fails open and the hook may contend
         // with the MCP server on the LadybugDB.
-        for (const helper of ['hook-lock.cjs', 'hook-db-lock-probe.cjs', 'win-rm-list-json.ps1']) {
-            try {
-                await fs.copyFile(path.join(pluginClaudeDir, helper), path.join(destHooksDir, helper));
-            }
-            catch {
-                result.errors.push(`Antigravity hooks: failed to copy ${helper} — hook may crash at runtime`);
-            }
+        const failedRequired = await copyHookHelpers(pluginClaudeDir, destHooksDir, 'Antigravity hooks', result);
+        if (failedRequired.length > 0) {
+            result.errors.push(`Antigravity hooks: required helper(s) ${failedRequired.join(', ')} failed to copy — skipping hook registration`);
+            return;
         }
         const hookPath = path.join(destHooksDir, 'gitnexus-antigravity-hook.cjs').replace(/\\/g, '/');
-        const escapedHookPath = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        const hookCmd = `node "${escapedHookPath}"`;
+        const hookCmd = formatHookCommand(hookPath);
         const parsed = await (async () => {
             try {
                 const r = await fs.readFile(settingsPath, 'utf-8');

package/dist/cli/skill-gen.js

@@ -482,8 +482,8 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
             : community.label;
     lines.push('## How to Explore');
     lines.push('');
-    lines.push(`1. \`gitnexus_context({name: "${firstEntry}"})\` \u2014 see callers and callees`);
-    lines.push(`2. \`gitnexus_query({query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
+    lines.push(`1. \`context({name: "${firstEntry}"})\` \u2014 see callers and callees`);
+    lines.push(`2. \`query({query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
     lines.push('3. Read key files listed above for implementation details');
     lines.push('');
     return lines.join('\n');

package/dist/cli/wiki.js

@@ -29,14 +29,21 @@ function parsePositiveIntegerOption(value, flag, multiplier = 1) {
     return parsed;
 }
 function isLocalProvider(provider) {
-    return provider === 'cursor' || provider === 'claude' || provider === 'codex';
+    return (provider === 'cursor' ||
+        provider === 'claude' ||
+        provider === 'codex' ||
+        provider === 'opencode');
 }
 function localModelConfigKey(provider) {
     if (provider === 'cursor')
         return 'cursorModel';
     if (provider === 'claude')
         return 'claudeModel';
-    return 'codexModel';
+    if (provider === 'codex')
+        return 'codexModel';
+    if (provider === 'opencode')
+        return 'opencodeModel';
+    throw new Error(`Unsupported local provider: ${provider}`);
 }
 /**
  * Prompt the user for input via stdin.
@@ -212,7 +219,7 @@ const wikiCommandImpl = async (inputPath, options) => {
             if (!llmConfig.apiKey && !isLocalProvider(llmConfig.provider)) {
                 console.log('  Error: No LLM API key found.');
                 console.log('  Set OPENAI_API_KEY or GITNEXUS_API_KEY environment variable,');
-                console.log('  or pass --api-key <key>, or use --provider cursor|claude|codex.\n');
+                console.log('  or pass --api-key <key>, or use --provider cursor|claude|codex|opencode.\n');
                 process.exitCode = 1;
                 return;
             }
@@ -220,11 +227,12 @@ const wikiCommandImpl = async (inputPath, options) => {
         }
         else {
             console.log("  No LLM configured. Let's set it up.\n");
-            console.log('  Supports OpenAI, OpenRouter, Azure, any OpenAI-compatible API, Cursor CLI, Claude CLI, or Codex CLI.\n');
+            console.log('  Supports OpenAI, OpenRouter, Azure, any OpenAI-compatible API, Cursor CLI, Claude CLI, Codex CLI, or OpenCode CLI.\n');
             // Check if local agent CLIs are available.
             const hasCursor = detectCursorCLI();
             const hasClaude = detectLocalCLI('claude');
             const hasCodex = detectLocalCLI('codex');
+            const hasOpenCode = detectLocalCLI('opencode');
             const localChoices = [];
             // Provider selection
             console.log('  [1] OpenAI (api.openai.com)');
@@ -256,6 +264,14 @@ const wikiCommandImpl = async (inputPath, options) => {
                 });
                 console.log(`  [${choice}] Codex CLI (local, uses your Codex login)`);
             }
+            if (hasOpenCode) {
+                const choice = String(nextChoice++);
+                localChoices.push({
+                    choice,
+                    provider: 'opencode',
+                });
+                console.log(`  [${choice}] OpenCode CLI (local, uses your OpenCode login/config)`);
+            }
             console.log('');
             const maxChoice = String(nextChoice - 1);
             const choice = await prompt(`  Select provider (1/${maxChoice}): `);

package/dist/core/embeddings/embedder.d.ts

@@ -6,7 +6,7 @@
  *
  * Uses snowflake-arctic-embed-xs by default (22M params, 384 dims, ~90MB)
  */
-import { type FeatureExtractionPipeline } from '@huggingface/transformers';
+import type { FeatureExtractionPipeline } from '@huggingface/transformers';
 import { type EmbeddingConfig, type ModelProgress } from './types.js';
 /**
  * Progress callback type for model loading

package/dist/core/embeddings/embedder.js

@@ -12,7 +12,6 @@
 if (!process.env.ORT_LOG_LEVEL) {
     process.env.ORT_LOG_LEVEL = '3';
 }
-import { pipeline, env, } from '@huggingface/transformers';
 import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { join, dirname } from 'path';
@@ -21,6 +20,7 @@ import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
 import { resolveEmbeddingConfig } from './config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
+import { getLocalEmbeddingRuntimeBlocker } from './runtime-support.js';
 import { logger } from '../logger.js';
 /**
  * Check whether the onnxruntime-node package that @huggingface/transformers
@@ -117,6 +117,16 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
         throw new Error('initEmbedder() should not be called in HTTP mode. ' +
             'Use embedText()/embedBatch() which handle HTTP transparently.');
     }
+    // Fail fast on platforms where the bundled native ONNX Runtime binding is not
+    // shipped (macOS Intel, #1515). Must run before any transformers.js /
+    // onnxruntime-node import or resolution — otherwise the native module load
+    // crashes with a raw "Cannot find module ...onnxruntime_binding.node" that
+    // ONNX_WEB_BACKEND=wasm cannot rescue (#1516). HTTP mode was already handled
+    // above, so this only blocks the local-runtime path.
+    const runtimeBlocker = getLocalEmbeddingRuntimeBlocker();
+    if (runtimeBlocker) {
+        throw new Error(runtimeBlocker);
+    }
     // Return existing instance if available
     if (embedderInstance) {
         return embedderInstance;
@@ -135,6 +145,9 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
     const requestedDevice = forceDevice || (finalConfig.device === 'auto' ? gpuDevice : finalConfig.device);
     initPromise = (async () => {
         try {
+            // Lazy-load transformers.js only after the runtime guard has passed, so
+            // unsupported platforms never reach the native ONNX import (#1515).
+            const { pipeline, env } = await import('@huggingface/transformers');
             // Configure transformers.js environment
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →

package/dist/core/embeddings/runtime-support.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Local embedding runtime support guard.
+ *
+ * The bundled local embedding stack (`@huggingface/transformers` →
+ * `onnxruntime-node`) only ships native ONNX Runtime bindings for a subset of
+ * platform/arch pairs. On macOS Intel (`darwin`/`x64`), `onnxruntime-node`
+ * ships no `bin/napi-v6/darwin/x64/onnxruntime_binding.node`, so *importing*
+ * transformers.js throws a raw `Cannot find module ...onnxruntime_binding.node`
+ * before any device/backend selection can run (#1515). `ONNX_WEB_BACKEND=wasm`
+ * cannot rescue this — the failure is at native-module import time, not backend
+ * selection (#1516).
+ *
+ * This module is intentionally free of any native or transformers.js import (at
+ * module scope or inside its functions) so it can be consulted *before* the
+ * dynamic import that would crash. HTTP embedding mode never touches the native
+ * runtime, so callers in HTTP mode must skip this guard.
+ */
+export interface LocalEmbeddingRuntimeOptions {
+    platform?: NodeJS.Platform;
+    arch?: NodeJS.Architecture;
+}
+/**
+ * Return a human-readable explanation when the *local* embedding runtime cannot
+ * load on this platform, or `null` when local embeddings are expected to work.
+ *
+ * Only `darwin`/`x64` is blocked today: it is the one platform/arch pair where
+ * the bundled `onnxruntime-node` ships no native binding (#1515). Every other
+ * platform returns `null` and follows the normal device-probe path, so genuine
+ * ONNX failures on supported platforms are never masked by this message.
+ *
+ * Accepts an explicit `{ platform, arch }` for testing; defaults to the current
+ * process values.
+ */
+export declare const getLocalEmbeddingRuntimeBlocker: (options?: LocalEmbeddingRuntimeOptions) => string | null;
+/**
+ * True when `message` is the macOS-Intel local-embedding blocker produced by
+ * {@link getLocalEmbeddingRuntimeBlocker}. Lets the CLI surface a clean,
+ * actionable message instead of a raw stack trace, without coupling to the
+ * full wording.
+ */
+export declare const isLocalEmbeddingRuntimeBlockerMessage: (message: string) => boolean;

package/dist/core/embeddings/runtime-support.js

@@ -0,0 +1,65 @@
+/**
+ * Local embedding runtime support guard.
+ *
+ * The bundled local embedding stack (`@huggingface/transformers` →
+ * `onnxruntime-node`) only ships native ONNX Runtime bindings for a subset of
+ * platform/arch pairs. On macOS Intel (`darwin`/`x64`), `onnxruntime-node`
+ * ships no `bin/napi-v6/darwin/x64/onnxruntime_binding.node`, so *importing*
+ * transformers.js throws a raw `Cannot find module ...onnxruntime_binding.node`
+ * before any device/backend selection can run (#1515). `ONNX_WEB_BACKEND=wasm`
+ * cannot rescue this — the failure is at native-module import time, not backend
+ * selection (#1516).
+ *
+ * This module is intentionally free of any native or transformers.js import (at
+ * module scope or inside its functions) so it can be consulted *before* the
+ * dynamic import that would crash. HTTP embedding mode never touches the native
+ * runtime, so callers in HTTP mode must skip this guard.
+ */
+/**
+ * Stable lead line of the macOS-Intel blocker message. Also used to recognise
+ * the thrown error in the CLI error handler without coupling to the full
+ * wording (see {@link isLocalEmbeddingRuntimeBlockerMessage}).
+ */
+const LOCAL_EMBEDDING_BLOCKER_LEAD = 'Local semantic embeddings are unavailable on macOS Intel (darwin/x64).';
+/**
+ * Return a human-readable explanation when the *local* embedding runtime cannot
+ * load on this platform, or `null` when local embeddings are expected to work.
+ *
+ * Only `darwin`/`x64` is blocked today: it is the one platform/arch pair where
+ * the bundled `onnxruntime-node` ships no native binding (#1515). Every other
+ * platform returns `null` and follows the normal device-probe path, so genuine
+ * ONNX failures on supported platforms are never masked by this message.
+ *
+ * Accepts an explicit `{ platform, arch }` for testing; defaults to the current
+ * process values.
+ */
+export const getLocalEmbeddingRuntimeBlocker = (options = {}) => {
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    if (platform === 'darwin' && arch === 'x64') {
+        return [
+            LOCAL_EMBEDDING_BLOCKER_LEAD,
+            'The bundled ONNX Runtime package (onnxruntime-node) does not ship a',
+            'darwin/x64 native binding, so the local embedding model cannot load here.',
+            'ONNX_WEB_BACKEND=wasm does not help: the failure happens while importing',
+            'the native runtime, before any backend can be selected. Forcing',
+            'GITNEXUS_EMBEDDING_DEVICE=wasm (or cpu) does not help either, for the same reason.',
+            '',
+            'Use one of these instead:',
+            '  - Run analyze without --embeddings (all other indexing still works).',
+            '  - Point GITNEXUS_EMBEDDING_URL (with GITNEXUS_EMBEDDING_MODEL) at an',
+            '    OpenAI-compatible /v1/embeddings endpoint to embed over HTTP.',
+            '  - Run GitNexus on Linux or in Docker, where the native binding ships.',
+            '  - Run GitNexus on Apple Silicon (darwin/arm64), which ships a binding.',
+            '  - Use a future GitNexus build that restores darwin/x64 ONNX support.',
+        ].join('\n');
+    }
+    return null;
+};
+/**
+ * True when `message` is the macOS-Intel local-embedding blocker produced by
+ * {@link getLocalEmbeddingRuntimeBlocker}. Lets the CLI surface a clean,
+ * actionable message instead of a raw stack trace, without coupling to the
+ * full wording.
+ */
+export const isLocalEmbeddingRuntimeBlockerMessage = (message) => message.includes(LOCAL_EMBEDDING_BLOCKER_LEAD);

package/dist/core/group/extractors/grpc-patterns/proto.js

@@ -11,7 +11,8 @@ import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js
  *
  * The grammar is vendored in `vendor/tree-sitter-proto/` with
  * parser.c regenerated against tree-sitter-cli 0.24 (ABI version 14)
- * so it is compatible with the project's tree-sitter 0.25 runtime.
+ * so it is compatible with the project's tree-sitter 0.21.1 runtime
+ * (which loads ABI 13–14).
  */
 const _require = createRequire(import.meta.url);
 let ProtoGrammar = null;