gitnexus 1.3.2 → 1.3.4

package/dist/server/mcp-http.js

@@ -0,0 +1,100 @@
+/**
+ * MCP over HTTP
+ *
+ * Mounts the GitNexus MCP server on Express using StreamableHTTP transport.
+ * Each connecting client gets its own stateful session; the LocalBackend
+ * is shared across all sessions (thread-safe — lazy KuzuDB per repo).
+ *
+ * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
+ * (guards against network drops that never trigger onclose).
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMCPServer } from '../mcp/server.js';
+import { randomUUID } from 'crypto';
+/** Idle sessions are evicted after 30 minutes */
+const SESSION_TTL_MS = 30 * 60 * 1000;
+/** Cleanup sweep runs every 5 minutes */
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+export function mountMCPEndpoints(app, backend) {
+    const sessions = new Map();
+    // Periodic cleanup of idle sessions (guards against network drops)
+    const cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, session] of sessions) {
+            if (now - session.lastActivity > SESSION_TTL_MS) {
+                try {
+                    session.server.close();
+                }
+                catch { }
+                sessions.delete(id);
+            }
+        }
+    }, CLEANUP_INTERVAL_MS);
+    if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
+        cleanupTimer.unref();
+    }
+    const handleMcpRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId && sessions.has(sessionId)) {
+            // Existing session — delegate to its transport
+            const session = sessions.get(sessionId);
+            session.lastActivity = Date.now();
+            await session.transport.handleRequest(req, res, req.body);
+        }
+        else if (sessionId) {
+            // Unknown/expired session ID — tell client to re-initialize (per MCP spec)
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: { code: -32001, message: 'Session not found. Re-initialize.' },
+                id: null,
+            });
+        }
+        else if (req.method === 'POST') {
+            // No session ID — new client initializing
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+            });
+            const server = createMCPServer(backend);
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            if (transport.sessionId) {
+                sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
+                transport.onclose = () => {
+                    sessions.delete(transport.sessionId);
+                };
+            }
+        }
+        else {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'No valid session. Send a POST to initialize.' },
+                id: null,
+            });
+        }
+    };
+    app.all('/api/mcp', (req, res) => {
+        void handleMcpRequest(req, res).catch((err) => {
+            console.error('MCP HTTP request failed:', err);
+            if (res.headersSent)
+                return;
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Internal MCP server error' },
+                id: null,
+            });
+        });
+    });
+    const cleanup = async () => {
+        clearInterval(cleanupTimer);
+        const closers = [...sessions.values()].map(async (session) => {
+            try {
+                await Promise.resolve(session.server.close());
+            }
+            catch { }
+        });
+        sessions.clear();
+        await Promise.allSettled(closers);
+    };
+    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    return cleanup;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "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",
@@ -62,6 +62,7 @@
     "tree-sitter-go": "^0.21.0",
     "tree-sitter-java": "^0.21.0",
     "tree-sitter-javascript": "^0.21.0",
+    "tree-sitter-php": "^0.23.12",
     "tree-sitter-python": "^0.21.0",
     "tree-sitter-rust": "^0.21.0",
     "tree-sitter-typescript": "^0.21.0",

package/skills/gitnexus-cli.md

@@ -0,0 +1,82 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus 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.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus 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.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus 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.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

package/skills/{debugging.md → gitnexus-debugging.md}

@@ -1,11 +1,12 @@
 ---
 name: gitnexus-debugging
-description: Trace bugs through call chains using knowledge graph
+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?"
@@ -37,17 +38,18 @@ description: Trace bugs through call chains using knowledge graph
 
 ## 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 | `detect_changes` to see what your changes affect |
+| 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    | `detect_changes` to see what your changes affect           |
 
 ## Tools
 
 **gitnexus_query** — find code related to error:
+
 ```
 gitnexus_query({query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
@@ -55,6 +57,7 @@ gitnexus_query({query: "payment validation error"})
 ```
 
 **gitnexus_context** — full context for a suspect:
