gitnexus 1.6.6-rc.98 → 1.6.6

package/scripts/cross-platform-tests.ts

@@ -30,9 +30,10 @@ const PLATFORM_LOGIC = [
   'test/unit/setup-jsonc.test.ts',
   'test/unit/setup-codex.test.ts',
   'test/unit/setup-antigravity.test.ts',
+  'test/unit/resolve-invocation.test.ts',
   'test/unit/platform-capabilities.test.ts',
   'test/unit/worker-pool-windows-quarantine.test.ts',
-  'test/unit/lbug-pool-win-fts-probe.test.ts',
+  'test/unit/lbug-pool-fts-load.test.ts',
   'test/unit/repo-manager.test.ts',
   'test/unit/repo-manager-finalize-invariant.test.ts',
   'test/unit/hooks.test.ts',
@@ -84,6 +85,7 @@ const SPAWN_CLI = [
   'test/integration/setup-antigravity.test.ts',
   'test/integration/antigravity-hook-e2e.test.ts',
   'test/unit/local-cli-subprocess.test.ts',
+  'test/unit/runner-exec-tail.test.ts',
 ];
 
 // Worker threads tests — exercise real worker_threads which have
@@ -101,6 +103,7 @@ const NATIVE_ADDON_SMOKE = [
   'test/integration/pipeline.test.ts',
   'test/integration/pipeline-graph-golden.test.ts',
   'test/unit/parser-loader.test.ts',
+  'test/unit/parser-loader-abi.test.ts',
 ];
 
 // Filesystem behavior tests — exercise operations that vary across

package/skills/gitnexus-cli.md

@@ -5,14 +5,16 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/
 
 # GitNexus CLI Commands
 
-All commands work via `npx` — no global install required.
+Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required.
+
+> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
 
 ## Commands
 
 ### analyze — Build or refresh the index
 
 ```bash
-npx gitnexus analyze
+node .gitnexus/run.cjs analyze
 ```
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
@@ -28,7 +30,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 ### status — Check index freshness
 
 ```bash
-npx gitnexus status
+node .gitnexus/run.cjs status
 ```
 
 Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
@@ -36,7 +38,7 @@ Shows whether the current repo has a GitNexus index, when it was last updated, a
 ### clean — Delete the index
 
 ```bash
-npx gitnexus clean
+node .gitnexus/run.cjs clean
 ```
 
 Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
@@ -49,7 +51,7 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
 ### wiki — Generate documentation from the graph
 
 ```bash
-npx gitnexus wiki
+node .gitnexus/run.cjs wiki
 ```
 
 Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
@@ -66,7 +68,7 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 ### list — Show all indexed repos
 
 ```bash
-npx gitnexus list
+node .gitnexus/run.cjs list
 ```
 
 Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.

package/skills/gitnexus-debugging.md

@@ -16,23 +16,23 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow
 
 ```
-1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
-2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+1. query({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. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklist
 
 ```
 - [ ] Understand the symptom (error message, unexpected behavior)
-- [ ] gitnexus_query for error text or related code
+- [ ] query for error text or related code
 - [ ] Identify the suspect function from returned processes
-- [ ] gitnexus_context to see callers and callees
+- [ ] context to see callers and callees
 - [ ] Trace execution flow via process resource if applicable
-- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] cypher for custom call chain traces if needed
 - [ ] Read source files to confirm root cause
 ```
 
@@ -40,7 +40,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 
 | Symptom              | GitNexus Approach                                          |
 | -------------------- | ---------------------------------------------------------- |
-| Error message        | `gitnexus_query` for error text → `context` on throw sites |
+| Error message        | `query` for error text → `context` on throw sites |
 | Wrong return value   | `context` on the function → trace callees for data flow    |
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
@@ -48,24 +48,24 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 
 ## Tools
 
-**gitnexus_query** — find code related to error:
+**query** — find code related to error:
 
 ```
