gitnexus 1.6.3-rc.9 → 1.6.3

package/dist/cli/group.js

@@ -149,6 +149,79 @@ export function registerGroupCommands(program) {
             console.log(`\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`);
         }
     });
+    group
+        .command('impact <name>')
+        .description('Cross-repo impact for a symbol in one member repo of a group')
+        .requiredOption('--target <symbol>', 'Symbol or file name to analyze')
+        .requiredOption('--repo <groupPath>', 'Member path from group.yaml (e.g. app/backend), not the indexed repo name')
+        .option('--direction <dir>', 'upstream or downstream', 'upstream')
+        .option('--service <path>', 'Optional monorepo service directory prefix (path filter)')
+        .option('--subgroup <path>', 'Optional prefix limiting which group repos participate in cross fan-out')
+        .option('--max-depth <n>', 'Max graph traversal depth')
+        .option('--cross-depth <n>', 'Cross-repository hop depth')
+        .option('--min-confidence <n>', 'Minimum relation confidence (0–1)')
+        .option('--include-tests', 'Include test files in traversal', false)
+        .option('--timeout-ms <n>', 'Phase-1 local impact wall time in milliseconds')
+        .option('--json', 'JSON output')
+        .action(async (name, opts) => {
+        const { LocalBackend } = await import('../mcp/local/local-backend.js');
+        const backend = new LocalBackend();
+        try {
+            await backend.init();
+            const payload = {
+                name,
+                repo: opts.repo,
+                target: opts.target,
+                direction: opts.direction || 'upstream',
+            };
+            if (opts.service)
+                payload.service = opts.service;
+            if (opts.subgroup)
+                payload.subgroup = opts.subgroup;
+            if (opts.maxDepth !== undefined && opts.maxDepth !== '') {
+                const n = parseInt(String(opts.maxDepth), 10);
+                if (!Number.isNaN(n))
+                    payload.maxDepth = n;
+            }
+            if (opts.crossDepth !== undefined && opts.crossDepth !== '') {
+                const n = parseInt(String(opts.crossDepth), 10);
+                if (!Number.isNaN(n))
+                    payload.crossDepth = n;
+            }
+            if (opts.minConfidence !== undefined && opts.minConfidence !== '') {
+                const n = parseFloat(String(opts.minConfidence));
+                if (!Number.isNaN(n))
+                    payload.minConfidence = n;
+            }
+            if (opts.timeoutMs !== undefined && opts.timeoutMs !== '') {
+                const n = parseInt(String(opts.timeoutMs), 10);
+                if (!Number.isNaN(n))
+                    payload.timeoutMs = n;
+            }
+            if (opts.includeTests)
+                payload.includeTests = true;
+            const raw = await backend.getGroupService().groupImpact(payload);
+            if (raw && typeof raw === 'object' && 'error' in raw) {
+                console.error(String(raw.error));
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(raw, null, 2));
+            }
+            else {
+                const summary = raw?.summary;
+                const risk = raw?.risk;
+                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}`);
+                if (summary) {
+                    console.log(`  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}`);
+                }
+            }
+        }
+        finally {
+            await backend.dispose().catch(() => { });
+        }
+    });
     group
         .command('query <name> <query>')
         .description('Search execution flows across all repos in a group')

package/dist/cli/index-repo.js

@@ -11,7 +11,7 @@
 import path from 'path';
 import fs from 'fs/promises';
 import { getStoragePaths, loadMeta, addToGitignore, registerRepo, } from '../storage/repo-manager.js';
-import { getGitRoot, isGitRepo } from '../storage/git.js';
+import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
 export const indexCommand = async (inputPathParts, options) => {
     console.log('\n  GitNexus Index\n');
     const inputPath = inputPathParts?.length ? inputPathParts.join(' ') : undefined;
@@ -88,6 +88,13 @@ export const indexCommand = async (inputPathParts, options) => {
         };
     }
     // ── Register in global registry ───────────────────────────────────
+    // Refresh the on-disk meta with a freshly captured `remoteUrl` if
+    // it's missing, so an `index` of an older `.gitnexus/` still gets
+    // sibling-clone fingerprinting on subsequent use without forcing a
+    // full re-analyze.
+    if (!meta.remoteUrl && isGitRepo(repoPath)) {
+        meta.remoteUrl = getRemoteUrl(repoPath);
+    }
     await registerRepo(repoPath, meta);
     await addToGitignore(repoPath);
     const projectName = path.basename(repoPath);

package/dist/cli/index.js

@@ -18,12 +18,23 @@ program
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+    .option('--drop-embeddings', 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
+    'preserves any embeddings already present in the index.')
     .option('--skills', 'Generate repo-specific skill files from detected communities')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-git', 'Index a folder without requiring a .git directory')
+    .option('--name <alias>', 'Register this repo under a custom name in ~/.gitnexus/registry.json ' +
+    '(disambiguates repos whose paths share a basename, e.g. two different .../app folders)')
+    .option('--allow-duplicate-name', 'Register this repo even if another path already uses the same --name alias. ' +
+    'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
-    .addHelpText('after', '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)')
+    .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
+    .addHelpText('after', '\nEnvironment variables:\n' +
+    '  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n' +
+    '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
+    '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +
+    '     `!__tests__/` to index a directory that is auto-filtered by default (#771).')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 program
     .command('index [path...]')
@@ -55,6 +66,12 @@ program
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
+program
+    .command('remove <target>')
+    .description('Delete the GitNexus index for a registered repo (by alias, name, or absolute path). ' +
+    'Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(createLazyAction(() => import('./remove.js'), 'removeCommand'));
 program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')
@@ -107,6 +124,14 @@ program
     .description('Execute raw Cypher query against the knowledge graph')
     .option('-r, --repo <name>', 'Target repository')
     .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
+program
+    .command('detect-changes')
+    .alias('detect_changes')
+    .description('Map git diff hunks to indexed symbols and affected execution flows')
+    .option('-s, --scope <scope>', 'What to analyze: unstaged, staged, all, or compare', 'unstaged')
+    .option('-b, --base-ref <ref>', 'Branch/commit for compare scope (e.g. main)')
+    .option('-r, --repo <name>', 'Target repository')
+    .action(createLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')

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