+
 ```
 gitnexus_context({name: "validatePayment"})
 → Incoming calls: processCheckout, webhookHandler
@@ -63,6 +66,7 @@ gitnexus_context({name: "validatePayment"})
 ```
 
 **gitnexus_cypher** — custom call chain traces:
+
 ```cypher
 MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
 RETURN [n IN nodes(path) | n.name] AS chain

package/skills/{exploring.md → gitnexus-exploring.md}

@@ -1,11 +1,12 @@
 ---
 name: gitnexus-exploring
-description: Navigate unfamiliar code using GitNexus knowledge graph
+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"
@@ -37,16 +38,17 @@ description: Navigate unfamiliar code using GitNexus knowledge graph
 
 ## Resources
 
-| Resource | What you get |
-|----------|-------------|
-| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
-| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
-| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
-| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
 
 ## Tools
 
 **gitnexus_query** — find execution flows related to a concept:
+
 ```
 gitnexus_query({query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
@@ -54,6 +56,7 @@ gitnexus_query({query: "payment processing"})
 ```
 
 **gitnexus_context** — 360-degree view of a symbol:
+
 ```
 gitnexus_context({name: "validateUser"})
 → Incoming calls: loginHandler, apiMiddleware

package/skills/gitnexus-guide.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+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.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

package/skills/{impact-analysis.md → gitnexus-impact-analysis.md}

@@ -1,11 +1,12 @@
 ---
 name: gitnexus-impact-analysis
-description: Analyze blast radius before making code changes
+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"
@@ -37,24 +38,25 @@ description: Analyze blast radius before making code changes
 
 ## 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 |
+| 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 |
+| 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 |
 
 ## Tools
 
 **gitnexus_impact** — the primary tool for symbol blast radius:
+
 ```
 gitnexus_impact({
   target: "validateUser",
@@ -72,6 +74,7 @@ gitnexus_impact({
 ```
 
 **gitnexus_detect_changes** — git-diff based impact analysis:
+
 ```
 gitnexus_detect_changes({scope: "staged"})
 

package/skills/{refactoring.md → gitnexus-refactoring.md}

@@ -1,11 +1,12 @@
 ---
 name: gitnexus-refactoring
-description: Plan safe refactors using blast radius and dependency mapping
+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"
@@ -26,6 +27,7 @@ description: Plan safe refactors using blast radius and dependency mapping
 ## 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)
@@ -35,6 +37,7 @@ description: Plan safe refactors using blast radius and dependency mapping
 ```
 
 ### Extract Module
+
 ```
 - [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
 - [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
@@ -45,6 +48,7 @@ description: Plan safe refactors using blast radius and dependency mapping
 ```
 
 ### Split Function/Service
+
 ```
 - [ ] gitnexus_context({name: target}) — understand all callees
 - [ ] Group callees by responsibility
@@ -58,6 +62,7 @@ description: Plan safe refactors using blast radius and dependency mapping
 ## Tools
 
 **gitnexus_rename** — automated multi-file rename:
+
 ```
 gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
 → 12 edits across 8 files
@@ -66,6 +71,7 @@ gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_
 ```
 
 **gitnexus_impact** — map all dependents first:
+
 ```
 gitnexus_impact({target: "validateUser", direction: "upstream"})
 → d=1: loginHandler, apiMiddleware, testUtils
@@ -73,6 +79,7 @@ gitnexus_impact({target: "validateUser", direction: "upstream"})
 ```
 
 **gitnexus_detect_changes** — verify your changes after refactoring:
+
 ```
 gitnexus_detect_changes({scope: "all"})
 → Changed: 8 files, 12 symbols
@@ -81,6 +88,7 @@ gitnexus_detect_changes({scope: "all"})
 ```
 
 **gitnexus_cypher** — custom reference queries:
+
 ```cypher
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
 RETURN caller.name, caller.filePath ORDER BY caller.filePath
@@ -88,12 +96,12 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
 
 ## 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 |
+| 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`