gitnexus 1.6.8-rc.26 → 1.6.8-rc.27

package/README.md

@@ -134,7 +134,7 @@ Your AI agent gets these tools automatically:
 | `rename`         | Multi-file coordinated rename with graph + text search           | Optional     |
 | `cypher`         | Raw Cypher graph queries                                         | Optional     |
 
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`.
 
 ## MCP Resources
 

package/dist/cli/ai-context.js

@@ -134,7 +134,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
 - **MUST run \`detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use \`query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When exploring unfamiliar code, use \`query({search_query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`context({name: "symbolName"})\`.
 - For security review, \`explain({target: "fileOrSymbol"})\` lists taint findings (source→sink flows; needs \`analyze --pdg\`).
 

package/dist/cli/skill-gen.js

@@ -483,7 +483,7 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
     lines.push('## How to Explore');
     lines.push('');
     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(`2. \`query({search_query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
     lines.push('3. Read key files listed above for implementation details');
     lines.push('4. `explain({target: "<file or symbol>"})` — persisted taint findings (source→sink data flows), when indexed with `--pdg`');
     lines.push('');

package/dist/cli/tool.js

@@ -62,7 +62,8 @@ export async function queryCommand(queryText, options) {
     }
     const backend = await getBackend();
     const result = await backend.callTool('query', {
-        query: queryText,
+        // #2175: canonical param is search_query; the backend still accepts legacy "query".
+        search_query: queryText,
         task_context: options?.context,
         goal: options?.goal,
         limit: options?.limit ? parseInt(options.limit) : undefined,
@@ -154,7 +155,8 @@ export async function cypherCommand(query, options) {
     }
     const backend = await getBackend();
     const result = await backend.callTool('cypher', {
-        query,
+        // #2175: canonical param is statement; the backend still accepts legacy "query".
+        statement: query,
         repo: options?.repo,
         branch: options?.branch,
     });

package/dist/mcp/local/local-backend.js

@@ -43,6 +43,23 @@ function looksLikeFilePath(target) {
     const lower = target.toLowerCase();
     return SOURCE_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext));
 }
+/**
+ * Resolve a string tool param from its canonical name or legacy alias (#2175).
+ * Returns the first NON-BLANK string of [canonical, legacy] — the canonical (new)
+ * name is preferred when it carries a real value, otherwise the legacy value is used.
+ * A blank/whitespace new value therefore does NOT clobber a valid legacy value (e.g. a
+ * gradually-migrating client that always emits the new key, blank when unset). A
+ * non-string value (the MCP envelope is not schema-validated, so clients can send any
+ * JSON type) and an all-blank input resolve to `undefined`, so the caller returns a
+ * friendly required-param error instead of throwing `TypeError` on `.trim()`.
+ */
+function resolveAliasString(canonical, legacy) {
+    for (const value of [canonical, legacy]) {
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -1030,6 +1047,15 @@ export class LocalBackend {
             return this.handleGroupTool(method, params || {});
         }
         const p = params && typeof params === 'object' ? params : {};
+        // #2175: Claude Code drops a tool-call argument named exactly "query", so the
+        // query/cypher tools advertise "search_query"/"statement" while still accepting the
+        // legacy "query" key for backward compat. The alias is resolved with `?? ` (new name
+        // wins) at every consumer site rather than by mutating params here, so precedence is
+        // uniform and there is no hidden mutation: query()/cypher() read it directly, the
+        // legacy "search" alias routes through query(), and the cross-repo group-forward
+        // resolves it self-contained in callToolAtGroupRepo. This is permanent compatibility
+        // — third-party MCP clients may legitimately send "query", so the alias is not slated
+        // for removal even if Claude Code's argument handling later changes.
         if ((method === 'impact' || method === 'query' || method === 'context') &&
             typeof p.repo === 'string' &&
             p.repo.startsWith('@')) {
@@ -1118,14 +1144,18 @@ export class LocalBackend {
      * 4. Return: { processes, process_symbols, definitions }
      */
     async query(repo, params) {
-        if (!params.query?.trim()) {
-            return { error: 'query parameter is required and cannot be empty.' };
+        // #2175: each consumer resolves the search_query/query alias itself (there is no
+        // chokepoint mutation in callTool). This also serves the GroupService port, which
+        // reaches query() carrying only the legacy `query` key.
+        const rawQuery = resolveAliasString(params.search_query, params.query);
+        if (!rawQuery?.trim()) {
+            return { error: 'search_query (or legacy query) parameter is required and cannot be empty.' };
         }
         await this.ensureInitialized(repo);
         const processLimit = params.limit || 5;
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
-        const searchQuery = params.query.trim();
+        const searchQuery = rawQuery.trim();
         // Per-phase timing instrumentation (#553). Records wall time for each
         // observable sub-step of the search pipeline so production latency can
         // be aggregated offline for Pareto analysis and bottleneck detection.
@@ -1602,7 +1632,10 @@ export class LocalBackend {
         const repo = await this.resolveRepo(repoName);
         return this.cypher(repo, { query, params });
     }
-    async cypher(repo, request) {
+    async cypher(repo, 
+    // #2175: "statement" is the advertised param; "query" is the legacy alias,
+    // still accepted (and the field the internal executeCypher() passes). New wins.
+    request) {
         await this.ensureInitialized(repo);
         if (!isLbugReady(repo.lbugPath)) {
             return { error: 'LadybugDB not ready. Index may be corrupted.' };
@@ -1612,8 +1645,14 @@ export class LocalBackend {
                 error: '"params" must be a plain object with scalar values (string/number/boolean/null).',
             };
         }
+        const cypherText = resolveAliasString(request.statement, request.query) ?? '';
+        if (!cypherText.trim()) {
+            // Mirror query()'s friendly required-param error instead of letting an empty
+            // string fall through to a raw LadybugDB prepare error (#2175 review).
+            return { error: 'statement (or legacy query) parameter is required and cannot be empty.' };
+        }
         try {
-            const result = await executeParameterized(repo.lbugPath, request.query, request.params ?? {});
+            const result = await executeParameterized(repo.lbugPath, cypherText, request.params ?? {});
             return result;
         }
         catch (err) {
@@ -3984,7 +4023,10 @@ export class LocalBackend {
         if (method === 'query') {
             const queryArgs = {
                 name: groupName,
-                query: params.query,
+                // #2175: resolve the search_query alias here (new name wins, same rule as the
+                // local query() handler) so the group path is self-contained and does not depend
+                // on params being normalized upstream. groupQuery() reads `query`.
+                query: resolveAliasString(params.search_query, params.query),
             };
             if (typeof params.task_context === 'string')
                 queryArgs.task_context = params.task_context;

package/dist/mcp/resources.js

@@ -234,7 +234,7 @@ async function getReposResource(backend) {
     if (repos.length > 1) {
         lines.push('');
         lines.push('# Multiple repos indexed. Use repo parameter in tool calls:');
-        lines.push(`# query({query: "auth", repo: "${repos[0].name}"})`);
+        lines.push(`# query({search_query: "auth", repo: "${repos[0].name}"})`);
     }
     return lines.join('\n');
 }