-gitnexus_query({query: "payment validation error"})
+query({query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
 
-**gitnexus_context** — full context for a suspect:
+**context** — full context for a suspect:
 
 ```
-gitnexus_context({name: "validatePayment"})
+context({name: "validatePayment"})
 → Incoming calls: processCheckout, webhookHandler
 → Outgoing calls: verifyCard, fetchRates (external API!)
 → Processes: CheckoutFlow (step 3/7)
 ```
 
-**gitnexus_cypher** — custom call chain traces:
+**cypher** — custom call chain traces:
 
 ```cypher
 MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
@@ -75,11 +75,11 @@ RETURN [n IN nodes(path) | n.name] AS chain
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. gitnexus_query({query: "payment error handling"})
+1. query({query: "payment error handling"})
    → Processes: CheckoutFlow, ErrorHandling
    → Symbols: validatePayment, handlePaymentError
 
-2. gitnexus_context({name: "validatePayment"})
+2. context({name: "validatePayment"})
    → Outgoing calls: verifyCard, fetchRates (external API!)
 
 3. READ gitnexus://repo/my-app/process/CheckoutFlow

package/skills/gitnexus-exploring.md

@@ -18,20 +18,20 @@ 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. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
-4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+3. query({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
 ```
 
-> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklist
 
 ```
 - [ ] READ gitnexus://repo/{name}/context
-- [ ] gitnexus_query for the concept you want to understand
+- [ ] query for the concept you want to understand
 - [ ] Review returned processes (execution flows)
-- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] context on key symbols for callers/callees
 - [ ] READ process resource for full execution traces
 - [ ] Read source files for implementation details
 ```
@@ -47,18 +47,18 @@ description: "Use when the user asks how code works, wants to understand archite
 
 ## Tools
 
-**gitnexus_query** — find execution flows related to a concept:
+**query** — find execution flows related to a concept:
 
 ```
-gitnexus_query({query: "payment processing"})
+query({query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
 
-**gitnexus_context** — 360-degree view of a symbol:
+**context** — 360-degree view of a symbol:
 
 ```
-gitnexus_context({name: "validateUser"})
+context({name: "validateUser"})
 → Incoming calls: loginHandler, apiMiddleware
 → Outgoing calls: checkToken, getUserById
 → Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
@@ -68,10 +68,10 @@ gitnexus_context({name: "validateUser"})
 
 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. gitnexus_query({query: "payment processing"})
+2. query({query: "payment processing"})
    → CheckoutFlow: processPayment → validateCard → chargeStripe
    → RefundFlow: initiateRefund → calculateRefund → processRefund
-3. gitnexus_context({name: "processPayment"})
+3. context({name: "processPayment"})
    → Incoming: checkoutHandler, webhookHandler
    → Outgoing: validateCard, chargeStripe, saveTransaction
 4. Read src/payments/processor.ts for implementation details

package/skills/gitnexus-guide.md

@@ -15,7 +15,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+> If step 1 warns the index is stale, run `node .gitnexus/run.cjs analyze` in the terminal first.
 
 ## Skills
 

package/skills/gitnexus-impact-analysis.md

@@ -17,22 +17,22 @@ description: "Use when the user wants to know what will break if they change som
 ## Workflow
 
 ```
-1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+1. impact({target: "X", direction: "upstream"})  → What depends on this
 2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
-3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+3. detect_changes()                               → Map current git changes to affected flows
 4. Assess risk and report to user
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklist
 
 ```
-- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] impact({target, direction: "upstream"}) to find dependents
 - [ ] Review d=1 items first (these WILL BREAK)
 - [ ] Check high-confidence (>0.8) dependencies
 - [ ] READ processes to check affected execution flows
-- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] detect_changes() for pre-commit check
 - [ ] Assess risk level and report to user
 ```
 
@@ -55,10 +55,10 @@ description: "Use when the user wants to know what will break if they change som
 
 ## Tools
 
-**gitnexus_impact** — the primary tool for symbol blast radius:
+**impact** — the primary tool for symbol blast radius:
 
 ```
