pi-gitnexus 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.3.0
 
+- **Configurable command** — the gitnexus binary invocation is now configurable. Default is `gitnexus` on PATH. Use `/gitnexus config` to set a custom command (e.g. `npx gitnexus@latest`) via an input dialog; the value is persisted to `~/.pi/pi-gitnexus.json`. The `--gitnexus-cmd` CLI flag overrides the saved config for one-off runs. Nothing is ever installed automatically.
 - **TypeScript compatibility** — `tool_result` handler now uses inferred event types from the API overload instead of a manual annotation, fixing a compile error with `@mariozechner/pi-coding-agent` 0.54.x.
 - **Dependency updates** — `@mariozechner/pi-coding-agent` to 0.54.2, `@types/node` to 25.x.
 

package/README.md

@@ -28,15 +28,18 @@ Five tools are also registered directly in pi — the agent can use them explici
 
 ## Requirements
 
-- [gitnexus](https://github.com/abhigyanpatwari/GitNexus) installed globally: `npm i -g gitnexus`
+- [gitnexus](https://github.com/abhigyanpatwari/GitNexus) available as `gitnexus` on PATH (e.g. `npm i -g gitnexus`)
 - A GitNexus index in your project: run `/gitnexus analyze`
 
+The extension never installs anything automatically. It assumes `gitnexus` is on PATH. If your setup differs, use `/gitnexus config` to set a custom command (e.g. `npx gitnexus@latest`).
+
 ## Getting started
 
-1. Install gitnexus: `npm i -g gitnexus`
-2. Open your project in pi
-3. Run `/gitnexus analyze` to build the knowledge graph
-4. Done — file reads and searches are now enriched automatically
+1. Install the extension: `pi install npm:pi-gitnexus`
+2. Install gitnexus: `npm i -g gitnexus`
+3. Open your project in pi
+4. Run `/gitnexus analyze` to build the knowledge graph
+5. Done — file reads and searches are now enriched automatically
 
 ## What triggers augmentation
 
@@ -59,6 +62,7 @@ Each tool result augments up to 3 patterns in parallel. Patterns already augment
 | `/gitnexus` | Show index status and session enrichment count |
 | `/gitnexus analyze` | Build or rebuild the knowledge graph |
 | `/gitnexus on` / `/gitnexus off` | Enable/disable auto-augment (tools unaffected) |
+| `/gitnexus config` | Set the gitnexus command (saved to `~/.pi/pi-gitnexus.json`) |
 | `/gitnexus <pattern>` | Manual graph lookup for a symbol or pattern |
 | `/gitnexus query <text>` | Search execution flows |
 | `/gitnexus context <name>` | 360° view of a symbol: callers, callees, processes |
@@ -97,6 +101,7 @@ This extension (pi-gitnexus) is MIT licensed. [GitNexus](https://github.com/abhi
 
 ## Notes
 
+- The extension never runs `gitnexus analyze` automatically — indexing is always user-initiated via `/gitnexus analyze`.
 - The index is a static snapshot. Re-run `/gitnexus analyze` after significant code changes. The agent will suggest this when the index appears stale.
 - `gitnexus_detect_changes` is a lightweight alternative: pass `git diff HEAD` output to see affected flows without a full reindex.
 - `gitnexus_cypher` and `gitnexus_rename` are intentionally not exposed (raw graph access and automated multi-file rename).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gitnexus",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "GitNexus knowledge graph integration for pi — enriches searches with call chains, execution flows, and blast radius",
   "author": "tintinweb",
   "license": "MIT",

package/src/gitnexus.ts

@@ -1,6 +1,7 @@
 import { spawn } from 'child_process';
-import { resolve, sep, basename, extname } from 'path';
-import { existsSync } from 'fs';
+import { resolve, sep, basename, extname, join } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
 
 /** Max output chars returned to the LLM. Prevents context flooding. JS strings are UTF-16 chars, not bytes. */
 export const MAX_OUTPUT_CHARS = 8 * 1024;
@@ -13,6 +14,35 @@ export const MAX_OUTPUT_CHARS = 8 * 1024;
 export let spawnEnv: NodeJS.ProcessEnv = process.env;
 export function updateSpawnEnv(env: NodeJS.ProcessEnv): void { spawnEnv = env; }
 
+/**
+ * Resolved command prefix for invoking gitnexus.
+ * Set to ['gitnexus'] when the binary is on PATH, otherwise ['npx', '-y', 'gitnexus@latest'].
+ * Updated by setGitnexusCmd() during session_start probe.
+ */
+export let gitnexusCmd: string[] = ['gitnexus'];
+export function setGitnexusCmd(cmd: string[]): void { gitnexusCmd = cmd; }
+
+const CONFIG_PATH = join(homedir(), '.pi', 'pi-gitnexus.json');
+
+interface GitNexusConfig {
+  cmd?: string;
+}
+
+export function loadSavedConfig(): GitNexusConfig {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) as GitNexusConfig;
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: GitNexusConfig): void {
+  try {
+    mkdirSync(join(homedir(), '.pi'), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+  } catch { /* ignore write errors */ }
+}
+
 /** Augment subprocess timeout in ms. Applied via setTimeout + proc.kill('SIGTERM') — spawn has no built-in timeout. */
 const AUGMENT_TIMEOUT = 8_000;
 
@@ -174,7 +204,8 @@ export async function runAugment(pattern: string, cwd: string): Promise<string>
     let output = '';
     let done = false;
 
-    const proc = spawn('gitnexus', ['augment', pattern], {
+    const [bin, ...baseArgs] = gitnexusCmd;
+    const proc = spawn(bin, [...baseArgs, 'augment', pattern], {
       cwd,
       stdio: ['ignore', 'ignore', 'pipe'],
       env: spawnEnv,

package/src/index.ts

@@ -1,6 +1,6 @@
 import { spawn } from 'child_process';
 import type { ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
-import { findGitNexusIndex, clearIndexCache, extractPattern, extractFilePatternsFromContent, runAugment, spawnEnv, updateSpawnEnv } from './gitnexus';
+import { findGitNexusIndex, clearIndexCache, extractPattern, extractFilePatternsFromContent, runAugment, spawnEnv, updateSpawnEnv, gitnexusCmd, setGitnexusCmd, loadSavedConfig, saveConfig } from './gitnexus';
 import { mcpClient } from './mcp-client';
 import { registerTools } from './tools';
 
@@ -19,14 +19,20 @@ async function resolveShellPath(): Promise<void> {
   updateSpawnEnv({ ...process.env, PATH: path });
 }
 
-function probeGitNexusBinary(): Promise<boolean> {
+function trySpawn(bin: string, args: string[]): Promise<boolean> {
   return new Promise((resolve_) => {
-    const proc = spawn('gitnexus', ['--version'], { stdio: 'ignore', env: spawnEnv });
+    const proc = spawn(bin, args, { stdio: 'ignore', env: spawnEnv });
     proc.on('close', (code: number | null) => resolve_(code === 0));
     proc.on('error', () => resolve_(false));
   });
 }
 
+/** Probe for gitnexus using the configured command. */
+async function probeGitNexusBinary(): Promise<boolean> {
+  const [bin, ...args] = gitnexusCmd;
+  return trySpawn(bin, [...args, '--version']);
+}
+
 /** Cached from session_start/session_switch — avoids re-probing on every /gitnexus status. */
 let binaryAvailable = false;
 
@@ -51,6 +57,12 @@ const augmentedCache = new Set<string>();
 export default function(pi: ExtensionAPI) {
   registerTools(pi);
 
+  pi.registerFlag('gitnexus-cmd', {
+    type: 'string',
+    default: 'gitnexus',
+    description: 'Command used to invoke gitnexus, e.g. "npx gitnexus@latest"',
+  });
+
   // Append a one-liner so the agent understands graph context in search results.
   pi.on('before_agent_start', async (event: { systemPrompt?: string }, ctx: ExtensionContext) => {
     if (!findGitNexusIndex(ctx.cwd)) return;
@@ -111,6 +123,12 @@ export default function(pi: ExtensionAPI) {
     sessionCwd = ctx.cwd;
     await resolveShellPath();
 
+    // Resolve command: default → saved config → CLI flag (highest precedence)
+    const saved = loadSavedConfig().cmd;
+    const flag = pi.getFlag('gitnexus-cmd') as string | undefined;
+    const cmdStr = flag ?? saved ?? 'gitnexus';
+    setGitnexusCmd(cmdStr.trim().split(/\s+/));
+
     binaryAvailable = await probeGitNexusBinary();
     if (!findGitNexusIndex(ctx.cwd)) return;
 
@@ -149,7 +167,8 @@ export default function(pi: ExtensionAPI) {
         }
         const out = await new Promise<string>((resolve_) => {
           let stdout = '';
-          const proc = spawn('gitnexus', ['status'], {
+          const [bin, ...baseArgs] = gitnexusCmd;
+          const proc = spawn(bin, [...baseArgs, 'status'], {
             cwd: ctx.cwd,
             stdio: ['ignore', 'pipe', 'ignore'],
             env: spawnEnv,
@@ -174,6 +193,7 @@ export default function(pi: ExtensionAPI) {
           '  /gitnexus             — show status\n' +
           '  /gitnexus analyze     — index the codebase\n' +
           '  /gitnexus on|off      — enable/disable auto-augment on searches\n' +
+          '  /gitnexus config      — set the gitnexus command (saved to ~/.pi/pi-gitnexus.json)\n' +
           '  /gitnexus <pattern>   — manual graph lookup\n' +
           '  /gitnexus query <q>   — search execution flows\n' +
           '  /gitnexus context <n> — callers/callees of a symbol\n' +
@@ -194,6 +214,19 @@ export default function(pi: ExtensionAPI) {
         return;
       }
 
+      // /gitnexus config
+      if (sub === 'config') {
+        const current = gitnexusCmd.join(' ');
+        const input = await ctx.ui.input('gitnexus command', current);
+        if (input === undefined) return; // cancelled
+        const trimmed = input.trim();
+        if (!trimmed) return;
+        setGitnexusCmd(trimmed.split(/\s+/));
+        saveConfig({ cmd: trimmed });
+        ctx.ui.notify(`GitNexus command set to: ${trimmed}`, 'info');
+        return;
+      }
+
       // /gitnexus analyze
       if (sub === 'analyze') {
         if (!binaryAvailable) {
@@ -203,7 +236,8 @@ export default function(pi: ExtensionAPI) {
         augmentEnabled = false;
         ctx.ui.notify('GitNexus: analyzing codebase, this may take a while…', 'info');
         const exitCode = await new Promise<number | null>((resolve_) => {
-          const proc = spawn('gitnexus', ['analyze'], {
+          const [bin, ...baseArgs] = gitnexusCmd;
+          const proc = spawn(bin, [...baseArgs, 'analyze'], {
             cwd: ctx.cwd,
             stdio: 'ignore',
             env: spawnEnv,

package/src/mcp-client.ts

@@ -1,5 +1,5 @@
 import { spawn, ChildProcess } from 'child_process';
-import { MAX_OUTPUT_CHARS, spawnEnv } from './gitnexus';
+import { MAX_OUTPUT_CHARS, spawnEnv, gitnexusCmd } from './gitnexus';
 
 interface JsonRpcResponse {
   jsonrpc: '2.0';
@@ -45,7 +45,8 @@ class GitNexusMcpClient {
     if (this.startPromise) return this.startPromise;
 
     this.startPromise = new Promise<void>((resolve_, reject) => {
-      const proc = spawn('gitnexus', ['mcp'], {
+      const [bin, ...baseArgs] = gitnexusCmd;
+      const proc = spawn(bin, [...baseArgs, 'mcp'], {
         cwd,
         stdio: ['pipe', 'pipe', 'ignore'],
         env: spawnEnv,