gitnexus 1.6.11-rc.2 → 1.6.11-rc.21

package/dist/core/wiki/grok-client.js

@@ -0,0 +1,287 @@
+/**
+ * Grok Build CLI client for wiki generation.
+ *
+ * Uses headless `grok --prompt-file` so large wiki prompts are not placed on
+ * argv or stdin (Grok does not read stdin as the prompt).
+ */
+import { spawn, execFileSync } from 'child_process';
+import { StringDecoder } from 'string_decoder';
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { resolveWindowsCliCommand } from './local-cli-client.js';
+import { logger } from '../logger.js';
+// Verified live: an empty --tools allowlist does NOT disable the shell tool
+// (`run_terminal_cmd`) — Grok still ran `find` across the user's entire home
+// directory looking for project context, taking 10+ minutes per call and
+// then hitting --max-turns anyway. A denylist naming the tool explicitly is
+// what actually blocks it; internal tool IDs, not the CLI-facing names
+// (shell is `run_terminal_cmd`, not `bash`).
+const GROK_DISALLOWED_TOOLS = 'run_terminal_cmd,search_replace,web_search,web_fetch,spawn_subagent';
+// Defense in depth beyond the tool denylist: a kernel-enforced (Landlock/
+// Seatbelt) sandbox so reads/writes stay confined to --cwd (our empty temp
+// dir) + system paths even if a future tool slips past the denylist.
+const GROK_SANDBOX_PROFILE = 'strict';
+// Verified live with the denylist + sandbox above: turn counts vary run to
+// run (observed 3-10 across identical prompts, including the large overview
+// prompt that aggregates every module's summary). 15 gives real headroom
+// over that variance without leaving a runaway session effectively uncapped.
+const GROK_MAX_TURNS = '15';
+let cachedGrokCommand;
+function isVerbose() {
+    return process.env.GITNEXUS_VERBOSE === '1';
+}
+function verboseLog(...args) {
+    if (isVerbose()) {
+        logger.info({ args }, '[grok-cli]');
+    }
+}
+function killChildTree(child) {
+    if (process.platform === 'win32' && child.pid !== undefined) {
+        try {
+            execFileSync('taskkill', ['/T', '/F', '/PID', String(child.pid)], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            return;
+        }
+        catch {
+            // Process may have already exited — fall through to child.kill()
+        }
+    }
+    child.kill();
+}
+/** Returns `'grok'` when the CLI is on PATH, else null. Cached. */
+export function detectGrokCLI() {
+    if (cachedGrokCommand !== undefined)
+        return cachedGrokCommand?.displayName ?? null;
+    const resolved = resolveWindowsCliCommand('grok');
+    try {
+        execFileSync(resolved.command, [...resolved.argsPrefix, '--version'], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        cachedGrokCommand = resolved;
+    }
+    catch (err) {
+        const isNotFound = err instanceof Error && 'code' in err && err.code === 'ENOENT';
+        if (!isNotFound && err instanceof Error) {
+            logger.warn(`grok CLI found but --version failed (exit ${err.status ?? '?'}). ` +
+                'Ensure it is authenticated: run `grok --version` manually.');
+        }
+        cachedGrokCommand = null;
+    }
+    return cachedGrokCommand?.displayName ?? null;
+}
+function getDetectedGrokCommand() {
+    detectGrokCLI();
+    return cachedGrokCommand ?? null;
+}
+export function resolveGrokConfig(overrides) {
+    return {
+        model: overrides?.model,
+        requestTimeoutMs: overrides?.requestTimeoutMs,
+    };
+}
+function excerpt(raw, max = 200) {
+    const trimmed = raw.trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, max)}…`;
+}
+function parseGrokOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        throw new Error('grok CLI returned empty output');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        throw new Error(`grok CLI returned non-JSON output: ${excerpt(trimmed)}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`grok CLI JSON has no text field: ${excerpt(trimmed)}`);
+    }
+    const record = parsed;
+    if (record.type === 'error') {
+        throw new Error(record.message || 'grok CLI returned an error');
+    }
+    if (typeof record.text !== 'string') {
+        throw new Error(`grok CLI JSON has no text field: ${excerpt(trimmed)}`);
+    }
+    const content = record.text.trim();
+    if (!content) {
+        throw new Error('grok CLI returned empty text');
+    }
+    const rawReason = record.stopReason === undefined || record.stopReason === null
+        ? ''
+        : String(record.stopReason).trim();
+    if (rawReason.toLowerCase() !== 'end_turn') {
+        throw new Error(rawReason
+            ? `grok CLI stopped with stopReason=${rawReason}`
+            : 'grok CLI JSON is missing stopReason=end_turn');
+    }
+    return content;
+}
+/**
+ * Call Grok Build in headless mode and return the assistant text.
+ *
+ * `--cwd` is an empty temp directory (not the repo) so project AGENTS.md
+ * files are not injected into wiki generation.
+ */
+export async function callGrokLLM(prompt, config, systemPrompt, options) {
+    const grokCmd = getDetectedGrokCommand();
+    if (!grokCmd) {
+        throw new Error('Grok CLI not found. Install Grok Build and ensure `grok` is on PATH. Run `grok login` if unauthenticated.');
+    }
+    const fullPrompt = systemPrompt ? `${systemPrompt}\n\n---\n\n${prompt}` : prompt;
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-wiki-grok-'));
+    const promptPath = path.join(tempDir, 'prompt.txt');
+    const childLifecycle = { spawned: false, closed: false };
+    try {
+        await fs.writeFile(promptPath, fullPrompt, 'utf-8');
+        const args = [
+            '--prompt-file',
+            promptPath,
+            '--output-format',
+            'json',
+            '--max-turns',
+            GROK_MAX_TURNS,
+            '--no-plan',
+            '--no-subagents',
+            '--disable-web-search',
+            '--disallowed-tools',
+            GROK_DISALLOWED_TOOLS,
+            '--sandbox',
+            GROK_SANDBOX_PROFILE,
+            '--cwd',
+            tempDir,
+        ];
+        if (config.model) {
+            args.push('--model', config.model);
+        }
+        verboseLog('Spawning:', grokCmd.command, [...grokCmd.argsPrefix, ...args].join(' ').replace(promptPath, '[prompt-file]'));
+        if (config.model) {
+            verboseLog('Model:', config.model);
+        }
+        const content = await runGrok(grokCmd.command, [...grokCmd.argsPrefix, ...args], tempDir, config, options, childLifecycle);
+        return { content };
+    }
+    finally {
+        // Skip rm while a live child may still be using cwd/sandbox/prompt-file.
+        if (!childLifecycle.spawned || childLifecycle.closed) {
+            await fs.rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+}
+function runGrok(command, args, cwd, config, options, lifecycle) {
+    const startTime = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            // Prompt is --prompt-file; an unused stdin pipe can EPIPE the wiki process.
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            env: {
+                ...process.env,
+                CI: '1',
+            },
+        });
+        lifecycle.spawned = true;
+        verboseLog('Process spawned with PID:', child.pid);
+        let stdout = '';
+        let stderr = '';
+        const stdoutDecoder = new StringDecoder('utf8');
+        const stderrDecoder = new StringDecoder('utf8');
+        let settled = false;
+        let timedOut = false;
+        let killTimer;
+        let killEscalate;
+        let hardDeadline;
+        const timeoutMs = config.requestTimeoutMs;
+        const timeoutError = timeoutMs !== undefined && timeoutMs > 0
+            ? new Error(`grok CLI timed out after ${timeoutMs >= 60_000
+                ? `${Math.round(timeoutMs / 60_000)}m`
+                : `${Math.round(timeoutMs / 1_000)}s`}. Increase --timeout or omit it to disable the request timeout.`)
+            : undefined;
+        const clearKillTimers = () => {
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            if (killEscalate !== undefined)
+                clearTimeout(killEscalate);
+            if (hardDeadline !== undefined)
+                clearTimeout(hardDeadline);
+        };
+        const rejectOnce = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearKillTimers();
+            reject(error);
+        };
+        const resolveOnce = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearKillTimers();
+            resolve(value);
+        };
+        const KILL_GRACE_MS = 2000;
+        if (timeoutMs !== undefined && timeoutMs > 0 && timeoutError) {
+            killTimer = setTimeout(() => {
+                timedOut = true;
+                killChildTree(child);
+                killEscalate = setTimeout(() => {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // Process may have already exited.
+                    }
+                    hardDeadline = setTimeout(() => {
+                        rejectOnce(timeoutError);
+                    }, KILL_GRACE_MS);
+                }, KILL_GRACE_MS);
+            }, timeoutMs);
+        }
+        child.stdout.on('data', (chunk) => {
+            const chunkStr = stdoutDecoder.write(chunk);
+            stdout += chunkStr;
+            options?.onChunk?.(stdout.length);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += stderrDecoder.write(chunk);
+        });
+        child.on('close', (code) => {
+            const alreadySettled = settled;
+            lifecycle.closed = true;
+            stdout += stdoutDecoder.end();
+            stderr += stderrDecoder.end();
+            verboseLog(`Process exited with code ${code} after ${((Date.now() - startTime) / 1000).toFixed(1)}s`);
+            if (timedOut && timeoutError) {
+                rejectOnce(timeoutError);
+            }
+            else if (code !== 0) {
+                const details = stderr.trim() || stdout.trim();
+                rejectOnce(new Error(`grok CLI exited with code ${code}: ${details}`));
+            }
+            else {
+                try {
+                    resolveOnce(parseGrokOutput(stdout));
+                }
+                catch (err) {
+                    rejectOnce(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            if (alreadySettled) {
+                void fs.rm(cwd, { recursive: true, force: true }).catch(() => undefined);
+            }
+        });
+        child.on('error', (err) => {
+            lifecycle.closed = true;
+            rejectOnce(new Error(`Failed to spawn grok CLI: ${err.message}`));
+        });
+    });
+}

