gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/cli/list.js

@@ -12,11 +12,21 @@ export const listCommand = async () => {
         return;
     }
     console.log(`\n  Indexed Repositories (${entries.length})\n`);
+    // Count occurrences of each name so colliding entries can be
+    // disambiguated in the header (#829). Unique-name entries render
+    // identically to pre-#829 output; only collisions gain a suffix.
+    const nameCounts = new Map();
+    for (const e of entries) {
+        const key = e.name.toLowerCase();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
     for (const entry of entries) {
         const indexedDate = new Date(entry.indexedAt).toLocaleString();
         const stats = entry.stats || {};
         const commitShort = entry.lastCommit?.slice(0, 7) || 'unknown';
-        console.log(`  ${entry.name}`);
+        const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;
+        const header = hasCollision ? `${entry.name}  (${entry.path})` : entry.name;
+        console.log(`  ${header}`);
         console.log(`    Path:    ${entry.path}`);
         console.log(`    Indexed: ${indexedDate}`);
         console.log(`    Commit:  ${commitShort}`);

package/dist/cli/remove.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+export declare const removeCommand: (target: string, options?: {
+    force?: boolean;
+}) => Promise<void>;

package/dist/cli/remove.js

@@ -0,0 +1,99 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+import fs from 'fs/promises';
+import { readRegistry, resolveRegistryEntry, assertSafeStoragePath, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+export const removeCommand = async (target, options) => {
+    // Read the registry snapshot once and pass it to the resolver — this
+    // lets us render the "before" state in the dry-run path without a
+    // second disk read.
+    const entries = await readRegistry();
+    let entry;
+    try {
+        entry = resolveRegistryEntry(entries, target);
+    }
+    catch (err) {
+        if (err instanceof RegistryNotFoundError) {
+            // Idempotent: missing target is a no-op warning, not an error.
+            // The `availableNames` hint comes from the error itself so users
+            // can see what they might have meant.
+            console.warn(`Nothing to remove: ${err.message}`);
+            return;
+        }
+        if (err instanceof RegistryAmbiguousTargetError) {
+            // Duplicate aliases are allowed via --allow-duplicate-name (#829);
+            // refuse to guess which one the user meant — surface the full list
+            // and exit non-zero so scripts don't silently pick the wrong repo.
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Confirmation gate — same shape as `clean`. Default is a dry-run
+    // that describes what would be deleted; `--force` actually deletes.
+    if (!options?.force) {
+        console.log(`This will delete the GitNexus index for: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+        console.log('\nRun with --force to confirm deletion.');
+        return;
+    }
+    // Safety guard (#1003 review — @magyargergo): refuse to proceed if
+    // the registry entry's `storagePath` isn't the canonical
+    // `<entry.path>/.gitnexus` subfolder. `~/.gitnexus/registry.json` is
+    // user-writable, so a corrupted or hand-edited entry could point
+    // storagePath at the repo root, an empty string (→ cwd), a parent
+    // dir, or anywhere else; `fs.rm(recursive: true, force: true)` on
+    // any of those would be a runtime disaster. Bail before touching
+    // disk, with an actionable hint for recovering a broken registry.
+    try {
+        assertSafeStoragePath(entry);
+    }
+    catch (err) {
+        if (err instanceof UnsafeStoragePathError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Deletion order: fs.rm first, then unregister. If fs.rm fails mid-way,
+    // the registry entry stays so the user can retry. If fs.rm succeeds but
+    // unregister throws (e.g. ENOSPC on registry write), the entry becomes
+    // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
+    // next read, so the failure is self-healing.
+    try {
+        await fs.rm(entry.storagePath, { recursive: true, force: true });
+        await unregisterRepo(entry.path);
+        console.log(`Removed: ${entry.name}`);
+        console.log(`   Path:    ${entry.path}`);
+        console.log(`   Storage: ${entry.storagePath}`);
+    }
+    catch (err) {
+        console.error(`Failed to remove ${entry.name}:`, err);
+        process.exit(1);
+    }
+};

package/dist/cli/setup.js

@@ -12,6 +12,7 @@ import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { glob } from 'glob';
+import { parseTree, modify, applyEdits, parse as parseJsonc } from 'jsonc-parser';
 import { getGlobalDir } from '../storage/repo-manager.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -64,37 +65,61 @@ function getMcpEntry() {
     };
 }
 /**
- * Merge gitnexus entry into an existing MCP config JSON object.
- * Returns the updated config.
+ * OpenCode uses a different MCP format: { type: "local", command: [...] }
+ * where command is a flat array (command + args combined).
  */
-function mergeMcpConfig(existing) {
-    if (!existing || typeof existing !== 'object') {
-        existing = {};
+function getOpenCodeMcpEntry() {
+    const bin = resolveGitnexusBin();
+    if (bin) {
+        return { type: 'local', command: [bin, 'mcp'] };
     }
-    if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
-        existing.mcpServers = {};
+    if (process.platform === 'win32') {
+        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', 'gitnexus@latest', 'mcp'] };
     }
-    existing.mcpServers.gitnexus = getMcpEntry();
-    return existing;
+    return { type: 'local', command: ['npx', '-y', 'gitnexus@latest', 'mcp'] };
 }
 /**
- * Try to read a JSON file, returning null if it doesn't exist or is invalid.
+ * Detect indentation style from file content.
+ * Returns formatting options matching the file's existing style.
  */
-async function readJsonFile(filePath) {
-    try {
-        const raw = await fs.readFile(filePath, 'utf-8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
+function detectIndentation(raw) {
+    const firstIndented = raw.match(/^( +|\t)/m);
+    if (!firstIndented)
+        return { tabSize: 2, insertSpaces: true };
+    if (firstIndented[1] === '\t')
+        return { tabSize: 1, insertSpaces: false };
+    return { tabSize: firstIndented[1].length, insertSpaces: true };
 }
 /**
- * Write JSON to a file, creating parent directories if needed.
+ * Merge a key/value pair into a JSONC config file, preserving comments and formatting.
+ * If the file is genuinely corrupt (not valid JSONC), leaves it untouched.
  */
-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');
+async function mergeJsoncFile(filePath, keyPath, value) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        raw = '';
+    }
+    if (raw.trim().length === 0) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        const formattingOptions = { tabSize: 2, insertSpaces: true };
+        const edits = modify('{}', keyPath, value, { formattingOptions });
+        const result = applyEdits('{}', edits);
+        await fs.writeFile(filePath, result, 'utf-8');
+        return true;
+    }
+    const parseErrors = [];
+    const tree = parseTree(raw, parseErrors);
+    if (tree && tree.type === 'object' && parseErrors.length === 0) {
+        const formattingOptions = detectIndentation(raw);
+        const edits = modify(raw, keyPath, value, { formattingOptions });
+        const result = applyEdits(raw, edits);
+        await fs.writeFile(filePath, result, 'utf-8');
+        return true;
+    }
+    return false;
 }
 /**
  * Check if a directory exists
@@ -117,10 +142,13 @@ async function setupCursor(result) {
     }
     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');
+        const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+        if (ok) {
+            result.configured.push('Cursor');
+        }
+        else {
+            result.errors.push('Cursor: mcp.json is corrupt — skipping to preserve existing content');
+        }
     }
     catch (err) {
         result.errors.push(`Cursor: ${err.message}`);
@@ -135,10 +163,13 @@ async function setupClaudeCode(result) {
     // Claude Code stores MCP config in ~/.claude.json
     const mcpPath = path.join(os.homedir(), '.claude.json');
     try {
-        const existing = await readJsonFile(mcpPath);
-        const updated = mergeMcpConfig(existing);
-        await writeJsonFile(mcpPath, updated);
-        result.configured.push('Claude Code');
+        const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+        if (ok) {
+            result.configured.push('Claude Code');
+        }
+        else {
+            result.errors.push('Claude Code: .claude.json is corrupt — skipping to preserve existing content');
+        }
     }
     catch (err) {
         result.errors.push(`Claude Code: ${err.message}`);
@@ -162,9 +193,71 @@ async function installClaudeCodeSkills(result) {
         result.errors.push(`Claude Code skills: ${err.message}`);
     }
 }
+/**
+ * Check whether an event array already contains a gitnexus-hook entry.
+ */
+function hasGitnexusHook(hooksObj, eventName) {
+    const entries = hooksObj?.[eventName];
+    if (!Array.isArray(entries))
+        return false;
+    return entries.some((h) => Array.isArray(h.hooks) &&
+        h.hooks.some((hh) => typeof hh.command === 'string' && hh.command.includes('gitnexus-hook')));
+}
+/**
+ * Merge hook entries into a JSONC settings file, preserving comments and formatting.
+ * Uses chained modify()+applyEdits() calls to append to arrays without a full
+ * JSON.stringify roundtrip that would strip comments.
+ */
+async function mergeHooksJsonc(filePath, entries) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        raw = '';
+    }
+    if (raw.trim().length === 0) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        const hooks = {};
+        for (const { eventName, value } of entries) {
+            hooks[eventName] = [value];
+        }
+        const formattingOptions = { tabSize: 2, insertSpaces: true };
+        const edits = modify('{}', ['hooks'], hooks, { formattingOptions });
+        await fs.writeFile(filePath, applyEdits('{}', edits), 'utf-8');
+        return true;
+    }
+    const parseErrors = [];
+    const tree = parseTree(raw, parseErrors);
+    if (!tree || tree.type !== 'object' || parseErrors.length > 0) {
+        return false;
+    }
+    const formattingOptions = detectIndentation(raw);
+    let current = raw;
+    for (const { eventName, value } of entries) {
+        // Re-parse after each edit to get a fresh insertion index.
+        const currentTree = parseTree(current, []);
+        const hooksNode = currentTree?.children?.find((c) => c.type === 'property' && c.children?.[0]?.value === 'hooks');
+        const eventNode = hooksNode?.children?.[1]?.children?.find((c) => c.type === 'property' && c.children?.[0]?.value === eventName);
+        let insertIndex;
+        if (eventNode?.children?.[1] && Array.isArray(eventNode.children[1].children)) {
+            insertIndex = eventNode.children[1].children.length;
+        }
+        else {
+            insertIndex = 0;
+        }
+        const edits = modify(current, ['hooks', eventName, insertIndex], value, {
+            formattingOptions,
+        });
+        current = applyEdits(current, edits);
+    }
+    await fs.writeFile(filePath, current, 'utf-8');
+    return true;
+}
 /**
  * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
- * Merges hook config without overwriting existing hooks.
+ * Merges hook config without overwriting existing hooks, preserving
+ * comments and formatting in the JSONC file.
  */
 async function installClaudeCodeHooks(result) {
     const claudeDir = path.join(os.homedir(), '.claude');
@@ -181,8 +274,6 @@ async function installClaudeCodeHooks(result) {
         const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
         try {
             let content = await fs.readFile(src, 'utf-8');
-            // Inject resolved CLI path so the copied hook can find the CLI
-            // even when it's no longer inside the npm package tree
             const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
@@ -194,25 +285,62 @@ async function installClaudeCodeHooks(result) {
         }
         const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
         const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
-        // Merge hook config into ~/.claude/settings.json
-        const existing = (await readJsonFile(settingsPath)) || {};
-        if (!existing.hooks)
-            existing.hooks = {};
-        function ensureHookEntry(eventName, matcher, timeout, statusMessage) {
-            if (!existing.hooks[eventName])
-                existing.hooks[eventName] = [];
-            const hasHook = existing.hooks[eventName].some((h) => h.hooks?.some((hh) => hh.command?.includes('gitnexus-hook')));
-            if (!hasHook) {
-                existing.hooks[eventName].push({
-                    matcher,
-                    hooks: [{ type: 'command', command: hookCmd, timeout, statusMessage }],
-                });
+        // Check which hook events need entries (idempotent: skip if already registered)
+        const parsed = await (async () => {
+            try {
+                const r = await fs.readFile(settingsPath, 'utf-8');
+                return parseJsonc(r);
+            }
+            catch {
+                return null;
             }
+        })();
+        const hookEntries = [];
+        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
+        // Session context is delivered via CLAUDE.md / skills instead.
+        if (!hasGitnexusHook(parsed?.hooks, 'PreToolUse')) {
+            hookEntries.push({
+                eventName: 'PreToolUse',
+                value: {
+                    matcher: 'Grep|Glob|Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: hookCmd,
+                            timeout: 10,
+                            statusMessage: 'Enriching with GitNexus graph context...',
+                        },
+                    ],
+                },
+            });
+        }
+        if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse')) {
+            hookEntries.push({
+                eventName: 'PostToolUse',
+                value: {
+                    matcher: 'Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: hookCmd,
+                            timeout: 10,
+                            statusMessage: 'Checking GitNexus index freshness...',
+                        },
+                    ],
+                },
+            });
+        }
+        if (hookEntries.length === 0) {
+            result.configured.push('Claude Code hooks (already configured)');
+            return;
+        }
+        const ok = await mergeHooksJsonc(settingsPath, hookEntries);
+        if (ok) {
+            result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
+        }
+        else {
+            result.errors.push('Claude Code hooks: settings.json is corrupt — skipping to preserve existing content');
         }
-        ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10, 'Enriching with GitNexus graph context...');
-        ensureHookEntry('PostToolUse', 'Bash', 10, 'Checking GitNexus index freshness...');
-        await writeJsonFile(settingsPath, existing);
-        result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
     }
     catch (err) {
         result.errors.push(`Claude Code hooks: ${err.message}`);
@@ -226,13 +354,13 @@ async function setupOpenCode(result) {
     }
     const configPath = path.join(opencodeDir, 'opencode.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');
+        const ok = await mergeJsoncFile(configPath, ['mcp', 'gitnexus'], getOpenCodeMcpEntry());
+        if (ok) {
+            result.configured.push('OpenCode');
+        }
+        else {
+            result.errors.push('OpenCode: opencode.json is corrupt — skipping to preserve existing content');
+        }
     }
     catch (err) {
         result.errors.push(`OpenCode: ${err.message}`);

package/dist/cli/tool.d.ts

@@ -36,3 +36,8 @@ export declare function impactCommand(target: string, options?: {
 export declare function cypherCommand(query: string, options?: {
     repo?: string;
 }): Promise<void>;
+export declare function detectChangesCommand(options?: {
+    scope?: string;
+    baseRef?: string;
+    repo?: string;
+}): Promise<void>;

package/dist/cli/tool.js

@@ -124,3 +124,45 @@ export async function cypherCommand(query, options) {
     });
     output(result);
 }
+function formatDetectChangesResult(result) {
+    if (result?.error)
+        return `Error: ${result.error}`;
+    const summary = result?.summary || {};
+    if ((summary.changed_count || 0) === 0) {
+        return 'No changes detected.';
+    }
+    const lines = [];
+    lines.push(`Changes: ${summary.changed_files || 0} files, ${summary.changed_count || 0} symbols`);
+    lines.push(`Affected processes: ${summary.affected_count || 0}`);
+    lines.push(`Risk level: ${summary.risk_level || 'unknown'}`);
+    lines.push('');
+    const changed = result?.changed_symbols || [];
+    if (changed.length > 0) {
+        lines.push('Changed symbols:');
+        for (const symbol of changed.slice(0, 15)) {
+            lines.push(`  ${symbol.type} ${symbol.name} → ${symbol.filePath}`);
+        }
+        if (changed.length > 15) {
+            lines.push(`  ... and ${changed.length - 15} more`);
+        }
+        lines.push('');
+    }
+    const affected = result?.affected_processes || [];
+    if (affected.length > 0) {
+        lines.push('Affected execution flows:');
+        for (const processInfo of affected.slice(0, 10)) {
+            const steps = (processInfo.changed_steps || []).map((s) => s.symbol).join(', ');
+            lines.push(`  • ${processInfo.name} (${processInfo.step_count} steps) — changed: ${steps}`);
+        }
+    }
+    return lines.join('\n').trim();
+}
+export async function detectChangesCommand(options) {
+    const backend = await getBackend();
+    const result = await backend.callTool('detect_changes', {
+        scope: options?.scope || 'unstaged',
+        base_ref: options?.baseRef,
+        repo: options?.repo,
+    });
+    output(formatDetectChangesResult(result));
+}

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

@@ -19,6 +19,15 @@ export declare const loadIgnoreRules: (repoPath: string, options?: IgnoreOptions
  *
  * Returns an IgnoreLike object for glob's `ignore` option,
  * enabling directory-level pruning during traversal.
+ *
+ * Precedence (#771): user's `.gitnexusignore` negation patterns take
+ * priority over the hardcoded list, matching `.gitignore` semantics.
+ * An explicit `!pattern` rule unignores descendants even when they
+ * would otherwise be blocked by DEFAULT_IGNORE_LIST — UNLESS a more
+ * specific rule in the same file re-ignores a subset (e.g.
+ * `!__tests__/` paired with `__tests__/generated/` blocks the child
+ * while leaving the parent negated). Last-match-wins is enforced by
+ * consulting `ig.ignores(rel)` after `hasExplicitUnignore`.
  */
 export declare const createIgnoreFilter: (repoPath: string, options?: IgnoreOptions) => Promise<{
     ignored(p: Path): boolean;