@veewo/gitnexus 1.4.8-rc → 1.4.8-rc.2

package/README.md

@@ -18,17 +18,16 @@ AI coding tools don't understand your codebase structure. They edit a function w
 ## Quick Start
 
 ```bash
-# Optional: pin one version for the whole session (example RC)
-# export GITNEXUS_CLI_SPEC="@veewo/gitnexus@1.4.7-rc"
-GITNEXUS_CLI_SPEC="${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}"
-
-# Index your repo (run from repo root)
-npx -y "${GITNEXUS_CLI_SPEC}" analyze
+npm install -g @veewo/gitnexus
+gitnexus setup --cli-spec @veewo/gitnexus
+gitnexus analyze
 ```
 
 That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-To configure MCP for your editor, run `npx -y "${GITNEXUS_CLI_SPEC}" setup --cli-spec "$GITNEXUS_CLI_SPEC"` once — or set it up manually below.
+After `setup`, repository workflows resolve any npx package fallback from `~/.gitnexus/config.json` instead of defaulting to `@latest`.
+
+To configure MCP for your editor, run `gitnexus setup --cli-spec <packageSpec>` once — or set it up manually below.
 
 `gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
 
@@ -56,7 +55,7 @@ If you prefer to configure manually instead of using `gitnexus setup`:
 ### Claude Code (full support — MCP + skills + hooks)
 
 ```bash
-claude mcp add gitnexus -- npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" mcp
+claude mcp add gitnexus -- gitnexus mcp
 ```
 
 ### Cursor / Windsurf
@@ -67,8 +66,8 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
 {
   "mcpServers": {
     "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "@veewo/gitnexus@latest", "mcp"]
+      "command": "gitnexus",
+      "args": ["mcp"]
     }
   }
 }
@@ -82,8 +81,8 @@ Add to `~/.config/opencode/config.json`:
 {
   "mcp": {
     "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "@veewo/gitnexus@latest", "mcp"]
+      "command": "gitnexus",
+      "args": ["mcp"]
     }
   }
 }
@@ -141,10 +140,10 @@ Your AI agent gets these tools automatically:
 
 ```bash
 gitnexus setup                    # Configure MCP for your editors (one-time)
-npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze [path]           # Index a repository (or update stale index)
-npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze --force          # Force full re-index
-npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze --embeddings     # Enable embedding generation (slower, better search)
-npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze --verbose        # Log skipped files when parsers are unavailable
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --embeddings     # Enable embedding generation (slower, better search)
+gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus list                    # List all indexed repositories
@@ -157,7 +156,7 @@ gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-m
 
 ## Multi-Repo Support
 
-GitNexus supports indexing multiple repositories. Each `npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
 
 ## Supported Languages
 
@@ -192,7 +191,7 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Impact Analysis** — Analyze blast radius before changes
 - **Refactoring** — Plan safe refactors using dependency mapping
 
-Installed automatically by both `npx -y "${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}" analyze` (per-repo) and `gitnexus setup` (global).
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
 
 ## Requirements
 

package/dist/cli/ai-context.js

@@ -44,7 +44,7 @@ This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} s
 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, ask user whether to rebuild index via \`gitnexus analyze\` when local CLI exists; otherwise run \`${reindexCmd}\` (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
+> If step 1 warns the index is stale, ask user whether to rebuild index via \`gitnexus analyze\` when local CLI exists; otherwise resolve the pinned npx package spec from \`~/.gitnexus/config.json\` (\`cliPackageSpec\` first, then \`cliVersion\`) and run \`${reindexCmd}\` with that exact package spec (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
 
 ## Skills
 

package/dist/cli/setup.js

@@ -264,7 +264,6 @@ async function installClaudeCodeHooks(result, mcpPackageSpec) {
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
             content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
-            content = content.replace("const DEFAULT_NPX_SPEC = '@veewo/gitnexus@latest';", `const DEFAULT_NPX_SPEC = ${JSON.stringify(mcpPackageSpec)};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {

package/hooks/claude/gitnexus-hook.cjs

@@ -15,7 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawnSync } = require('child_process');
-const DEFAULT_NPX_SPEC = '@veewo/gitnexus@latest';
+const DEFAULT_NPX_SPEC = '';
 const DEFAULT_PACKAGE_NAME = '@veewo/gitnexus';
 
 function normalizeNpxSpec(raw) {
@@ -150,6 +150,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout, npxSpec) {
       { encoding: 'utf-8', timeout, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
     );
   }
