@duytransipher/gitnexus 1.4.6-sipher.0

package/scripts/setup-unreal-gitnexus.ps1

@@ -0,0 +1,191 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$ProjectRoot,
+
+    [string]$ProjectFile,
+
+    [string]$PluginSource = (Join-Path $PSScriptRoot '..\..\gitnexus-unreal\GitNexusUnreal'),
+
+    [string]$EditorCmd,
+
+    [int]$TimeoutMs = 300000,
+
+    [switch]$Force,
+
+    [switch]$RunAnalyze,
+
+    [string]$GitNexusCommand = 'gitnexus'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Resolve-FullPath {
+    param([Parameter(Mandatory = $true)][string]$PathValue)
+
+    return $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($PathValue)
+}
+
+function Convert-ToPortablePath {
+    param([Parameter(Mandatory = $true)][string]$PathValue)
+
+    return ($PathValue -replace '\\', '/')
+}
+
+function Get-UProjectPath {
+    param(
+        [Parameter(Mandatory = $true)][string]$Root,
+        [string]$ExplicitProjectFile
+    )
+
+    if ($ExplicitProjectFile) {
+        $resolved = Resolve-FullPath -PathValue $ExplicitProjectFile
+        if (-not (Test-Path -LiteralPath $resolved -PathType Leaf)) {
+            throw "Project file not found: $resolved"
+        }
+
+        return $resolved
+    }
+
+    $uprojects = Get-ChildItem -LiteralPath $Root -Filter '*.uproject' -File
+    if ($uprojects.Count -eq 0) {
+        throw "No .uproject file found under $Root. Pass -ProjectFile explicitly."
+    }
+
+    if ($uprojects.Count -gt 1) {
+        $names = ($uprojects | Select-Object -ExpandProperty FullName) -join ', '
+        throw "Multiple .uproject files found under ${Root}: $names. Pass -ProjectFile explicitly."
+    }
+
+    return $uprojects[0].FullName
+}
+
+function Add-EditorCmdCandidates {
+    param(
+        [Parameter(Mandatory = $true)][System.Collections.Generic.List[string]]$Candidates,
+        [string]$RootOrExe
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RootOrExe)) {
+        return
+    }
+
+    $Candidates.Add($RootOrExe)
+    $Candidates.Add((Join-Path $RootOrExe 'Engine\Binaries\Win64\UnrealEditor-Cmd.exe'))
+    $Candidates.Add((Join-Path $RootOrExe 'Engine\Windows\Engine\Binaries\Win64\UnrealEditor-Cmd.exe'))
+}
+
+function Resolve-UnrealEditorCmd {
+    param(
+        [string]$ExplicitEditorCmd,
+        [string]$EngineAssociation
+    )
+
+    if ($ExplicitEditorCmd) {
+        $resolvedExplicit = Resolve-FullPath -PathValue $ExplicitEditorCmd
+        if (-not (Test-Path -LiteralPath $resolvedExplicit -PathType Leaf)) {
+            throw "Editor command not found: $resolvedExplicit"
+        }
+
+        return $resolvedExplicit
+    }
+
+    $candidates = [System.Collections.Generic.List[string]]::new()
+
+    if ($EngineAssociation) {
+        try {
+            $builds = Get-ItemProperty -Path 'HKCU:\Software\Epic Games\Unreal Engine\Builds'
+            foreach ($property in $builds.PSObject.Properties) {
+                if ($property.Name -like 'PS*') {
+                    continue
+                }
+
+                if ($property.Name -eq $EngineAssociation) {
+                    Add-EditorCmdCandidates -Candidates $candidates -RootOrExe ([string]$property.Value)
+                }
+            }
+        } catch {
+        }
+
+        Add-EditorCmdCandidates -Candidates $candidates -RootOrExe "C:\Program Files\Epic Games\UE_$EngineAssociation"
+    }
+
+    foreach ($candidate in $candidates | Select-Object -Unique) {
+        if (Test-Path -LiteralPath $candidate -PathType Leaf) {
+            return (Resolve-FullPath -PathValue $candidate)
+        }
+    }
+
+    throw "Could not auto-detect UnrealEditor-Cmd.exe for EngineAssociation '$EngineAssociation'. Pass -EditorCmd explicitly."
+}
+
+$resolvedProjectRoot = Resolve-FullPath -PathValue $ProjectRoot
+if (-not (Test-Path -LiteralPath $resolvedProjectRoot -PathType Container)) {
+    throw "Project root not found: $resolvedProjectRoot"
+}
+
+$resolvedPluginSource = Resolve-FullPath -PathValue $PluginSource
+if (-not (Test-Path -LiteralPath $resolvedPluginSource -PathType Container)) {
+    throw "Plugin source not found: $resolvedPluginSource"
+}
+
+$uprojectPath = Get-UProjectPath -Root $resolvedProjectRoot -ExplicitProjectFile $ProjectFile
+$uproject = Get-Content -LiteralPath $uprojectPath -Raw | ConvertFrom-Json
+$engineAssociation = ''
+if ($uproject.PSObject.Properties.Name -contains 'EngineAssociation') {
+    $engineAssociation = [string]$uproject.EngineAssociation
+}
+
+$resolvedEditorCmd = Resolve-UnrealEditorCmd -ExplicitEditorCmd $EditorCmd -EngineAssociation $engineAssociation
+
+$pluginsRoot = Join-Path $resolvedProjectRoot 'Plugins'
+$pluginDestination = Join-Path $pluginsRoot 'GitNexusUnreal'
+$gitnexusRoot = Join-Path $resolvedProjectRoot '.gitnexus'
+$unrealRoot = Join-Path $gitnexusRoot 'unreal'
+$configPath = Join-Path $unrealRoot 'config.json'
+
+if ((Test-Path -LiteralPath $pluginDestination) -and -not $Force) {
+    throw "Plugin destination already exists: $pluginDestination. Remove it first or rerun with -Force."
+}
+
+if ((Test-Path -LiteralPath $configPath) -and -not $Force) {
+    throw "Config already exists: $configPath. Remove it first or rerun with -Force."
+}
+
+New-Item -ItemType Directory -Path $pluginsRoot -Force | Out-Null
+New-Item -ItemType Directory -Path $unrealRoot -Force | Out-Null
+
+if (Test-Path -LiteralPath $pluginDestination) {
+    Remove-Item -LiteralPath $pluginDestination -Recurse -Force
+}
+
+Copy-Item -LiteralPath $resolvedPluginSource -Destination $pluginDestination -Recurse
+
+$config = [ordered]@{
+    editor_cmd  = Convert-ToPortablePath -PathValue $resolvedEditorCmd
+    project_path = Convert-ToPortablePath -PathValue $uprojectPath
+    commandlet  = 'GitNexusBlueprintAnalyzer'
+    timeout_ms  = $TimeoutMs
+}
+
+$config | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath $configPath -Encoding UTF8
+
+if ($RunAnalyze) {
+    Push-Location $resolvedProjectRoot
+    try {
+        & $GitNexusCommand analyze
+    } finally {
+        Pop-Location
+    }
+}
+
+Write-Host "Installed GitNexusUnreal plugin to: $pluginDestination"
+Write-Host "Wrote Unreal config to: $configPath"
+Write-Host "Resolved UnrealEditor-Cmd.exe: $resolvedEditorCmd"
+Write-Host ""
+Write-Host "Next steps:"
+Write-Host "1. Build your Unreal editor target."
+Write-Host "2. Run 'gitnexus analyze' in $resolvedProjectRoot if you have not indexed the repo yet."
+Write-Host "3. Run 'gitnexus unreal-sync'."
+Write-Host "4. Run 'gitnexus unreal-find-refs ""Class::Function""'."

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. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+
+### 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/gitnexus-debugging.md

@@ -0,0 +1,89 @@
+---
+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. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## 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
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## 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           |
+
+## 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:
+
+```cypher
+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. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

package/skills/gitnexus-exploring.md

@@ -0,0 +1,78 @@
+---
+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. 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
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## 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)              |
+
+## 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)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```

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/gitnexus-impact-analysis.md

@@ -0,0 +1,97 @@
+---
+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. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_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.
+
+## Checklist
+
+```
+- [ ] gitnexus_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
+- [ ] Assess risk level and report to user
+```
+
+## 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 |
+
+## Tools
+
+**gitnexus_impact** — the 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. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```