package/dist/core/wiki/llm-client.d.ts

@@ -6,7 +6,7 @@
  *
  * Config priority: CLI flags > env vars > defaults
  */
-export type LLMProvider = 'openai' | 'openrouter' | 'azure' | 'custom' | 'cursor' | 'claude' | 'codex' | 'opencode' | 'minimax';
+export type LLMProvider = 'openai' | 'openrouter' | 'azure' | 'custom' | 'cursor' | 'claude' | 'codex' | 'opencode' | 'grok' | 'minimax';
 export declare const MINIMAX_OPENAI_BASE_URLS: {
     readonly global_en: "https://api.minimax.io/v1";
     readonly cn_zh: "https://api.minimaxi.com/v1";

package/dist/core/wiki/llm-client.js

@@ -33,11 +33,14 @@ export async function resolveLLMConfig(overrides) {
                 ? savedConfig.codexModel
                 : savedProvider === 'opencode'
                     ? savedConfig.opencodeModel
-                    : undefined;
+                    : savedProvider === 'grok'
+                        ? savedConfig.grokModel
+                        : undefined;
     const localProvider = savedProvider === 'cursor' ||
         savedProvider === 'claude' ||
         savedProvider === 'codex' ||
-        savedProvider === 'opencode';
+        savedProvider === 'opencode' ||
+        savedProvider === 'grok';
     const apiKey = overrides?.apiKey ||
         (savedProvider === 'minimax' ? process.env.MINIMAX_API_KEY : undefined) ||
         (savedProvider !== 'minimax' ? process.env.GITNEXUS_API_KEY : undefined) ||

package/dist/core/wiki/local-cli-client.d.ts

@@ -11,8 +11,19 @@ export interface LocalCLIConfig {
     workingDirectory?: string;
     requestTimeoutMs?: number;
 }
+export interface ResolvedCliCommand {
+    displayName: string;
+    command: string;
+    argsPrefix: string[];
+}
 export declare function detectLocalCLI(provider: LocalAgentProvider): string | null;
 export declare function resolveLocalCLIConfig(overrides?: Partial<LocalCLIConfig>): LocalCLIConfig;
 export declare function callClaudeLLM(prompt: string, config: LocalCLIConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;
 export declare function callCodexLLM(prompt: string, config: LocalCLIConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;
 export declare function callOpenCodeLLM(prompt: string, config: LocalCLIConfig, systemPrompt?: string, options?: CallLLMOptions): Promise<LLMResponse>;
+/**
+ * Resolve a PATH command for spawn/execFile without a shell.
+ * On Windows, npm shims are `.cmd` files that Node cannot execFile/spawn
+ * directly — prefer a native `.exe` from `where.exe`, else `cmd.exe /d /s /c`.
+ */
+export declare function resolveWindowsCliCommand(displayName: string): ResolvedCliCommand;

package/dist/core/wiki/local-cli-client.js

@@ -281,10 +281,30 @@ function getDetectedCommand(provider) {
     detectLocalCLI(provider);
     return cachedCommands.get(provider) ?? null;
 }
+/**
+ * Resolve a PATH command for spawn/execFile without a shell.
+ * On Windows, npm shims are `.cmd` files that Node cannot execFile/spawn
+ * directly — prefer a native `.exe` from `where.exe`, else `cmd.exe /d /s /c`.
+ */
+export function resolveWindowsCliCommand(displayName) {
+    if (process.platform !== 'win32') {
+        return { displayName, command: displayName, argsPrefix: [] };
+    }
+    const located = findWindowsCommand(`${displayName}.cmd`) || findWindowsCommand(displayName);
+    if (located && /\.exe$/i.test(located)) {
+        return { displayName, command: located, argsPrefix: [] };
+    }
+    // Last-resort fallback for installations that only expose a .cmd shim.
+    return {
+        displayName,
+        command: process.env.ComSpec || 'cmd.exe',
+        argsPrefix: ['/d', '/s', '/c', displayName],
+    };
+}
 function resolveLocalCommand(provider) {
     const displayName = COMMANDS[provider];
     if (process.platform !== 'win32') {
-        return { displayName, command: displayName, argsPrefix: [] };
+        return resolveWindowsCliCommand(displayName);
     }
     const npmBin = findWindowsCommand(`${displayName}.cmd`) || findWindowsCommand(displayName);
     if (npmBin) {
@@ -302,14 +322,7 @@ function resolveLocalCommand(provider) {
             }
         }
     }
-    // Last-resort fallback for non-npm Windows installations that only expose a
-    // .cmd shim. Prompts are passed via stdin, so repo content is not placed on
-    // the command line.
-    return {
-        displayName,
-        command: process.env.ComSpec || 'cmd.exe',
-        argsPrefix: ['/d', '/s', '/c', displayName],
-    };
+    return resolveWindowsCliCommand(displayName);
 }
 function findWindowsCommand(command) {
     try {

package/dist/mcp/local/local-backend.d.ts

@@ -371,10 +371,26 @@ export declare class LocalBackend {
      * - If only 1 repo, use it
      * - If 0 or multiple without param, throw with helpful message
      *
-     * On a miss, re-reads the registry once in case a new repo was indexed
-     * while the MCP server was running.
+     * Re-reads the registry before an omitted implicit target or after an
+     * explicit miss, so long-running servers see newly indexed repositories.
      */
     resolveRepo(repoParam?: string, branch?: string): Promise<RepoHandle>;
+    /**
+     * Internal resolver variant for CLI/MCP tool routing and discovery.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If multiple repos exist and repoParam is omitted, callers may opt in to
+     *   the registered repo containing process.cwd()
+     * - If 0 repos exist, or cwd cannot disambiguate multiple repos, throw
+     *
+     * Omitted-repo resolution re-reads the registry before accepting any
+     * implicit target, including a cached singleton. A caller that just obtained
+     * a fresh registry snapshot may disable that refresh explicitly.
+     */
+    selectToolRepository(repoParam?: string, branch?: string, options?: {
+        allowCwdDefault?: boolean;
+        refreshRegistry?: boolean;
+    }): Promise<RepoHandle>;
     /**
      * Re-point a resolved repo handle at a specific branch index (#2106).
      *
@@ -409,12 +425,13 @@ export declare class LocalBackend {
      */
     private resolveRepoFromCache;
     /**
-     * Prefer the indexed repo whose path matches the git root of process.cwd().
+     * Match process.cwd() against indexed repositories.
      *
-     * In MCP stdio server mode, `process.cwd()` is the server's launch directory,
-     * not the agent client's cwd. If the server was started from an unrelated
-     * directory, `getGitRoot` returns null and duplicate-name resolution throws
-     * {@link RegistryAmbiguousTargetError} — callers should pass an absolute path.
+     * Explicit duplicate aliases use exact Git-root matching only. Omitted
+     * read-only calls opt into deepest containing-path selection. In that mode a
+     * candidate must not sit above cwd's Git root, so an unindexed nested checkout
+     * cannot fall through to an indexed ancestor. The `.git` ancestor fallback
+     * preserves that boundary when the git executable is unavailable.
      */
     private pickRepoHandleForCwd;
     private handleToRegistryEntry;