+  if (!npxSpec) return null;
   // On Windows, invoke npx.cmd directly (no shell needed)
   return spawnSync(
     isWin ? 'npx.cmd' : 'npx',
@@ -179,7 +180,7 @@ function handlePreToolUse(input) {
   let result = '';
   try {
     const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000, npxSpec);
-    if (!child.error && child.status === 0) {
+    if (child && !child.error && child.status === 0) {
       result = child.stderr || '';
     }
   } catch { /* graceful failure */ }
@@ -248,10 +249,14 @@ function handlePostToolUse(input) {
   const npxSpec = resolveNpxSpec();
   const analyzeArgs = `analyze${hadEmbeddings ? ' --embeddings' : ''}`;
   const analyzeCmd = `gitnexus ${analyzeArgs}`;
-  const fallbackCmd = `npx -y ${npxSpec} ${analyzeArgs}`;
+  const fallbackCmd = npxSpec
+    ? `npx -y ${npxSpec} ${analyzeArgs}`
+    : null;
   sendHookResponse('PostToolUse',
     `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
-    `Run \`${analyzeCmd}\` (or \`${fallbackCmd}\`) to update the knowledge graph.`
+    (fallbackCmd
+      ? `Run \`${analyzeCmd}\` (or \`${fallbackCmd}\`) to update the knowledge graph.`
+      : `Run \`${analyzeCmd}\` to update the knowledge graph. If local CLI is unavailable, populate ~/.gitnexus/config.json via \`gitnexus setup --cli-spec <packageSpec>\` first.`)
   );
 }
 

package/hooks/claude/pre-tool-use.sh

@@ -64,11 +64,32 @@ fi
 
 # Run gitnexus augment — must be fast (<500ms target)
 # augment writes to stderr (KuzuDB captures stdout at OS level), so capture stderr and discard stdout
-GITNEXUS_CLI_SPEC="${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}"
-if [ -n "$GITNEXUS_CLI_VERSION" ]; then
-  GITNEXUS_CLI_SPEC="@veewo/gitnexus@$GITNEXUS_CLI_VERSION"
+if command -v gitnexus >/dev/null 2>&1; then
+  RESULT=$(cd "$CWD" && gitnexus augment "$PATTERN" 2>&1 1>/dev/null)
+else
+  if [ -n "$GITNEXUS_CLI_SPEC" ]; then
+    :
+  elif [ -n "$GITNEXUS_CLI_VERSION" ]; then
+    GITNEXUS_CLI_SPEC="@veewo/gitnexus@$GITNEXUS_CLI_VERSION"
+  elif [ -f "${HOME}/.gitnexus/config.json" ]; then
+    GITNEXUS_CLI_SPEC="$(
+      node -e 'const fs=require("fs");const os=require("os");const path=require("path");
+      try {
+        const raw=fs.readFileSync(path.join(os.homedir(),".gitnexus","config.json"),"utf8");
+        const parsed=JSON.parse(raw);
+        const spec=typeof parsed.cliPackageSpec==="string" && parsed.cliPackageSpec.trim()
+          ? parsed.cliPackageSpec.trim()
+          : typeof parsed.cliVersion==="string" && parsed.cliVersion.trim()
+            ? `@veewo/gitnexus@${parsed.cliVersion.trim()}`
+            : "";
+        if (spec) process.stdout.write(spec);
+      } catch {}'
+    )"
+  fi
+
+  [ -z "$GITNEXUS_CLI_SPEC" ] && exit 0
+  RESULT=$(cd "$CWD" && npx -y "$GITNEXUS_CLI_SPEC" augment "$PATTERN" 2>&1 1>/dev/null)
 fi
-RESULT=$(cd "$CWD" && npx -y "$GITNEXUS_CLI_SPEC" augment "$PATTERN" 2>&1 1>/dev/null)
 
 if [ -n "$RESULT" ]; then
   ESCAPED=$(echo "$RESULT" | jq -Rs .)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.4.8-rc",
+  "version": "1.4.8-rc.2",
   "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-cli.md

@@ -5,15 +5,29 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/
 
 # GitNexus CLI Commands
 
-Use one command alias in the session so every CLI/MCP call stays on one version line.
+Use one command alias in the session so every CLI/MCP call stays on one version line. After `setup`, treat `~/.gitnexus/config.json` as the only npx version source.
 
 ```bash
-# If user prompt specifies a version (example: 1.4.7-rc), set it once:
-# export GITNEXUS_CLI_SPEC="@veewo/gitnexus@1.4.7-rc"
-GITNEXUS_CLI_SPEC="${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest}"
 if command -v gitnexus >/dev/null 2>&1; then
   GN="gitnexus"
 else
+  GITNEXUS_CLI_SPEC="$(
+    node -e 'const fs=require("fs");const os=require("os");const path=require("path");
+    try {
+      const raw=fs.readFileSync(path.join(os.homedir(),".gitnexus","config.json"),"utf8");
+      const parsed=JSON.parse(raw);
+      const spec=typeof parsed.cliPackageSpec==="string" && parsed.cliPackageSpec.trim()
+        ? parsed.cliPackageSpec.trim()
+        : typeof parsed.cliVersion==="string" && parsed.cliVersion.trim()
+          ? `@veewo/gitnexus@${parsed.cliVersion.trim()}`
+          : "";
+      if (spec) process.stdout.write(spec);
+    } catch {}'
+  )"
+  if [ -z "$GITNEXUS_CLI_SPEC" ]; then
+    echo "Missing GitNexus CLI package spec in ~/.gitnexus/config.json. Run gitnexus setup --cli-spec <packageSpec> first." >&2
+    exit 1
+  fi
   GN="npx -y ${GITNEXUS_CLI_SPEC}"
 fi
 ```

package/skills/gitnexus-debugging.md

@@ -23,7 +23,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 5. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze`.
 
 ## Checklist
 

package/skills/gitnexus-exploring.md

@@ -24,7 +24,7 @@ description: "Use when the user asks how code works, wants to understand archite
 6. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
 
-> If step 2 says "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
+> If step 2 says "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze`.
 
 ## Checklist
 

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 `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
+> If step 1 warns the index is stale, run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze`.
 
 ## Skills
 

package/skills/gitnexus-impact-analysis.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to know what will break if they change som
 4. Assess risk and report to user
 ```
 
-> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze`.
 
 ## Checklist
 

package/skills/gitnexus-pr-review.md

@@ -26,7 +26,7 @@ description: "Use when the user wants to review a pull request, understand what
 6. Summarize findings with risk assessment
 ```
 
-> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze` before reviewing.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze` before reviewing.
 
 ## Checklist
 

package/skills/gitnexus-refactoring.md

@@ -23,7 +23,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 5. Plan update order: interfaces → implementations → callers → tests
 ```
 
-> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise run `npx -y ${GITNEXUS_CLI_SPEC:-@veewo/gitnexus@latest} analyze`.
+> If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze`.
 
 ## Checklists