pi-gitnexus-fork 0.7.0

package/docs/design/remote-mcp-backend.md

@@ -0,0 +1,153 @@
+# Design: Remote MCP Backend for pi-gitnexus
+
+## Problem
+
+The upstream `tintinweb/pi-gitnexus` extension uses a local `gitnexus` CLI binary for:
+
+1. **Auto-augment hooks** — spawn `gitnexus augment <pattern>` via stdio
+2. **Registered tools** — spawn `gitnexus mcp` via stdio JSON-RPC
+
+On this machine:
+
+- The npm `gitnexus@1.6.3` binary is a stub (`exit 0`)
+- Even with a working binary, LadybugDB segfaults (Node 22 Docker vs Node 24 host ABI mismatch)
+- A centralized GitNexus server runs on bhd-main2 (`http://100.114.135.99:4747`) and writes `.gitnexus/` indexes locally via shared mount
+- The server exposes MCP tools via StreamableHTTP at `/api/mcp`
+
+## Approach: Dual Transport with Auto-Detection
+
+Add a `RemoteMcpClient` alongside the existing `StdioMcpClient`. A factory selects based on config:
+
+```
+mode=auto    → probe local binary → works? use stdio : use remote
+mode=local   → stdio only (existing behavior)
+mode=remote  → StreamableHTTP to server
+```
+
+## Architecture
+
+### Config (~/.pi/pi-gitnexus.json)
+
+```jsonc
+{
+  "mode": "auto", // "auto" | "local" | "remote"
+  "serverUrl": "http://100.114.135.99:4747/api/mcp",
+  // existing fields...
+  "cmd": "", // local command override
+  "autoAugment": true,
+  "augmentTimeout": 8, // seconds
+}
+```
+
+### MCP Client Interface
+
+```typescript
+interface McpClient {
+  callTool(
+    name: string,
+    args: Record<string, unknown>,
+    cwd: string,
+  ): Promise<string>;
+  stop(): void;
+}
+```
+
+### Components
+
+| Component          | File                             | Purpose                                             |
+| ------------------ | -------------------------------- | --------------------------------------------------- |
+| `McpClientFactory` | `src/mcp-client.ts` (modify)     | Extract interface, add factory, keep StdioMcpClient |
+| `RemoteMcpClient`  | `src/remote-mcp-client.ts` (new) | StreamableHTTP transport to server                  |
+| `RepoResolver`     | `src/repo-resolver.ts` (new)     | Map host cwd → server repo name/path                |
+| `AutoMcpClient`    | `src/mcp-client.ts` (new)        | Probe → select → cache transport                    |
+| Augment hook       | `src/index.ts` (modify)          | Use remote client for augment via `query` tool      |
+
+### Repo Resolution Strategy
+
+The server knows repos by container paths (`/workspace/bhd/pi-plugins`) or registered names.
+The host cwd is `/home/bhd/Documents/Projects/bhd/pi-plugins`.
+
+Resolution:
+
+1. Fetch server registry from `GET /api/repos` (or `list_repos` MCP tool)
+2. Cache locally (in-memory, refreshed per session)
+3. Match host cwd to server repo by:
+   a. Git remote URL (most reliable)
+   b. Basename of cwd matches basename of server path
+   c. Fallback: pass `findGitNexusRoot(cwd)` as repo path
+
+### Augment via Query
+
+The server doesn't expose `augment` as an MCP tool. In remote mode:
+
+- Auto-augment hook calls `callTool('query', { query: pattern, repo, limit: 3 })`
+- This returns relevant graph context — serves the same purpose as augment
+- The agent also has native `gitnexus_query` tool, so this is consistent
+
+### Graceful Degradation
+
+- Server unreachable → augment hook returns empty (same as current broken state, but explicit)
+- No retry storms — single attempt per hook fire
+- Log warning via `ctx.ui.notify()` on first failure per session
+
+## Test Plan
+
+### P0 — RemoteMcpClient (src/remote-mcp-client.ts)
+
+- StreamableHTTP POST request/response cycle
+- JSON-RPC 2.0 message format
+- MCP initialize handshake
+- Error handling: network failure, timeout, MCP error response
+- Response parsing: text content extraction, truncation
+- Connection reuse across calls
+
+### P0 — RepoResolver (src/repo-resolver.ts)
+
+- Parse registry response (array of {name, path, remoteUrl})
+- Match host cwd by git remote URL
+- Match host cwd by basename
+- Fallback to findGitNexusRoot
+- Cache behavior (store, invalidate, refresh)
+
+### P0 — McpClientFactory (src/mcp-client.ts)
+
+- Mode selection: local, remote, auto
+- Auto probe: binary works → stdio, else → remote
+- Config loading with defaults
+
+### P1 — Augment hook integration (src/index.ts)
+
+- Remote augment via query tool
+- Fallback on error
+- Pattern extraction unchanged
+
+### P1 — Config (src/gitnexus.ts)
+
+- serverUrl loading
+- mode loading with validation
+- Environment variable overrides
+
+### Coverage Target: 60%+
+
+## Files to Create/Modify
+
+```
+src/
+  remote-mcp-client.ts  ← NEW
+  repo-resolver.ts      ← NEW
+  mcp-client.ts         ← MODIFY (extract interface, add factory + AutoMcpClient)
+  gitnexus.ts           ← MODIFY (add mode/serverUrl to GitNexusConfig)
+  index.ts              ← MODIFY (auto-augment uses remote when available)
+tests/
+  remote-mcp-client.test.ts  ← NEW
+  repo-resolver.test.ts      ← NEW
+  augment-remote.test.ts     ← NEW
+  mcp-client.test.ts         ← MODIFY (add factory tests)
+```
+
+## Constraints
+
+- NO changes to the GitNexus server — it's a read-only dependency
+- NO new npm dependencies for HTTP (use native `fetch`)
+- Existing tests MUST continue to pass (backward compat)
+- Config is additive — existing fields keep their meaning

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pi-gitnexus-fork",
+  "version": "0.7.0",
+  "description": "GitNexus knowledge graph integration for pi \u2014 enriches searches with call chains, execution flows, and blast radius",
+  "author": "tintinweb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buihongduc132/pi-gitnexus.git"
+  },
+  "homepage": "https://github.com/buihongduc132/pi-gitnexus#readme",
+  "bugs": {
+    "url": "https://github.com/buihongduc132/pi-gitnexus/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "gitnexus",
+    "code-intelligence",
+    "knowledge-graph"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run test",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --fix src/"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": ">=0.70",
+    "@mariozechner/pi-coding-agent": ">=0.70",
+    "typebox": ">=1.0"
+  },
+  "dependencies": {
+    "cross-spawn": "7.0.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@mariozechner/pi-ai": "^0.72.1",
+    "@mariozechner/pi-coding-agent": "^0.72.1",
+    "@types/cross-spawn": "6.0.6",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "typebox": "^1.1.37",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://github.com/tintinweb/pi-gitnexus/raw/master/media/screenshot.png"
+  }
+}