-gitnexus_impact({
+impact({
   target: "validateUser",
   direction: "upstream",
   minConfidence: 0.8,
@@ -73,10 +73,10 @@ gitnexus_impact({
   - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
 ```
 
-**gitnexus_detect_changes** — git-diff based impact analysis:
+**detect_changes** — git-diff based impact analysis:
 
 ```
-gitnexus_detect_changes({scope: "staged"})
+detect_changes({scope: "staged"})
 
 → Changed: 5 symbols in 3 files
 → Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
@@ -86,7 +86,7 @@ gitnexus_detect_changes({scope: "staged"})
 ## Example: "What breaks if I change validateUser?"
 
 ```
-1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+1. impact({target: "validateUser", direction: "upstream"})
    → d=1: loginHandler, apiMiddleware (WILL BREAK)
    → d=2: authRouter, sessionManager (LIKELY AFFECTED)
 

package/skills/gitnexus-pr-review.md

@@ -18,24 +18,24 @@ description: "Use when the user wants to review a pull request, understand what
 
 ```
 1. gh pr diff <number>                                    → Get the raw diff
-2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+2. detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
 3. For each changed symbol:
-   gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
-4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
+   impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
+4. context({name: "<key symbol>"})               → Understand callers/callees
 5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
 6. Summarize findings with risk assessment
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal before reviewing.
 
 ## Checklist
 
 ```
 - [ ] Fetch PR diff (gh pr diff or git diff base...head)
-- [ ] gitnexus_detect_changes to map changes to affected execution flows
-- [ ] gitnexus_impact on each non-trivial changed symbol
+- [ ] detect_changes to map changes to affected execution flows
+- [ ] impact on each non-trivial changed symbol
 - [ ] Review d=1 items (WILL BREAK) — are callers updated?
-- [ ] gitnexus_context on key changed symbols to understand full picture
+- [ ] context on key changed symbols to understand full picture
 - [ ] Check if affected processes have test coverage
 - [ ] Assess overall risk level
 - [ ] Write review summary with findings
@@ -63,20 +63,20 @@ description: "Use when the user wants to review a pull request, understand what
 
 ## Tools
 
-**gitnexus_detect_changes** — map PR diff to affected execution flows:
+**detect_changes** — map PR diff to affected execution flows:
 
 ```
-gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+detect_changes({scope: "compare", base_ref: "main"})
 
 → Changed: 8 symbols in 4 files
 → Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Risk: MEDIUM
 ```
 
-**gitnexus_impact** — blast radius per changed symbol:
+**impact** — blast radius per changed symbol:
 
 ```
-gitnexus_impact({target: "validatePayment", direction: "upstream"})
+impact({target: "validatePayment", direction: "upstream"})
 
 → d=1 (WILL BREAK):
   - processCheckout (src/checkout.ts:42) [CALLS, 100%]
@@ -86,20 +86,20 @@ gitnexus_impact({target: "validatePayment", direction: "upstream"})
   - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
 ```
 
-**gitnexus_impact with tests** — check test coverage:
+**impact with tests** — check test coverage:
 
 ```
-gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
+impact({target: "validatePayment", direction: "upstream", includeTests: true})
 
 → Tests that cover this symbol:
   - validatePayment.test.ts [direct]
   - checkout.integration.test.ts [via processCheckout]
 ```
 
-**gitnexus_context** — understand a changed symbol's role:
+**context** — understand a changed symbol's role:
 
 ```
-gitnexus_context({name: "validatePayment"})
+context({name: "validatePayment"})
 
 → Incoming calls: processCheckout, webhookHandler
 → Outgoing calls: verifyCard, fetchRates
@@ -112,20 +112,20 @@ gitnexus_context({name: "validatePayment"})
 1. gh pr diff 42 > /tmp/pr42.diff
    → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
 
-2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+2. detect_changes({scope: "compare", base_ref: "main"})
    → Changed symbols: validatePayment, PaymentInput, formatAmount
    → Affected processes: CheckoutFlow, RefundFlow
    → Risk: MEDIUM
 
-3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
+3. impact({target: "validatePayment", direction: "upstream"})
    → d=1: processCheckout, webhookHandler (WILL BREAK)
    → webhookHandler is NOT in the PR diff — potential breakage!
 
-4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
+4. impact({target: "PaymentInput", direction: "upstream"})
    → d=1: validatePayment (in PR), createPayment (NOT in PR)
    → createPayment uses the old PaymentInput shape — breaking change!
 
-5. gitnexus_context({name: "formatAmount"})
+5. context({name: "formatAmount"})
    → Called by 12 functions — but change is backwards-compatible (added optional param)
 
 6. Review summary:

package/skills/gitnexus-refactoring.md

@@ -16,78 +16,78 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 ## Workflow
 
 ```
-1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
-2. gitnexus_query({query: "X"})                            → Find execution flows involving X
-3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+1. impact({target: "X", direction: "upstream"})  → Map all dependents
+2. query({query: "X"})                            → Find execution flows involving X
+3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```
 
-> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
 
 ## Checklists
 
 ### Rename Symbol
 
 ```
-- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
 - [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
-- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
-- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
+- [ ] detect_changes() — verify only expected files changed
 - [ ] Run tests for affected processes
 ```
 
 ### Extract Module
 
 ```
-- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
-- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] context({name: target}) — see all incoming/outgoing refs
+- [ ] impact({target, direction: "upstream"}) — find all external callers
 - [ ] Define new module interface
 - [ ] Extract code, update imports
-- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] detect_changes() — verify affected scope
 - [ ] Run tests for affected processes
 ```
 
 ### Split Function/Service
 
 ```
-- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] context({name: target}) — understand all callees
 - [ ] Group callees by responsibility
-- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] impact({target, direction: "upstream"}) — map callers to update
 - [ ] Create new functions/services
 - [ ] Update callers
-- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] detect_changes() — verify affected scope
 - [ ] Run tests for affected processes
 ```
 
 ## Tools
 
-**gitnexus_rename** — automated multi-file rename:
+**rename** — automated multi-file rename:
 
 ```
-gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
 → 12 edits across 8 files
 → 10 graph edits (high confidence), 2 ast_search edits (review)
 → Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
 ```
 
-**gitnexus_impact** — map all dependents first:
+**impact** — map all dependents first:
 
 ```
-gitnexus_impact({target: "validateUser", direction: "upstream"})
+impact({target: "validateUser", direction: "upstream"})
 → d=1: loginHandler, apiMiddleware, testUtils
 → Affected Processes: LoginFlow, TokenRefresh
 ```
 
-**gitnexus_detect_changes** — verify your changes after refactoring:
+**detect_changes** — verify your changes after refactoring:
 
 ```
-gitnexus_detect_changes({scope: "all"})
+detect_changes({scope: "all"})
 → Changed: 8 files, 12 symbols
 → Affected processes: LoginFlow, TokenRefresh
 → Risk: MEDIUM
 ```
 
-**gitnexus_cypher** — custom reference queries:
+**cypher** — custom reference queries:
 
 ```cypher
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
@@ -98,24 +98,24 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
 
 | Risk Factor         | Mitigation                                |
 | ------------------- | ----------------------------------------- |
-| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Many callers (>5)   | Use rename for automated updates |
 | Cross-area refs     | Use detect_changes after to verify scope  |
-| String/dynamic refs | gitnexus_query to find them               |
+| String/dynamic refs | query to find them               |
 | External/public API | Version and deprecate properly            |
 
 ## Example: Rename `validateUser` to `authenticateUser`
 
 ```
-1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
    → 12 edits: 10 graph (safe), 2 ast_search (review)
    → Files: validator.ts, login.ts, middleware.ts, config.json...
 
 2. Review ast_search edits (config.json: dynamic reference!)
 
-3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
    → Applied 12 edits across 8 files
 
-4. gitnexus_detect_changes({scope: "all"})
+4. detect_changes({scope: "all"})
    → Affected: LoginFlow, TokenRefresh
    → Risk: MEDIUM — run tests for these flows
 ```