gitnexus 1.6.11-rc.2 → 1.6.11-rc.4

package/README.md

@@ -256,6 +256,7 @@ gitnexus clean                   # Delete index for current repo
 gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: minimax/minimax-m2.5)
+gitnexus wiki --provider grok    # Local Grok Build CLI (uses `grok login`, no API key)
 gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
                                   # Allow an exact LAN/self-hosted HTTP LLM host; env: GITNEXUS_ALLOW_INSECURE_CONNECTION
 gitnexus doctor                  # Show runtime platform capabilities and embedding configuration
@@ -281,6 +282,21 @@ gitnexus group status <name>     # Check staleness of repos in a group
 gitnexus group impact <name> --target <symbol> --repo <groupPath>  # Cross-repo blast radius
 ```
 
+GraphQL contract matching is opt-in in the group's `group.yaml`:
+
+```yaml
+detect:
+  graphql: true
+```
+
+The initial exact-only slice matches methods and properties on top-level NestJS `@Resolver`
+classes using imported `@Query`, `@Mutation`, and `@Subscription` decorators. Named
+`.graphql`/`.gql` operations are anchored by generated `<OperationName>Document` declarations;
+object, static `gql` template, and `TypedDocumentString` initializers must prove the operation name
+and root fields. Dynamic decorator names, anonymous operations, and ambiguous or missing graph
+anchors are deliberately omitted. Add common infrastructure fields such as `/health` to
+`matching.exclude_links_paths` to keep those GraphQL contracts visible without cross-linking them.
+
 > **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
 
 ## Remote Embeddings

package/dist/cli/i18n/en.d.ts

@@ -184,7 +184,7 @@ export declare const en: {
     readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
     readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
-    readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)";
+    readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)";
     readonly 'help.option.wiki.model': "LLM model or deployment name (default: MiniMax-M3)";
     readonly 'help.option.wiki.baseUrl': "LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1";
     readonly 'help.option.wiki.apiKey': "LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)";

package/dist/cli/i18n/en.js

@@ -186,7 +186,7 @@ export const en = {
     'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
     'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
-    'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)',
+    'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)',
     'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)',
     'help.option.wiki.baseUrl': 'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1',
     'help.option.wiki.apiKey': 'LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)',

package/dist/cli/i18n/resources.d.ts

@@ -185,7 +185,7 @@ export declare const cliResources: {
         readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
         readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
-        readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)";
+        readonly 'help.option.wiki.provider': "LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)";
         readonly 'help.option.wiki.model': "LLM model or deployment name (default: MiniMax-M3)";
         readonly 'help.option.wiki.baseUrl': "LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1";
         readonly 'help.option.wiki.apiKey': "LLM API key or Azure api-key (saved to ~/.gitnexus/config.json)";

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

@@ -184,7 +184,7 @@ export const zhCN = {
     'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
     'help.option.clean.lbugSidecars': '清理已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
-    'help.option.wiki.provider': 'LLM 提供商：minimax、openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：minimax）',
+    'help.option.wiki.provider': 'LLM 提供商：minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 或 grok（默认：minimax）',
     'help.option.wiki.model': 'LLM 模型或 deployment 名称（默认：MiniMax-M3）',
     '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

@@ -187,7 +187,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: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)')
+    .option('--provider <provider>', 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)')
     .option('--model <model>', 'LLM model or deployment name (default: MiniMax-M3)')
     .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/wiki.js

@@ -13,6 +13,7 @@ import { getStoragePaths, loadMeta, loadCLIConfig, saveCLIConfig, } from '../sto
 import { WikiGenerator } from '../core/wiki/generator.js';
 import { MINIMAX_MODEL_IDS, MINIMAX_OPENAI_BASE_URLS, parseLLMAllowedInsecureHttpHosts, resolveLLMConfig, } from '../core/wiki/llm-client.js';
 import { detectCursorCLI } from '../core/wiki/cursor-client.js';
+import { detectGrokCLI } from '../core/wiki/grok-client.js';
 import { detectLocalCLI } from '../core/wiki/local-cli-client.js';
 import { logger } from '../core/logger.js';
 function parsePositiveIntegerOption(value, flag, multiplier = 1) {
@@ -32,7 +33,8 @@ function isLocalProvider(provider) {
     return (provider === 'cursor' ||
         provider === 'claude' ||
         provider === 'codex' ||
-        provider === 'opencode');
+        provider === 'opencode' ||
+        provider === 'grok');
 }
 function localModelConfigKey(provider) {
     if (provider === 'cursor')
@@ -43,6 +45,8 @@ function localModelConfigKey(provider) {
         return 'codexModel';
     if (provider === 'opencode')
         return 'opencodeModel';
+    if (provider === 'grok')
+        return 'grokModel';
     throw new Error(`Unsupported local provider: ${provider}`);
 }
 /**
@@ -244,7 +248,7 @@ const wikiCommandImpl = async (inputPath, options) => {
             if (!llmConfig.apiKey && !isLocalProvider(llmConfig.provider)) {
                 console.log('  Error: No LLM API key found.');
                 console.log('  Set MINIMAX_API_KEY, GITNEXUS_API_KEY, or OPENAI_API_KEY,');
-                console.log('  or pass --api-key <key>, or use --provider cursor|claude|codex|opencode.\n');
+                console.log('  or pass --api-key <key>, or use --provider cursor|claude|codex|opencode|grok.\n');
                 process.exitCode = 1;
                 return;
             }
@@ -258,6 +262,7 @@ const wikiCommandImpl = async (inputPath, options) => {
             const hasClaude = detectLocalCLI('claude');
             const hasCodex = detectLocalCLI('codex');
             const hasOpenCode = detectLocalCLI('opencode');
+            const hasGrok = detectGrokCLI();
             const localChoices = [];
             // Provider selection
             console.log('  [1] OpenAI (api.openai.com)');
@@ -299,6 +304,14 @@ const wikiCommandImpl = async (inputPath, options) => {
                 });
                 console.log(`  [${choice}] OpenCode CLI (local, uses your OpenCode login/config)`);
             }
+            if (hasGrok) {
+                const choice = String(nextChoice++);
+                localChoices.push({
+                    choice,
+                    provider: 'grok',
+                });
+                console.log(`  [${choice}] Grok CLI (local, uses your Grok Build login)`);
+            }
             console.log('');
             const maxChoice = String(nextChoice - 1);
             const choice = await prompt(`  Select provider (1/${maxChoice}): `);

package/dist/core/group/config-parser.js

@@ -22,6 +22,7 @@ const VALID_ROLES = ['provider', 'consumer'];
 // repos that need cross-repo header tracking.
 const DEFAULT_DETECT = {
     http: true,
+    graphql: false,
     grpc: true,
     thrift: true,
     topics: true,
@@ -77,7 +78,17 @@ export function parseGroupConfig(yamlContent) {
             role: link.role,
         };
     });
-    const detect = { ...DEFAULT_DETECT, ...(raw.detect || {}) };
+    const rawDetect = raw.detect;
+    if (rawDetect !== undefined &&
+        (!rawDetect || typeof rawDetect !== 'object' || Array.isArray(rawDetect))) {
+        throw new Error('detect must be a mapping of boolean flags');
+    }
+    for (const [key, value] of Object.entries(rawDetect || {})) {
+        if (key in DEFAULT_DETECT && typeof value !== 'boolean') {
+            throw new Error(`detect.${key} must be true or false`);
+        }
+    }
+    const detect = { ...DEFAULT_DETECT, ...(rawDetect || {}) };
     const matching = { ...DEFAULT_MATCHING, ...(raw.matching || {}) };
     const packages = raw.packages || {};
     return {

package/dist/core/group/extractors/fs-utils.d.ts

@@ -8,3 +8,5 @@
  * sensitive) lives in exactly one place.
  */
 export declare function readSafe(repoPath: string, rel: string): string | null;
+/** Read a regular in-repo file without buffering more than `maxBytes`. */
+export declare function readSafeBounded(repoPath: string, rel: string, maxBytes: number): Promise<string | null>;

package/dist/core/group/extractors/fs-utils.js

@@ -22,3 +22,89 @@ export function readSafe(repoPath, rel) {
         return null;
     }
 }
+/** Read a regular in-repo file without buffering more than `maxBytes`. */
+export async function readSafeBounded(repoPath, rel, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        return null;
+    const abs = path.resolve(repoPath, rel);
+    const base = path.resolve(repoPath);
+    const relToBase = path.relative(base, abs);
+    if (relToBase.startsWith('..') || path.isAbsolute(relToBase))
+        return null;
+    try {
+        const canonicalBase = await fs.promises.realpath(base);
+        const canonicalFile = await fs.promises.realpath(abs);
+        const canonicalRelative = path.relative(canonicalBase, canonicalFile);
+        if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative))
+            return null;
+        const beforeOpen = await fs.promises.lstat(canonicalFile);
+        if (!beforeOpen.isFile() || beforeOpen.size > maxBytes)
+            return null;
+        if (maxBytes === 0)
+            return beforeOpen.size === 0 ? '' : null;
+        return await new Promise((resolve) => {
+            const stream = fs.createReadStream(canonicalFile, {
+                flags: 'r',
+                start: 0,
+                end: maxBytes,
+                autoClose: true,
+            });
+            const chunks = [];
+            let totalBytes = 0;
+            let validated = false;
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            stream.pause();
+            stream.once('open', (fd) => {
+                try {
+                    const opened = fs.fstatSync(fd);
+                    if (!opened.isFile() || opened.size > maxBytes) {
+                        finish(null);
+                        stream.destroy();
+                        return;
+                    }
+                    const currentCanonical = fs.realpathSync(canonicalFile);
+                    const currentRelative = path.relative(canonicalBase, currentCanonical);
+                    const current = fs.statSync(currentCanonical);
+                    if (currentRelative.startsWith('..') ||
+                        path.isAbsolute(currentRelative) ||
+                        opened.dev !== current.dev ||
+                        opened.ino !== current.ino) {
+                        finish(null);
+                        stream.destroy();
+                        return;
+                    }
+                    validated = true;
+                    stream.resume();
+                }
+                catch {
+                    finish(null);
+                    stream.destroy();
+                }
+            });
+            stream.on('data', (chunk) => {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalBytes += bytes.length;
+                if (totalBytes > maxBytes) {
+                    finish(null);
+                    stream.destroy();
+                    return;
+                }
+                chunks.push(bytes);
+            });
+            stream.once('end', () => {
+                finish(validated ? Buffer.concat(chunks, totalBytes).toString('utf8') : null);
+            });
+            stream.once('error', () => finish(null));
+            stream.once('close', () => finish(null));
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/group/extractors/graphql-extractor.d.ts

@@ -0,0 +1,17 @@
+import Parser from 'tree-sitter';
+import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
+import type { ExtractedContract, RepoHandle } from '../types.js';
+type GraphqlOperationKind = 'query' | 'mutation' | 'subscription';
+type GeneratedSymbolIndex = Map<string, Parser.SyntaxNode[]>;
+export declare const RESOLVE_METHOD_QUERY = "\nMATCH (n)\nWHERE labels(n) IN ['Method','Function','Property','CodeElement']\n  AND n.name = $name AND n.filePath = $filePath AND n.startLine = $startLine AND n.id <> ''\nRETURN n.id AS uid, n.name AS name, n.filePath AS filePath\nORDER BY n.id ASC\nLIMIT 2";
+export declare const RESOLVE_GENERATED_SYMBOL_QUERY = "\nMATCH (n)\nWHERE labels(n) IN ['Const','Variable','Function','Method','CodeElement']\n  AND n.name = $name AND n.filePath <> '' AND n.id <> ''\nRETURN n.id AS uid, n.name AS name, n.filePath AS filePath\nORDER BY n.id ASC\nLIMIT 2";
+export declare function hasGeneratedDocumentProof(initializer: Parser.SyntaxNode, operationKind: GraphqlOperationKind, operationName: string, requiredFields: readonly string[]): boolean;
+export declare function indexGeneratedDeclarators(root: Parser.SyntaxNode): GeneratedSymbolIndex;
+export declare class GraphqlExtractor implements ContractExtractor {
+    type: "graphql";
+    canExtract(_repo: RepoHandle): Promise<boolean>;
+    extract(dbExecutor: CypherExecutor | null, repoPath: string, _repo: RepoHandle): Promise<ExtractedContract[]>;
+    private extractProviders;
+    private extractConsumers;
+}
+export {};