package/dist/mcp/tools.js

@@ -98,7 +98,14 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Natural language or keyword search query' },
+                // #2175: the legacy `query` key is still accepted by the handler
+                // (resolveAliasString in local-backend.ts), but is deliberately NOT named in the
+                // advertised property or its description — surfacing "query" in the schema an LLM
+                // reads would nudge it to send `query`, the exact argument Claude Code drops.
+                search_query: {
+                    type: 'string',
+                    description: 'Natural language or keyword search query.',
+                },
                 task_context: {
                     type: 'string',
                     description: 'What you are working on (e.g., "adding OAuth support"). Helps ranking.',
@@ -136,7 +143,7 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
                     description: 'Optional monorepo service root (relative path, "/" separators). In group mode (@repo), prefix-matches symbol file paths; ignored for a normal repo name. Empty string is rejected server-side.',
                 },
             },
-            required: ['query'],
+            required: ['search_query'],
         },
     },
     {
@@ -189,7 +196,14 @@ TIPS:
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Cypher query to execute' },
+                // #2175: the legacy `query` key is still accepted by the handler
+                // (resolveAliasString in local-backend.ts), but is deliberately NOT named in the
+                // advertised property or its description — surfacing "query" in the schema an LLM
+                // reads would nudge it to send `query`, the exact argument Claude Code drops.
+                statement: {
+                    type: 'string',
+                    description: 'Cypher statement to execute.',
+                },
                 params: {
                     type: 'object',
                     description: 'Optional query parameters for placeholders (e.g. $name) to execute via prepared statement binding.',
@@ -199,7 +213,7 @@ TIPS:
                     description: 'Repository name or path. Omit if only one repo is indexed.',
                 },
             },
-            required: ['query'],
+            required: ['statement'],
         },
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.26",
+  "version": "1.6.8-rc.27",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-debugging.md

@@ -16,10 +16,10 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow
 
 ```
-1. query({query: "<error or symptom>"})            → Find related execution flows
+1. query({search_query: "<error or symptom>"})            → Find related execution flows
 2. context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
 ```
 
 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@@ -51,7 +51,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 **query** — find code related to error:
 
 ```
-query({query: "payment validation error"})
+query({search_query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -75,7 +75,7 @@ RETURN [n IN nodes(path) | n.name] AS chain
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. query({query: "payment error handling"})
+1. query({search_query: "payment error handling"})
    → Processes: CheckoutFlow, ErrorHandling
    → Symbols: validatePayment, handlePaymentError
 

package/skills/gitnexus-exploring.md

@@ -18,7 +18,7 @@ description: "Use when the user asks how code works, wants to understand archite
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({query: "<what you want to understand>"})  → Find related execution flows
+3. query({search_query: "<what you want to understand>"})  → Find related execution flows
 4. context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
@@ -50,7 +50,7 @@ description: "Use when the user asks how code works, wants to understand archite
 **query** — find execution flows related to a concept:
 
 ```
-query({query: "payment processing"})
+query({search_query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -68,7 +68,7 @@ context({name: "validateUser"})
 
 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({query: "payment processing"})
+2. query({search_query: "payment processing"})
    → CheckoutFlow: processPayment → validateCard → chargeStripe
    → RefundFlow: initiateRefund → calculateRefund → processRefund
 3. context({name: "processPayment"})

package/skills/gitnexus-refactoring.md

@@ -17,7 +17,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 
 ```
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({query: "X"})                            → Find execution flows involving X
+2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```