@veewo/gitnexus 1.3.4

package/dist/cli/wiki.js

@@ -0,0 +1,361 @@
+/**
+ * Wiki Command
+ *
+ * Generates repository documentation from the knowledge graph.
+ * Usage: gitnexus wiki [path] [options]
+ */
+import path from 'path';
+import readline from 'readline';
+import { execSync } from 'child_process';
+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) ─────────────────
+    // Save any CLI overrides immediately
+    if (options?.apiKey || options?.model || options?.baseUrl) {
+        const existing = await loadCLIConfig();
+        const updates = {};
+        if (options.apiKey)
+            updates.apiKey = options.apiKey;
+        if (options.model)
+            updates.model = options.model;
+        if (options.baseUrl)
+            updates.baseUrl = options.baseUrl;
+        await saveCLIConfig({ ...existing, ...updates });
+        console.log('  Config saved to ~/.gitnexus/config.json\n');
+    }
+    const savedConfig = await loadCLIConfig();
+    const hasSavedConfig = !!(savedConfig.apiKey && savedConfig.baseUrl);
+    const hasCLIOverrides = !!(options?.apiKey || options?.model || options?.baseUrl);
+    let llmConfig = await resolveLLMConfig({
+        model: options?.model,
+        baseUrl: options?.baseUrl,
+        apiKey: options?.apiKey,
+    });
+    // Run interactive setup if no saved config and no CLI flags provided
+    // (even if env vars exist — let user explicitly choose their provider)
+    if (!hasSavedConfig && !hasCLIOverrides) {
+        if (!process.stdin.isTTY) {
+            if (!llmConfig.apiKey) {
+                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;
+            }
+            // Non-interactive with env var — just use it
+        }
+        else {
+            console.log('  No LLM configured. Let\'s set it up.\n');
+            console.log('  Supports OpenAI, OpenRouter, or any OpenAI-compatible API.\n');
+            // Provider selection
+            console.log('  [1] OpenAI (api.openai.com)');
+            console.log('  [2] OpenRouter (openrouter.ai)');
+            console.log('  [3] Custom endpoint\n');
+            const choice = await prompt('  Select provider (1/2/3): ');
+            let baseUrl;
+            let defaultModel;
+            if (choice === '2') {
+                baseUrl = 'https://openrouter.ai/api/v1';
+                defaultModel = 'minimax/minimax-m2.5';
+            }
+            else if (choice === '3') {
+                baseUrl = await prompt('  Base URL (e.g. http://localhost:11434/v1): ');
+                if (!baseUrl) {
+                    console.log('\n  No URL provided. Aborting.\n');
+                    process.exitCode = 1;
+                    return;
+                }
+                defaultModel = 'gpt-4o-mini';
+            }
+            else {
+                baseUrl = 'https://api.openai.com/v1';
+                defaultModel = 'gpt-4o-mini';
+            }
+            // Model
+            const modelInput = await prompt(`  Model (default: ${defaultModel}): `);
+            const model = modelInput || defaultModel;
+            // API key — pre-fill hint if env var exists
+            const envKey = process.env.GITNEXUS_API_KEY || process.env.OPENAI_API_KEY || '';
+            let key;
+            if (envKey) {
+                const masked = envKey.slice(0, 6) + '...' + envKey.slice(-4);
+                const useEnv = await prompt(`  Use existing env key (${masked})? (Y/n): `);
+                if (!useEnv || useEnv.toLowerCase() === 'y' || useEnv.toLowerCase() === 'yes') {
+                    key = envKey;
+                }
+                else {
+                    key = await prompt('  API key: ', true);
+                }
+            }
+            else {
+                key = await prompt('  API key: ', true);
+            }
+            if (!key) {
+                console.log('\n  No key provided. Aborting.\n');
+                process.exitCode = 1;
+                return;
+            }
+            // Save
+            await saveCLIConfig({ apiKey: key, baseUrl, model });
+            console.log('  Config saved to ~/.gitnexus/config.json\n');
+            llmConfig = { ...llmConfig, apiKey: key, baseUrl, model };
+        }
+    }
+    // ── Setup progress bar with elapsed timer ──────────────────────────
+    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();
+    let lastPhase = '';
+    let phaseStart = t0;
+    // Tick elapsed time every second while stuck on the same phase
+    const elapsedTimer = setInterval(() => {
+        if (lastPhase) {
+            const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+            if (elapsed >= 3) {
+                bar.update({ phase: `${lastPhase} (${elapsed}s)` });
+            }
+        }
+    }, 1000);
+    // ── Run generator ───────────────────────────────────────────────────
+    const wikiOptions = {
+        force: options?.force,
+        model: options?.model,
+        baseUrl: options?.baseUrl,
+        concurrency: options?.concurrency ? parseInt(options.concurrency, 10) : undefined,
+    };
+    const generator = new WikiGenerator(repoPath, storagePath, kuzuPath, llmConfig, wikiOptions, (phase, percent, detail) => {
+        const label = detail || phase;
+        if (label !== lastPhase) {
+            lastPhase = label;
+            phaseStart = Date.now();
+        }
+        bar.update(percent, { phase: label });
+    });
+    try {
+        const result = await generator.run();
+        clearInterval(elapsedTimer);
+        bar.update(100, { phase: 'Done' });
+        bar.stop();
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+        const wikiDir = path.join(storagePath, 'wiki');
+        const viewerPath = path.join(wikiDir, 'index.html');
+        if (result.mode === 'up-to-date' && !options?.force) {
+            console.log('\n  Wiki is already up to date.');
+            console.log(`  Viewer: ${viewerPath}\n`);
+            await maybePublishGist(viewerPath, options?.gist);
+            return;
+        }
+        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: ${viewerPath}`);
+        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('');
+        await maybePublishGist(viewerPath, options?.gist);
+    }
+    catch (err) {
+        clearInterval(elapsedTimer);
+        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`);
+            // Offer to reconfigure on auth-related failures
+            const isAuthError = err.message?.includes('401') || err.message?.includes('403')
+                || err.message?.includes('502') || err.message?.includes('authenticate')
+                || err.message?.includes('Unauthorized');
+            if (isAuthError && process.stdin.isTTY) {
+                const answer = await new Promise((resolve) => {
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                    rl.question('  Reconfigure LLM settings? (Y/n): ', (ans) => { rl.close(); resolve(ans.trim().toLowerCase()); });
+                });
+                if (!answer || answer === 'y' || answer === 'yes') {
+                    // Clear saved config so next run triggers interactive setup
+                    await saveCLIConfig({});
+                    console.log('  Config cleared. Run `gitnexus wiki` again to reconfigure.\n');
+                }
+            }
+        }
+        else {
+            console.log(`\n  Error: ${err.message}\n`);
+            if (process.env.DEBUG) {
+                console.error(err);
+            }
+        }
+        process.exitCode = 1;
+    }
+};
+// ─── Gist Publishing ───────────────────────────────────────────────────
+function hasGhCLI() {
+    try {
+        execSync('gh --version', { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function publishGist(htmlPath) {
+    try {
+        const output = execSync(`gh gist create "${htmlPath}" --desc "Repository Wiki — generated by GitNexus" --public`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        // gh gist create prints the gist URL as the last line
+        const lines = output.split('\n');
+        const gistUrl = lines.find(l => l.includes('gist.github.com')) || lines[lines.length - 1];
+        if (!gistUrl || !gistUrl.includes('gist.github.com'))
+            return null;
+        // Build a raw viewer URL via gist.githack.com
+        // gist URL format: https://gist.github.com/{user}/{id}
+        const match = gistUrl.match(/gist\.github\.com\/([^/]+)\/([a-f0-9]+)/);
+        let rawUrl = gistUrl;
+        if (match) {
+            rawUrl = `https://gistcdn.githack.com/${match[1]}/${match[2]}/raw/index.html`;
+        }
+        return { url: gistUrl.trim(), rawUrl };
+    }
+    catch {
+        return null;
+    }
+}
+async function maybePublishGist(htmlPath, gistFlag) {
+    if (gistFlag === false)
+        return;
+    // Check that the HTML file exists
+    try {
+        const fs = await import('fs/promises');
+        await fs.access(htmlPath);
+    }
+    catch {
+        return;
+    }
+    if (!hasGhCLI()) {
+        if (gistFlag) {
+            console.log('  GitHub CLI (gh) is not installed. Cannot publish gist.');
+            console.log('  Install it: https://cli.github.com\n');
+        }
+        return;
+    }
+    let shouldPublish = !!gistFlag;
+    if (!shouldPublish && process.stdin.isTTY) {
+        const answer = await new Promise((resolve) => {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            rl.question('  Publish wiki as a GitHub Gist for easy viewing? (Y/n): ', (ans) => {
+                rl.close();
+                resolve(ans.trim().toLowerCase());
+            });
+        });
+        shouldPublish = !answer || answer === 'y' || answer === 'yes';
+    }
+    if (!shouldPublish)
+        return;
+    console.log('\n  Publishing to GitHub Gist...');
+    const result = publishGist(htmlPath);
+    if (result) {
+        console.log(`  Gist:   ${result.url}`);
+        console.log(`  Viewer: ${result.rawUrl}\n`);
+    }
+    else {
+        console.log('  Failed to publish gist. Make sure `gh auth login` is configured.\n');
+    }
+}

package/dist/config/ignore-service.d.ts

@@ -0,0 +1 @@
+export declare const shouldIgnorePath: (filePath: string) => boolean;

package/dist/config/ignore-service.js

@@ -0,0 +1,210 @@
+const DEFAULT_IGNORE_LIST = new Set([
+    // Version Control
+    '.git',
+    '.svn',
+    '.hg',
+    '.bzr',
+    // IDEs & Editors
+    '.idea',
+    '.vscode',
+    '.vs',
+    '.eclipse',
+    '.settings',
+    '.DS_Store',
+    'Thumbs.db',
+    // Dependencies
+    'node_modules',
+    'bower_components',
+    'jspm_packages',
+    'vendor', // PHP/Go
+    // 'packages' removed - commonly used for monorepo source code (lerna, pnpm, yarn workspaces)
+    'venv',
+    '.venv',
+    'env',
+    '.env',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    'site-packages',
+    '.tox',
+    'eggs',
+    '.eggs',
+    'lib64',
+    'parts',
+    'sdist',
+    'wheels',
+    // Build Outputs
+    'dist',
+    'build',
+    'out',
+    'output',
+    'bin',
+    'obj',
+    'target', // Java/Rust
+    '.next',
+    '.nuxt',
+    '.output',
+    '.vercel',
+    '.netlify',
+    '.serverless',
+    '_build',
+    'public/build',
+    '.parcel-cache',
+    '.turbo',
+    '.svelte-kit',
+    // Test & Coverage
+    'coverage',
+    '.nyc_output',
+    'htmlcov',
+    '.coverage',
+    '__tests__', // Often just test files
+    '__mocks__',
+    '.jest',
+    // Logs & Temp
+    'logs',
+    'log',
+    'tmp',
+    'temp',
+    'cache',
+    '.cache',
+    '.tmp',
+    '.temp',
+    // Generated/Compiled
+    '.generated',
+    'generated',
+    'auto-generated',
+    '.terraform',
+    '.serverless',
+    // Documentation (optional - might want to keep)
+    // 'docs',
+    // 'documentation',
+    // Misc
+    '.husky',
+    '.github', // GitHub config, not code
+    '.circleci',
+    '.gitlab',
+    'fixtures', // Test fixtures
+    'snapshots', // Jest snapshots
+    '__snapshots__',
+]);
+const IGNORED_EXTENSIONS = new Set([
+    // Images
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp', '.bmp', '.tiff', '.tif',
+    '.psd', '.ai', '.sketch', '.fig', '.xd',
+    // Archives
+    '.zip', '.tar', '.gz', '.rar', '.7z', '.bz2', '.xz', '.tgz',
+    // Binary/Compiled
+    '.exe', '.dll', '.so', '.dylib', '.a', '.lib', '.o', '.obj',
+    '.class', '.jar', '.war', '.ear',
+    '.pyc', '.pyo', '.pyd',
+    '.beam', // Erlang
+    '.wasm', // WebAssembly - important!
+    '.node', // Native Node addons
+    // Documents
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+    '.odt', '.ods', '.odp',
+    // Media
+    '.mp4', '.mp3', '.wav', '.mov', '.avi', '.mkv', '.flv', '.wmv',
+    '.ogg', '.webm', '.flac', '.aac', '.m4a',
+    // Fonts
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    // Databases
+    '.db', '.sqlite', '.sqlite3', '.mdb', '.accdb',
+    // Minified/Bundled files
+    '.min.js', '.min.css', '.bundle.js', '.chunk.js',
+    // Source maps (debug files, not source)
+    '.map',
+    // Lock files (handled separately, but also here)
+    '.lock',
+    // Certificates & Keys (security - don't index!)
+    '.pem', '.key', '.crt', '.cer', '.p12', '.pfx',
+    // Data files (often large/binary)
+    '.csv', '.tsv', '.parquet', '.avro', '.feather',
+    '.npy', '.npz', '.pkl', '.pickle', '.h5', '.hdf5',
+    // Misc binary
+    '.bin', '.dat', '.data', '.raw',
+    '.iso', '.img', '.dmg',
+    // Unity metadata assets
+    '.meta',
+]);
+// Files to ignore by exact name
+const IGNORED_FILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'composer.lock',
+    'Gemfile.lock',
+    'poetry.lock',
+    'Cargo.lock',
+    'go.sum',
+    '.gitignore',
+    '.gitattributes',
+    '.npmrc',
+    '.yarnrc',
+    '.editorconfig',
+    '.prettierrc',
+    '.prettierignore',
+    '.eslintignore',
+    '.dockerignore',
+    'Thumbs.db',
+    '.DS_Store',
+    'LICENSE',
+    'LICENSE.md',
+    'LICENSE.txt',
+    'CHANGELOG.md',
+    'CHANGELOG',
+    'CONTRIBUTING.md',
+    'CODE_OF_CONDUCT.md',
+    'SECURITY.md',
+    '.env',
+    '.env.local',
+    '.env.development',
+    '.env.production',
+    '.env.test',
+    '.env.example',
+]);
+export const shouldIgnorePath = (filePath) => {
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const parts = normalizedPath.split('/');
+    const fileName = parts[parts.length - 1];
+    const fileNameLower = fileName.toLowerCase();
+    // Check if any path segment is in ignore list
+    for (const part of parts) {
+        if (DEFAULT_IGNORE_LIST.has(part)) {
+            return true;
+        }
+    }
+    // Check exact filename matches
+    if (IGNORED_FILES.has(fileName) || IGNORED_FILES.has(fileNameLower)) {
+        return true;
+    }
+    // Check extension
+    const lastDotIndex = fileNameLower.lastIndexOf('.');
+    if (lastDotIndex !== -1) {
+        const ext = fileNameLower.substring(lastDotIndex);
+        if (IGNORED_EXTENSIONS.has(ext))
+            return true;
+        // Handle compound extensions like .min.js, .bundle.js
+        const secondLastDot = fileNameLower.lastIndexOf('.', lastDotIndex - 1);
+        if (secondLastDot !== -1) {
+            const compoundExt = fileNameLower.substring(secondLastDot);
+            if (IGNORED_EXTENSIONS.has(compoundExt))
+                return true;
+        }
+    }
+    // Ignore hidden files (starting with .)
+    if (fileName.startsWith('.') && fileName !== '.') {
+        // But allow some important config files
+        const allowedDotFiles = ['.env', '.gitignore']; // Already in IGNORED_FILES, so this is redundant
+        // Actually, let's NOT ignore all dot files - many are important configs
+        // Just rely on the explicit lists above
+    }
+    // Ignore files that look like generated/bundled code
+    if (fileNameLower.includes('.bundle.') ||
+        fileNameLower.includes('.chunk.') ||
+        fileNameLower.includes('.generated.') ||
+        fileNameLower.endsWith('.d.ts')) { // TypeScript declaration files
+        return true;
+    }
+    return false;
+};

package/dist/config/supported-languages.d.ts

@@ -0,0 +1,12 @@
+export declare enum SupportedLanguages {
+    JavaScript = "javascript",
+    TypeScript = "typescript",
+    Python = "python",
+    Java = "java",
+    C = "c",
+    CPlusPlus = "cpp",
+    CSharp = "csharp",
+    Go = "go",
+    Rust = "rust",
+    PHP = "php"
+}

package/dist/config/supported-languages.js

@@ -0,0 +1,15 @@
+export var SupportedLanguages;
+(function (SupportedLanguages) {
+    SupportedLanguages["JavaScript"] = "javascript";
+    SupportedLanguages["TypeScript"] = "typescript";
+    SupportedLanguages["Python"] = "python";
+    SupportedLanguages["Java"] = "java";
+    SupportedLanguages["C"] = "c";
+    SupportedLanguages["CPlusPlus"] = "cpp";
+    SupportedLanguages["CSharp"] = "csharp";
+    SupportedLanguages["Go"] = "go";
+    SupportedLanguages["Rust"] = "rust";
+    SupportedLanguages["PHP"] = "php";
+    // Ruby = 'ruby',
+    // Swift = 'swift',
+})(SupportedLanguages || (SupportedLanguages = {}));

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>;