gitnexus 1.1.8 → 1.2.0

package/dist/cli/setup.js

@@ -8,7 +8,10 @@
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
+import { fileURLToPath } from 'url';
 import { getGlobalDir } from '../storage/repo-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 /**
  * The MCP server entry for all editors
  */
@@ -82,8 +85,6 @@ async function setupCursor(result) {
     }
 }
 async function setupClaudeCode(result) {
-    // Claude Code uses `claude mcp add` — we just print the command
-    // Check for common Claude Code indicators
     const claudeDir = path.join(os.homedir(), '.claude');
     const hasClaude = await dirExists(claudeDir);
     if (!hasClaude) {
@@ -92,11 +93,82 @@ async function setupClaudeCode(result) {
     }
     // Claude Code uses a JSON settings file at ~/.claude.json or claude mcp add
     console.log('');
-    console.log('  Claude Code detected. Run this command to add GitNexus:');
+    console.log('  Claude Code detected. Run this command to add GitNexus MCP:');
     console.log('');
     console.log('    claude mcp add gitnexus -- npx -y gitnexus mcp');
     console.log('');
-    result.configured.push('Claude Code (manual step printed)');
+    result.configured.push('Claude Code (MCP manual step printed)');
+}
+/**
+ * Install GitNexus skills to ~/.claude/skills/ for Claude Code.
+ */
+async function installClaudeCodeSkills(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    if (!(await dirExists(claudeDir)))
+        return;
+    const skillsDir = path.join(claudeDir, 'skills');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Claude Code skills (${installed.length} skills → ~/.claude/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Claude Code skills: ${err.message}`);
+    }
+}
+/**
+ * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
+ * Merges hook config without overwriting existing hooks.
+ */
+async function installClaudeCodeHooks(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    if (!(await dirExists(claudeDir)))
+        return;
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    // Source hooks bundled within the gitnexus package (hooks/claude/)
+    const pluginHooksPath = path.join(__dirname, '..', '..', 'hooks', 'claude');
+    // Copy unified hook script to ~/.claude/hooks/gitnexus/
+    const destHooksDir = path.join(claudeDir, 'hooks', 'gitnexus');
+    try {
+        await fs.mkdir(destHooksDir, { recursive: true });
+        const src = path.join(pluginHooksPath, 'gitnexus-hook.cjs');
+        const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
+        try {
+            const content = await fs.readFile(src, 'utf-8');
+            await fs.writeFile(dest, content, 'utf-8');
+        }
+        catch {
+            // Script not found in source — skip
+        }
+        const hookCmd = `node "${path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/')}"`;
+        // Merge hook config into ~/.claude/settings.json
+        const existing = await readJsonFile(settingsPath) || {};
+        if (!existing.hooks)
+            existing.hooks = {};
+        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
+        // Session context is delivered via CLAUDE.md / skills instead.
+        // Add PreToolUse hook if not already present
+        if (!existing.hooks.PreToolUse)
+            existing.hooks.PreToolUse = [];
+        const hasPreToolHook = existing.hooks.PreToolUse.some((h) => h.hooks?.some((hh) => hh.command?.includes('gitnexus')));
+        if (!hasPreToolHook) {
+            existing.hooks.PreToolUse.push({
+                matcher: 'Grep|Glob|Bash',
+                hooks: [{
+                        type: 'command',
+                        command: hookCmd,
+                        timeout: 8000,
+                        statusMessage: 'Enriching with GitNexus graph context...',
+                    }],
+            });
+        }
+        await writeJsonFile(settingsPath, existing);
+        result.configured.push('Claude Code hooks (PreToolUse)');
+    }
+    catch (err) {
+        result.errors.push(`Claude Code hooks: ${err.message}`);
+    }
 }
 async function setupOpenCode(result) {
     const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
@@ -118,6 +190,104 @@ async function setupOpenCode(result) {
         result.errors.push(`OpenCode: ${err.message}`);
     }
 }
+// ─── Skill Installation ───────────────────────────────────────────
+const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring'];
+/**
+ * Install GitNexus skills to a target directory.
+ * Each skill is installed as {targetDir}/gitnexus-{skillName}/SKILL.md
+ * following the Agent Skills standard (both Cursor and Claude Code).
+ *
+ * Supports two source layouts:
+ *   - Flat file:  skills/{name}.md           → copied as SKILL.md
+ *   - Directory:  skills/{name}/SKILL.md     → copied recursively (includes references/, etc.)
+ */
+async function installSkillsTo(targetDir) {
+    const installed = [];
+    const skillsRoot = path.join(__dirname, '..', '..', 'skills');
+    for (const skillName of SKILL_NAMES) {
+        const skillDir = path.join(targetDir, `gitnexus-${skillName}`);
+        try {
+            // Try directory-based skill first (skills/{name}/SKILL.md)
+            const dirSource = path.join(skillsRoot, skillName);
+            const dirSkillFile = path.join(dirSource, 'SKILL.md');
+            let isDirectory = false;
+            try {
+                const stat = await fs.stat(dirSource);
+                isDirectory = stat.isDirectory();
+            }
+            catch { /* not a directory */ }
+            if (isDirectory) {
+                await copyDirRecursive(dirSource, skillDir);
+                installed.push(skillName);
+            }
+            else {
+                // Fall back to flat file (skills/{name}.md)
+                const flatSource = path.join(skillsRoot, `${skillName}.md`);
+                const content = await fs.readFile(flatSource, 'utf-8');
+                await fs.mkdir(skillDir, { recursive: true });
+                await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+                installed.push(skillName);
+            }
+        }
+        catch {
+            // Source skill not found — skip
+        }
+    }
+    return installed;
+}
+/**
+ * Recursively copy a directory tree.
+ */
+async function copyDirRecursive(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Install global Cursor skills to ~/.cursor/skills/gitnexus/
+ */
+async function installCursorSkills(result) {
+    const cursorDir = path.join(os.homedir(), '.cursor');
+    if (!(await dirExists(cursorDir)))
+        return;
+    const skillsDir = path.join(cursorDir, 'skills');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Cursor skills (${installed.length} skills → ~/.cursor/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Cursor skills: ${err.message}`);
+    }
+}
+/**
+ * Install global OpenCode skills to ~/.config/opencode/skill/gitnexus/
+ */
+async function installOpenCodeSkills(result) {
+    const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
+    if (!(await dirExists(opencodeDir)))
+        return;
+    const skillsDir = path.join(opencodeDir, 'skill');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`OpenCode skills (${installed.length} skills → ~/.config/opencode/skill/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`OpenCode skills: ${err.message}`);
+    }
+}
 // ─── Main command ──────────────────────────────────────────────────
 export const setupCommand = async () => {
     console.log('');
@@ -132,10 +302,15 @@ export const setupCommand = async () => {
         skipped: [],
         errors: [],
     };
-    // Detect and configure each editor
+    // Detect and configure each editor's MCP
     await setupCursor(result);
     await setupClaudeCode(result);
     await setupOpenCode(result);
+    // Install global skills for platforms that support them
+    await installClaudeCodeSkills(result);
+    await installClaudeCodeHooks(result);
+    await installCursorSkills(result);
+    await installOpenCodeSkills(result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -158,6 +333,10 @@ export const setupCommand = async () => {
         }
     }
     console.log('');
+    console.log('  Summary:');
+    console.log(`    MCP configured for: ${result.configured.filter(c => !c.includes('skills')).join(', ') || 'none'}`);
+    console.log(`    Skills installed to: ${result.configured.filter(c => c.includes('skills')).length > 0 ? result.configured.filter(c => c.includes('skills')).join(', ') : 'none'}`);
+    console.log('');
     console.log('  Next steps:');
     console.log('    1. cd into any git repo');
     console.log('    2. Run: gitnexus analyze');

package/dist/cli/tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Direct CLI Tool Commands
+ *
+ * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
+ *
+ * Usage:
+ *   gitnexus query "authentication flow"
+ *   gitnexus context --name "validateUser"
+ *   gitnexus impact --target "AuthService" --direction upstream
+ *   gitnexus cypher "MATCH (n:Function) RETURN n.name LIMIT 10"
+ *
+ * Note: Output goes to stderr because KuzuDB's native module captures stdout
+ * at the OS level during init. This is consistent with augment.ts.
+ */
+export declare function queryCommand(queryText: string, options?: {
+    repo?: string;
+    context?: string;
+    goal?: string;
+    limit?: string;
+    content?: boolean;
+}): Promise<void>;
+export declare function contextCommand(name: string, options?: {
+    repo?: string;
+    file?: string;
+    uid?: string;
+    content?: boolean;
+}): Promise<void>;
+export declare function impactCommand(target: string, options?: {
+    direction?: string;
+    repo?: string;
+    depth?: string;
+    includeTests?: boolean;
+}): Promise<void>;
+export declare function cypherCommand(query: string, options?: {
+    repo?: string;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -0,0 +1,91 @@
+/**
+ * Direct CLI Tool Commands
+ *
+ * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
+ *
+ * Usage:
+ *   gitnexus query "authentication flow"
+ *   gitnexus context --name "validateUser"
+ *   gitnexus impact --target "AuthService" --direction upstream
+ *   gitnexus cypher "MATCH (n:Function) RETURN n.name LIMIT 10"
+ *
+ * Note: Output goes to stderr because KuzuDB's native module captures stdout
+ * at the OS level during init. This is consistent with augment.ts.
+ */
+import { LocalBackend } from '../mcp/local/local-backend.js';
+let _backend = null;
+async function getBackend() {
+    if (_backend)
+        return _backend;
+    _backend = new LocalBackend();
+    const ok = await _backend.init();
+    if (!ok) {
+        console.error('GitNexus: No indexed repositories found. Run: gitnexus analyze');
+        process.exit(1);
+    }
+    return _backend;
+}
+function output(data) {
+    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    // stderr because KuzuDB captures stdout at OS level
+    process.stderr.write(text + '\n');
+}
+export async function queryCommand(queryText, options) {
+    if (!queryText?.trim()) {
+        console.error('Usage: gitnexus query <search_query>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('query', {
+        query: queryText,
+        task_context: options?.context,
+        goal: options?.goal,
+        limit: options?.limit ? parseInt(options.limit) : undefined,
+        include_content: options?.content ?? false,
+        repo: options?.repo,
+    });
+    output(result);
+}
+export async function contextCommand(name, options) {
+    if (!name?.trim() && !options?.uid) {
+        console.error('Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('context', {
+        name: name || undefined,
+        uid: options?.uid,
+        file_path: options?.file,
+        include_content: options?.content ?? false,
+        repo: options?.repo,
+    });
+    output(result);
+}
+export async function impactCommand(target, options) {
+    if (!target?.trim()) {
+        console.error('Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('impact', {
+        target,
+        direction: options?.direction || 'upstream',
+        maxDepth: options?.depth ? parseInt(options.depth) : undefined,
+        includeTests: options?.includeTests ?? false,
+        repo: options?.repo,
+    });
+    output(result);
+}
+export async function cypherCommand(query, options) {
+    if (!query?.trim()) {
+        console.error('Usage: gitnexus cypher <cypher_query>');
+        process.exit(1);
+    }
+    const backend = await getBackend();
+    const result = await backend.callTool('cypher', {
+        query,
+        repo: options?.repo,
+    });
+    output(result);
+}

package/dist/cli/wiki.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wiki Command
+ *
+ * Generates repository documentation from the knowledge graph.
+ * Usage: gitnexus wiki [path] [options]
+ */
+export interface WikiCommandOptions {
+    force?: boolean;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+}
+export declare const wikiCommand: (inputPath?: string, options?: WikiCommandOptions) => Promise<void>;

package/dist/cli/wiki.js

@@ -0,0 +1,199 @@
+/**
+ * Wiki Command
+ *
+ * Generates repository documentation from the knowledge graph.
+ * Usage: gitnexus wiki [path] [options]
+ */
+import path from 'path';
+import readline from 'readline';
+import cliProgress from 'cli-progress';
+import { getGitRoot, isGitRepo } from '../storage/git.js';
+import { getStoragePaths, loadMeta, loadCLIConfig, saveCLIConfig } from '../storage/repo-manager.js';
+import { WikiGenerator } from '../core/wiki/generator.js';
+import { resolveLLMConfig } from '../core/wiki/llm-client.js';
+/**
+ * Prompt the user for input via stdin.
+ */
+function prompt(question, hide = false) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        if (hide && process.stdin.isTTY) {
+            // Mask input for API keys
+            process.stdout.write(question);
+            let input = '';
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding('utf-8');
+            const onData = (char) => {
+                if (char === '\n' || char === '\r' || char === '\u0004') {
+                    process.stdin.setRawMode(false);
+                    process.stdin.removeListener('data', onData);
+                    process.stdout.write('\n');
+                    rl.close();
+                    resolve(input);
+                }
+                else if (char === '\u0003') {
+                    // Ctrl+C
+                    process.stdin.setRawMode(false);
+                    rl.close();
+                    process.exit(1);
+                }
+                else if (char === '\u007F' || char === '\b') {
+                    // Backspace
+                    if (input.length > 0) {
+                        input = input.slice(0, -1);
+                        process.stdout.write('\b \b');
+                    }
+                }
+                else {
+                    input += char;
+                    process.stdout.write('*');
+                }
+            };
+            process.stdin.on('data', onData);
+        }
+        else {
+            rl.question(question, (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+        }
+    });
+}
+export const wikiCommand = async (inputPath, options) => {
+    console.log('\n  GitNexus Wiki Generator\n');
+    // ── Resolve repo path ───────────────────────────────────────────────
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            console.log('  Error: Not inside a git repository\n');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    if (!isGitRepo(repoPath)) {
+        console.log('  Error: Not a git repository\n');
+        process.exitCode = 1;
+        return;
+    }
+    // ── Check for existing index ────────────────────────────────────────
+    const { storagePath, kuzuPath } = getStoragePaths(repoPath);
+    const meta = await loadMeta(storagePath);
+    if (!meta) {
+        console.log('  Error: No GitNexus index found.');
+        console.log('  Run `gitnexus analyze` first to index this repository.\n');
+        process.exitCode = 1;
+        return;
+    }
+    // ── Resolve LLM config (with interactive fallback) ─────────────────
+    // If --api-key was passed via CLI, save it immediately
+    if (options?.apiKey) {
+        const existing = await loadCLIConfig();
+        await saveCLIConfig({ ...existing, apiKey: options.apiKey });
+        console.log('  API key saved to ~/.gitnexus/config.json\n');
+    }
+    let llmConfig = await resolveLLMConfig({
+        model: options?.model,
+        baseUrl: options?.baseUrl,
+        apiKey: options?.apiKey,
+    });
+    if (!llmConfig.apiKey) {
+        if (!process.stdin.isTTY) {
+            console.log('  Error: No LLM API key found.');
+            console.log('  Set OPENAI_API_KEY or GITNEXUS_API_KEY environment variable,');
+            console.log('  or pass --api-key <key>.\n');
+            process.exitCode = 1;
+            return;
+        }
+        console.log('  No API key configured.\n');
+        console.log('  The wiki command requires an LLM API key (OpenAI-compatible).');
+        console.log('  You can also set OPENAI_API_KEY or GITNEXUS_API_KEY env var.\n');
+        const key = await prompt('  Enter your API key: ', true);
+        if (!key) {
+            console.log('\n  No key provided. Aborting.\n');
+            process.exitCode = 1;
+            return;
+        }
+        const save = await prompt('  Save key to ~/.gitnexus/config.json for future use? (Y/n): ');
+        if (!save || save.toLowerCase() === 'y' || save.toLowerCase() === 'yes') {
+            const existing = await loadCLIConfig();
+            await saveCLIConfig({ ...existing, apiKey: key });
+            console.log('  Key saved.\n');
+        }
+        else {
+            console.log('  Key will be used for this session only.\n');
+        }
+        llmConfig = { ...llmConfig, apiKey: key };
+    }
+    // ── Setup progress bar ──────────────────────────────────────────────
+    const bar = new cliProgress.SingleBar({
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    }, cliProgress.Presets.shades_grey);
+    bar.start(100, 0, { phase: 'Initializing...' });
+    const t0 = Date.now();
+    // ── Run generator ───────────────────────────────────────────────────
+    const wikiOptions = {
+        force: options?.force,
+        model: options?.model,
+        baseUrl: options?.baseUrl,
+    };
+    const generator = new WikiGenerator(repoPath, storagePath, kuzuPath, llmConfig, wikiOptions, (phase, percent, detail) => {
+        bar.update(percent, { phase: detail || phase });
+    });
+    try {
+        const result = await generator.run();
+        bar.update(100, { phase: 'Done' });
+        bar.stop();
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+        if (result.mode === 'up-to-date' && !options?.force) {
+            console.log('\n  Wiki is already up to date.');
+            console.log(`  ${path.join(storagePath, 'wiki')}\n`);
+            return;
+        }
+        const wikiDir = path.join(storagePath, 'wiki');
+        console.log(`\n  Wiki generated successfully (${elapsed}s)\n`);
+        console.log(`  Mode: ${result.mode}`);
+        console.log(`  Pages: ${result.pagesGenerated}`);
+        console.log(`  Output: ${wikiDir}`);
+        console.log(`  Viewer: ${path.join(wikiDir, 'index.html')}`);
+        if (result.failedModules && result.failedModules.length > 0) {
+            console.log(`\n  Failed modules (${result.failedModules.length}):`);
+            for (const mod of result.failedModules) {
+                console.log(`    - ${mod}`);
+            }
+            console.log('  Re-run to retry failed modules (pages will be regenerated).');
+        }
+        console.log('');
+    }
+    catch (err) {
+        bar.stop();
+        if (err.message?.includes('No source files')) {
+            console.log(`\n  ${err.message}\n`);
+        }
+        else if (err.message?.includes('API key') || err.message?.includes('API error')) {
+            console.log(`\n  LLM Error: ${err.message}\n`);
+        }
+        else {
+            console.log(`\n  Error: ${err.message}\n`);
+            if (process.env.DEBUG) {
+                console.error(err);
+            }
+        }
+        process.exitCode = 1;
+    }
+};

package/dist/core/augmentation/engine.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Augmentation Engine
+ *
+ * Lightweight, fast-path enrichment of search patterns with knowledge graph context.
+ * Designed to be called from platform hooks (Claude Code PreToolUse, Cursor beforeShellExecution)
+ * when an agent runs grep/glob/search.
+ *
+ * Performance target: <500ms cold start, <200ms warm.
+ *
+ * Design decisions:
+ * - Uses only BM25 search (no semantic/embedding) for speed
+ * - Clusters used internally for ranking, NEVER in output
+ * - Output is pure relationships: callers, callees, process participation
+ * - Graceful failure: any error → return empty string
+ */
+/**
+ * Augment a search pattern with knowledge graph context.
+ *
+ * 1. BM25 search for the pattern
+ * 2. For top matches, fetch callers/callees/processes
+ * 3. Rank by internal cluster cohesion (not exposed)
+ * 4. Format as structured text block
+ *
+ * Returns empty string on any error (graceful failure).
+ */
+export declare function augment(pattern: string, cwd?: string): Promise<string>;