package/sgconfig.yml

@@ -0,0 +1,4 @@
+# Auto-generated by coding-guard deploy.sh
+# Run: sg scan . --json
+ruleDirs:
+  - .sg-rules

package/skills/gitnexus-debugging/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})    → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})             → See callers/callees/processes
+3. gitnexus_cypher({query: "MATCH path..."})         → Custom traces if needed
+4. Read source files to confirm root cause
+```
+
+> If index is stale → run `/gitnexus analyze` to rebuild.
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `gitnexus_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)     |
+| Recent regression    | `gitnexus_detect_changes` to see what your changes affect  |
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```
+gitnexus_cypher({query: "MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: 'validatePayment'}) RETURN [n IN nodes(path) | n.name] AS chain"})
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. Root cause: fetchRates calls external API without proper timeout
+```

package/skills/gitnexus-exploring/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. gitnexus_list_repos()                                   → Discover indexed repos
+2. gitnexus_query({query: "<what you want to understand>"}) → Find related execution flows
+3. gitnexus_context({name: "<symbol>"})                     → Deep dive on specific symbol
+4. Read source files for implementation details
+```
+
+> If index is stale → run `/gitnexus analyze` to rebuild.
+
+## Checklist
+
+```
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] Read source files for implementation details
+```
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+**gitnexus_cypher** — custom graph queries for deeper exploration:
+
+```
+gitnexus_cypher({query: "MATCH (f:Function)-[:CodeRelation {type: 'CALLS'}]->(g) WHERE f.name = 'main' RETURN g.name, g.filePath"})
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+
+2. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+
+3. Read src/payments/processor.ts for implementation details
+```

package/skills/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. gitnexus_detect_changes()                               → Map current git changes to affected flows
+3. Assess risk and report to user
+```
+
+> If index is stale → run `/gitnexus analyze` to rebuild.
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Tools
+
+**gitnexus_impact** — primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. Risk: 2 direct callers, 2 processes = MEDIUM
+   → Recommend: update loginHandler and apiMiddleware first, then run tests
+```

package/skills/gitnexus-pr-review/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: gitnexus-pr-review
+description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
+---
+
+# PR Review with GitNexus
+
+## When to Use
+
+- "Review this PR"
+- "What does PR #42 change?"
+- "Is this safe to merge?"
+- "What's the blast radius of this PR?"
+- Reviewing someone else's code changes before merge
+
+## Workflow
+
+```
+1. gh pr diff <number>                                                → Get the raw diff
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})     → Map diff to affected flows
+3. gitnexus_impact({target: "<symbol>", direction: "upstream"})       → Blast radius per change
+4. gitnexus_context({name: "<key symbol>"})                           → Understand callers/callees
+5. Summarize findings with risk assessment
+```
+
+> If index is stale → run `/gitnexus analyze` 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
+- [ ] Review d=1 items (WILL BREAK) — are callers updated?
+- [ ] gitnexus_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
+```
+
+## Review Dimensions
+
+| Dimension | How GitNexus Helps |
+| --- | --- |
+| **Correctness** | `context` shows callers — are they all compatible with the change? |
+| **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
+| **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
+| **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
+| **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
+
+## Risk Assessment
+
+| Signal | Risk |
+| --- | --- |
+| Changes touch <3 symbols, 0-1 processes | LOW |
+| Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
+| Changes touch >10 symbols or many processes | HIGH |
+| Changes touch auth, payments, or data integrity code | CRITICAL |
+| d=1 callers exist outside the PR diff | Potential breakage — flag it |
+
+## Review Output Format
+
+```markdown
+## PR Review: <title>
+
+**Risk: LOW / MEDIUM / HIGH / CRITICAL**
+
+### Changes Summary
+- <N> symbols changed across <M> files
+- <P> execution flows affected
+
+### Findings
+1. **[severity]** Description of finding
+   - Evidence from GitNexus tools
+   - Affected callers/flows
+
+### Missing Coverage
+- Callers not updated in PR: ...
+- Untested flows: ...
+
+### Recommendation
+APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+```
+
+## Example: "Review PR #42"
+
+```
+1. gh pr diff 42
+   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
+
+2. gitnexus_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"})
+   → d=1: processCheckout, webhookHandler (WILL BREAK)
+   → webhookHandler is NOT in the PR diff — potential breakage!
+
+4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
+   → d=1: validatePayment (in PR), createPayment (NOT in PR)
+   → createPayment uses the old PaymentInput shape — breaking change!
+
+5. Review summary:
+   - MEDIUM risk — 3 changed symbols affect 2 execution flows
+   - BUG: webhookHandler not updated for new validatePayment signature
+   - BUG: createPayment depends on changed PaymentInput type
+   - OK: formatAmount change is backwards-compatible
+```

package/skills/gitnexus-refactoring/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## 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
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If index is stale → run `/gitnexus analyze` to rebuild.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_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
+- [ ] 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
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_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})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```