@veewo/gitnexus 1.3.4

package/dist/cli/setup.js

@@ -0,0 +1,311 @@
+/**
+ * Setup Command
+ *
+ * One-time global MCP configuration writer.
+ * Detects installed AI editors and writes the appropriate MCP config
+ * so the GitNexus MCP server is available in all projects.
+ */
+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.
+ * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
+ */
+function getMcpEntry() {
+    if (process.platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'npx', '-y', 'gitnexus@latest', 'mcp'],
+        };
+    }
+    return {
+        command: 'npx',
+        args: ['-y', 'gitnexus@latest', 'mcp'],
+    };
+}
+/**
+ * Merge gitnexus entry into an existing MCP config JSON object.
+ * Returns the updated config.
+ */
+function mergeMcpConfig(existing) {
+    if (!existing || typeof existing !== 'object') {
+        existing = {};
+    }
+    if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+        existing.mcpServers = {};
+    }
+    existing.mcpServers.gitnexus = getMcpEntry();
+    return existing;
+}
+/**
+ * Try to read a JSON file, returning null if it doesn't exist or is invalid.
+ */
+async function readJsonFile(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write JSON to a file, creating parent directories if needed.
+ */
+async function writeJsonFile(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Check if a directory exists
+ */
+async function dirExists(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Editor-specific setup ─────────────────────────────────────────
+async function setupCursor(result) {
+    const cursorDir = path.join(os.homedir(), '.cursor');
+    if (!(await dirExists(cursorDir))) {
+        result.skipped.push('Cursor (not installed)');
+        return;
+    }
+    const mcpPath = path.join(cursorDir, 'mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        const updated = mergeMcpConfig(existing);
+        await writeJsonFile(mcpPath, updated);
+        result.configured.push('Cursor');
+    }
+    catch (err) {
+        result.errors.push(`Cursor: ${err.message}`);
+    }
+}
+async function setupClaudeCode(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    const hasClaude = await dirExists(claudeDir);
+    if (!hasClaude) {
+        result.skipped.push('Claude Code (not installed)');
+        return;
+    }
+    // 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 MCP:');
+    console.log('');
+    console.log('    claude mcp add gitnexus -- npx -y gitnexus mcp');
+    console.log('');
+    result.configured.push('Claude Code (MCP manual step printed)');
+}
+/**
+ * Install GitNexus global skills to ~/.agents/skills/gitnexus/
+ * Users can create editor-specific symlinks if they want.
+ */
+async function installGlobalAgentSkills(result) {
+    const skillsDir = path.join(os.homedir(), '.agents', 'skills', 'gitnexus');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Global agent skills (${installed.length} skills → ~/.agents/skills/gitnexus/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Global agent 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');
+    if (!(await dirExists(opencodeDir))) {
+        result.skipped.push('OpenCode (not installed)');
+        return;
+    }
+    const configPath = path.join(opencodeDir, 'config.json');
+    try {
+        const existing = await readJsonFile(configPath);
+        const config = existing || {};
+        if (!config.mcp)
+            config.mcp = {};
+        config.mcp.gitnexus = getMcpEntry();
+        await writeJsonFile(configPath, config);
+        result.configured.push('OpenCode');
+    }
+    catch (err) {
+        result.errors.push(`OpenCode: ${err.message}`);
+    }
+}
+// ─── Skill Installation ───────────────────────────────────────────
+const SKILL_NAMES = ['gitnexus-exploring', 'gitnexus-debugging', 'gitnexus-impact-analysis', 'gitnexus-refactoring', 'gitnexus-guide', 'gitnexus-cli'];
+/**
+ * Install GitNexus skills to a target directory.
+ * Each skill is installed as {targetDir}/{skillName}/SKILL.md.
+ *
+ * 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, skillName);
+        try {
+            // Try directory-based skill first (skills/{name}/SKILL.md)
+            const dirSource = path.join(skillsRoot, skillName);
+            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);
+        }
+    }
+}
+// ─── Main command ──────────────────────────────────────────────────
+export const setupCommand = async () => {
+    console.log('');
+    console.log('  GitNexus Setup');
+    console.log('  ==============');
+    console.log('');
+    // Ensure global directory exists
+    const globalDir = getGlobalDir();
+    await fs.mkdir(globalDir, { recursive: true });
+    const result = {
+        configured: [],
+        skipped: [],
+        errors: [],
+    };
+    // Detect and configure each editor's MCP
+    await setupCursor(result);
+    await setupClaudeCode(result);
+    await setupOpenCode(result);
+    // Install shared global skills once
+    await installGlobalAgentSkills(result);
+    // Optional Claude-specific hooks
+    await installClaudeCodeHooks(result);
+    // Print results
+    if (result.configured.length > 0) {
+        console.log('  Configured:');
+        for (const name of result.configured) {
+            console.log(`    + ${name}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log('');
+        console.log('  Skipped:');
+        for (const name of result.skipped) {
+            console.log(`    - ${name}`);
+        }
+    }
+    if (result.errors.length > 0) {
+        console.log('');
+        console.log('  Errors:');
+        for (const err of result.errors) {
+            console.log(`    ! ${err}`);
+        }
+    }
+    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');
+    console.log('    3. Open the repo in your editor — MCP is ready!');
+    console.log('');
+};

package/dist/cli/setup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/setup.test.js

@@ -0,0 +1,31 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+const execFileAsync = promisify(execFile);
+test('setup installs global skills under ~/.agents/skills/gitnexus', async () => {
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packageRoot = path.resolve(here, '..', '..');
+    const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
+    try {
+        await execFileAsync(process.execPath, [cliPath, 'setup'], {
+            cwd: packageRoot,
+            env: {
+                ...process.env,
+                HOME: fakeHome,
+                USERPROFILE: fakeHome,
+            },
+        });
+        const skillPath = path.join(fakeHome, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        await fs.access(skillPath);
+        assert.ok(true);
+    }
+    finally {
+        await fs.rm(fakeHome, { recursive: true, force: true });
+    }
+});

package/dist/cli/status.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Status Command
+ *
+ * Shows the indexing status of the current repository.
+ */
+export declare const statusCommand: () => Promise<void>;

package/dist/cli/status.js

@@ -0,0 +1,27 @@
+/**
+ * Status Command
+ *
+ * Shows the indexing status of the current repository.
+ */
+import { findRepo } from '../storage/repo-manager.js';
+import { getCurrentCommit, isGitRepo } from '../storage/git.js';
+export const statusCommand = async () => {
+    const cwd = process.cwd();
+    if (!isGitRepo(cwd)) {
+        console.log('Not a git repository.');
+        return;
+    }
+    const repo = await findRepo(cwd);
+    if (!repo) {
+        console.log('Repository not indexed.');
+        console.log('Run: gitnexus analyze');
+        return;
+    }
+    const currentCommit = getCurrentCommit(repo.repoPath);
+    const isUpToDate = currentCommit === repo.meta.lastCommit;
+    console.log(`Repository: ${repo.repoPath}`);
+    console.log(`Indexed: ${new Date(repo.meta.indexedAt).toLocaleString()}`);
+    console.log(`Indexed commit: ${repo.meta.lastCommit?.slice(0, 7)}`);
+    console.log(`Current commit: ${currentCommit?.slice(0, 7)}`);
+    console.log(`Status: ${isUpToDate ? '✅ up-to-date' : '⚠️ stale (re-run gitnexus analyze)'}`);
+};

package/dist/cli/tool.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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;
+    uid?: string;
+    file?: string;
+    minConfidence?: string;
+    includeTests?: boolean;
+}): Promise<void>;
+export declare function cypherCommand(query: string, options?: {
+    repo?: string;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -0,0 +1,94 @@
+/**
+ * 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,
+        target_uid: options?.uid,
+        file_path: options?.file,
+        direction: options?.direction || 'upstream',
+        maxDepth: options?.depth ? parseInt(options.depth) : undefined,
+        minConfidence: options?.minConfidence ? parseFloat(options.minConfidence) : 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/version.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/version.test.js

@@ -0,0 +1,19 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+const execFileAsync = promisify(execFile);
+test('cli --version matches package.json version', async () => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packageRoot = path.resolve(here, '..', '..');
+    const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+    const { stdout } = await execFileAsync(process.execPath, [cliPath, '--version'], {
+        cwd: packageRoot,
+    });
+    assert.equal(stdout.trim(), packageJson.version);
+});

package/dist/cli/wiki.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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;
+    concurrency?: string;
+    gist?: boolean;
+}
+export declare const wikiCommand: (inputPath?: string, options?: WikiCommandOptions) => Promise<void>;