gitnexus 1.6.7-rc.7 → 1.6.7-rc.8

package/README.md

@@ -159,6 +159,7 @@ Your AI agent gets these tools automatically:
 
 ```bash
 gitnexus setup                   # Configure MCP for your editors (one-time)
+gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (add --force to apply)
 gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
@@ -196,6 +197,8 @@ gitnexus group query <name> <q>  # Search execution flows across all repos in a
 gitnexus group status <name>     # Check staleness of repos in a group
 ```
 
+> **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
+
 ## Remote Embeddings
 
 Set these env vars to use a remote OpenAI-compatible `/v1/embeddings` endpoint instead of the local model:

package/dist/cli/editor-targets.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Editor targets — the single source of truth for *where* GitNexus writes its
+ * per-editor configuration and *how* its entries are identified.
+ *
+ * `setup` (writes these) and `uninstall` (removes them) both consume this
+ * module so the two stay structurally in lock-step: add or change a target
+ * here and both sides follow. This is declarative metadata only — file
+ * locations, JSON key paths, hook event names, command needles, and script
+ * directories, plus the shared `detectIndentation` formatting helper. The
+ * format-specific read/write logic (JSONC merge, TOML upsert, OpenCode's flat
+ * command array, Gemini's hook schema) deliberately stays in setup.ts /
+ * uninstall.ts.
+ *
+ * The `setup → uninstall` round-trip integration test verifies the two
+ * implementations remain behaviourally symmetrical on top of this shared
+ * structure.
+ */
+export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codex';
+/** An editor whose MCP config is a JSONC document (server keyed by name). */
+export interface McpJsoncTarget {
+    id: EditorId;
+    label: string;
+    /** Absolute path to the editor's MCP config file. */
+    file: string;
+    /**
+     * JSON path of the gitnexus server entry within that file. Typed as
+     * `string[]` (all our keys are object keys) so it satisfies both setup's
+     * `mergeJsoncFile(string[])` and uninstall's `removeJsoncKey(JSONPath)`
+     * without either side needing a cast.
+     */
+    keyPath: string[];
+}
+/** Codex stores MCP config as a TOML table, not JSONC. */
+export interface CodexMcpTarget {
+    id: 'codex';
+    label: string;
+    /** Absolute path to ~/.codex/config.toml. */
+    configFile: string;
+    /** The TOML table header (without brackets) setup writes / uninstall strips. */
+    tomlSection: string;
+}
+export interface SkillTarget {
+    id: EditorId;
+    label: string;
+    /** Absolute path to the editor's skills directory. */
+    dir: string;
+}
+export interface HookTarget {
+    id: EditorId;
+    label: string;
+    /** Absolute path to the editor's settings file (JSONC). */
+    settingsFile: string;
+    /** Hook event arrays that may hold a gitnexus entry. */
+    events: string[];
+    /** Substring identifying the gitnexus command within a hook entry. */
+    needle: string;
+    /** Absolute path to the bundled hook-script directory setup writes. */
+    scriptDir: string;
+}
+export interface EditorTargets {
+    /** JSONC-format MCP entries: Cursor, Claude Code, Antigravity, OpenCode. */
+    mcpJsonc: McpJsoncTarget[];
+    /** Codex MCP (TOML). */
+    codex: CodexMcpTarget;
+    /** Skill install directories, one per editor that supports skills. */
+    skills: SkillTarget[];
+    /** Hook registrations + their bundled script directories. */
+    hooks: HookTarget[];
+}
+/**
+ * Resolve all editor targets for the given home directory. Defaults to
+ * `os.homedir()`; call sites pass it through so tests can point HOME at a temp
+ * dir. Paths are computed at call time (not module load) so a test setting
+ * `process.env.HOME` before invoking sees the right locations.
+ */
+export declare function getEditorTargets(home?: string): EditorTargets;
+/** Look up a single JSONC MCP target by editor id (throws if unknown). */
+export declare function mcpTarget(id: EditorId, home?: string): McpJsoncTarget;
+/** Look up a single skill target by editor id (throws if unknown). */
+export declare function skillTarget(id: EditorId, home?: string): SkillTarget;
+/** Look up a single hook target by editor id (throws if unknown). */
+export declare function hookTarget(id: EditorId, home?: string): HookTarget;
+/**
+ * Detect indentation style from file content so JSONC edits preserve the file's
+ * existing formatting. Shared by setup (writes) and uninstall (removes).
+ */
+export declare function detectIndentation(raw: string): {
+    tabSize: number;
+    insertSpaces: boolean;
+};

package/dist/cli/editor-targets.js

@@ -0,0 +1,124 @@
+/**
+ * Editor targets — the single source of truth for *where* GitNexus writes its
+ * per-editor configuration and *how* its entries are identified.
+ *
+ * `setup` (writes these) and `uninstall` (removes them) both consume this
+ * module so the two stay structurally in lock-step: add or change a target
+ * here and both sides follow. This is declarative metadata only — file
+ * locations, JSON key paths, hook event names, command needles, and script
+ * directories, plus the shared `detectIndentation` formatting helper. The
+ * format-specific read/write logic (JSONC merge, TOML upsert, OpenCode's flat
+ * command array, Gemini's hook schema) deliberately stays in setup.ts /
+ * uninstall.ts.
+ *
+ * The `setup → uninstall` round-trip integration test verifies the two
+ * implementations remain behaviourally symmetrical on top of this shared
+ * structure.
+ */
+import os from 'os';
+import path from 'path';
+/**
+ * Resolve all editor targets for the given home directory. Defaults to
+ * `os.homedir()`; call sites pass it through so tests can point HOME at a temp
+ * dir. Paths are computed at call time (not module load) so a test setting
+ * `process.env.HOME` before invoking sees the right locations.
+ */
+export function getEditorTargets(home = os.homedir()) {
+    const mcpJsonc = [
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            file: path.join(home, '.cursor', 'mcp.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
+        {
+            id: 'claude',
+            label: 'Claude Code',
+            file: path.join(home, '.claude.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
+        {
+            id: 'antigravity',
+            label: 'Antigravity',
+            file: path.join(home, '.gemini', 'antigravity', 'mcp_config.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
+        {
+            id: 'opencode',
+            label: 'OpenCode',
+            file: path.join(home, '.config', 'opencode', 'opencode.json'),
+            // OpenCode nests servers under `mcp`, not `mcpServers`.
+            keyPath: ['mcp', 'gitnexus'],
+        },
+    ];
+    const codex = {
+        id: 'codex',
+        label: 'Codex',
+        configFile: path.join(home, '.codex', 'config.toml'),
+        tomlSection: 'mcp_servers.gitnexus',
+    };
+    const skills = [
+        { id: 'claude', label: 'Claude Code', dir: path.join(home, '.claude', 'skills') },
+        {
+            id: 'antigravity',
+            label: 'Antigravity',
+            dir: path.join(home, '.gemini', 'antigravity', 'skills'),
+        },
+        { id: 'cursor', label: 'Cursor', dir: path.join(home, '.cursor', 'skills') },
+        { id: 'opencode', label: 'OpenCode', dir: path.join(home, '.config', 'opencode', 'skills') },
+        // Codex reads skills from ~/.agents/skills (not ~/.codex).
+        { id: 'codex', label: 'Codex', dir: path.join(home, '.agents', 'skills') },
+    ];
+    const hooks = [
+        {
+            id: 'claude',
+            label: 'Claude Code',
+            settingsFile: path.join(home, '.claude', 'settings.json'),
+            events: ['PreToolUse', 'PostToolUse'],
+            needle: 'gitnexus-hook',
+            scriptDir: path.join(home, '.claude', 'hooks', 'gitnexus'),
+        },
+        {
+            id: 'antigravity',
+            label: 'Antigravity',
+            settingsFile: path.join(home, '.gemini', 'settings.json'),
+            events: ['AfterTool'],
+            needle: 'gitnexus-antigravity-hook',
+            scriptDir: path.join(home, '.gemini', 'config', 'hooks', 'gitnexus'),
+        },
+    ];
+    return { mcpJsonc, codex, skills, hooks };
+}
+/** Look up a single JSONC MCP target by editor id (throws if unknown). */
+export function mcpTarget(id, home) {
+    const t = getEditorTargets(home).mcpJsonc.find((m) => m.id === id);
+    if (!t)
+        throw new Error(`No JSONC MCP target for editor "${id}"`);
+    return t;
+}
+/** Look up a single skill target by editor id (throws if unknown). */
+export function skillTarget(id, home) {
+    const t = getEditorTargets(home).skills.find((s) => s.id === id);
+    if (!t)
+        throw new Error(`No skill target for editor "${id}"`);
+    return t;
+}
+/** Look up a single hook target by editor id (throws if unknown). */
+export function hookTarget(id, home) {
+    const t = getEditorTargets(home).hooks.find((h) => h.id === id);
+    if (!t)
+        throw new Error(`No hook target for editor "${id}"`);
+    return t;
+}
+/**
+ * Detect indentation style from file content so JSONC edits preserve the file's
+ * existing formatting. Shared by setup (writes) and uninstall (removes).
+ */
+export 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 };
+}

package/dist/cli/help-i18n.js

@@ -9,6 +9,7 @@ const TITLE_KEYS = {
 const COMMAND_DESCRIPTION_KEYS = {
     '': 'help.description.root',
     setup: 'help.command.setup.description',
+    uninstall: 'help.command.uninstall.description',
     analyze: 'help.command.analyze.description',
     index: 'help.command.index.description',
     serve: 'help.command.serve.description',
@@ -65,6 +66,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'index|--allow-non-git': 'help.option.index.allowNonGit',
     'serve|-p, --port <port>': 'help.option.port',
     'serve|--host <host>': 'help.option.serve.host',
+    'uninstall|-f, --force': 'help.option.uninstall.force',
     'clean|-f, --force': 'help.option.force.confirmation',
     'clean|--all': 'help.option.clean.all',
     'clean|--lbug-sidecars': 'help.option.clean.lbugSidecars',

package/dist/cli/i18n/en.d.ts

@@ -99,6 +99,7 @@ export declare const en: {
     readonly 'help.option.help': "display help for command";
     readonly 'help.option.version': "output the version number";
     readonly 'help.command.setup.description': "One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex";
+    readonly 'help.command.uninstall.description': "Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors";
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
@@ -153,6 +154,7 @@ export declare const en: {
     readonly 'help.option.port': "Port number";
     readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
     readonly 'help.option.force.confirmation': "Skip confirmation prompt";
+    readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";
     readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";

package/dist/cli/i18n/en.js

@@ -99,6 +99,7 @@ export const en = {
     'help.option.help': 'display help for command',
     'help.option.version': 'output the version number',
     'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex',
+    'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors',
     'help.command.analyze.description': 'Index a repository (full analysis)',
     'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)',
     'help.command.serve.description': 'Start local HTTP server for web UI connection',
@@ -153,6 +154,7 @@ export const en = {
     'help.option.port': 'Port number',
     'help.option.serve.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)',
     'help.option.force.confirmation': 'Skip confirmation prompt',
+    'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',
     'help.option.clean.lbugSidecars': 'Clean quarantined LadybugDB missing-shadow WAL sidecars',
     'help.option.wiki.force': 'Force full regeneration even if up to date',

package/dist/cli/i18n/resources.d.ts

@@ -100,6 +100,7 @@ export declare const cliResources: {
         readonly 'help.option.help': "display help for command";
         readonly 'help.option.version': "output the version number";
         readonly 'help.command.setup.description': "One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex";
+        readonly 'help.command.uninstall.description': "Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors";
         readonly 'help.command.analyze.description': "Index a repository (full analysis)";
         readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
         readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
@@ -154,6 +155,7 @@ export declare const cliResources: {
         readonly 'help.option.port': "Port number";
         readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
         readonly 'help.option.force.confirmation': "Skip confirmation prompt";
+        readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
         readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
@@ -311,6 +313,7 @@ export declare const cliResources: {
         'help.option.help': string;
         'help.option.version': string;
         'help.command.setup.description': string;
+        'help.command.uninstall.description': string;
         'help.command.analyze.description': string;
         'help.command.index.description': string;
         'help.command.serve.description': string;
@@ -365,6 +368,7 @@ export declare const cliResources: {
         'help.option.port': string;
         'help.option.serve.host': string;
         'help.option.force.confirmation': string;
+        'help.option.uninstall.force': string;
         'help.option.clean.all': string;
         'help.option.clean.lbugSidecars': string;
         'help.option.wiki.force': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -99,6 +99,7 @@ export declare const zhCN: {
     'help.option.help': string;
     'help.option.version': string;
     'help.command.setup.description': string;
+    'help.command.uninstall.description': string;
     'help.command.analyze.description': string;
     'help.command.index.description': string;
     'help.command.serve.description': string;
@@ -153,6 +154,7 @@ export declare const zhCN: {
     'help.option.port': string;
     'help.option.serve.host': string;
     'help.option.force.confirmation': string;
+    'help.option.uninstall.force': string;
     'help.option.clean.all': string;
     'help.option.clean.lbugSidecars': string;
     'help.option.wiki.force': string;

package/dist/cli/i18n/zh-CN.js

@@ -99,6 +99,7 @@ export const zhCN = {
     'help.option.help': '显示命令帮助',
     'help.option.version': '输出版本号',
     'help.command.setup.description': '一次性设置：为 Cursor、Claude Code、OpenCode、Codex 配置 MCP',
+    'help.command.uninstall.description': '撤销 `setup`：从所有检测到的编辑器中移除 GitNexus 的 MCP 配置、技能和钩子',
     'help.command.analyze.description': '索引仓库（完整分析）',
     'help.command.index.description': '将现有 .gitnexus/ 文件夹注册到全局注册表（无需重新分析）',
     'help.command.serve.description': '启动供 Web UI 连接的本地 HTTP 服务器',
@@ -153,6 +154,7 @@ export const zhCN = {
     'help.option.port': '端口号',
     'help.option.serve.host': '绑定地址（默认：127.0.0.1；远程访问可用 0.0.0.0）',
     'help.option.force.confirmation': '跳过确认提示',
+    'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
     'help.option.clean.lbugSidecars': '清理已隔离的 LadybugDB missing-shadow WAL sidecar',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',

package/dist/cli/index.js

@@ -15,6 +15,11 @@ program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, Codex')
     .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
+program
+    .command('uninstall')
+    .description('Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors')
+    .option('-f, --force', 'Apply the changes (default is a dry-run preview)')
+    .action(createLazyAction(() => import('./uninstall.js'), 'uninstallCommand'));
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')

package/dist/cli/setup.js

@@ -14,6 +14,7 @@ import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { parseTree, modify, applyEdits, parse as parseJsonc } from 'jsonc-parser';
 import { getGlobalDir } from '../storage/repo-manager.js';
+import { getEditorTargets, mcpTarget, skillTarget, hookTarget, detectIndentation, } from './editor-targets.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
@@ -136,18 +137,6 @@ function getOpenCodeMcpEntry() {
     }
     return { type: 'local', command: ['npx', '-y', MCP_PINNED_REF, 'mcp'] };
 }
-/**
- * Detect indentation style from file content.
- * Returns formatting options matching the file's existing style.
- */
-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 };
-}
 /**
  * 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.
@@ -198,9 +187,9 @@ async function setupCursor(result) {
         result.skipped.push('Cursor (not installed)');
         return;
     }
-    const mcpPath = path.join(cursorDir, 'mcp.json');
+    const { file: mcpPath, keyPath } = mcpTarget('cursor');
     try {
-        const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+        const ok = await mergeJsoncFile(mcpPath, keyPath, getMcpEntry());
         if (ok) {
             result.configured.push('Cursor');
         }
@@ -219,9 +208,9 @@ async function setupClaudeCode(result) {
         return;
     }
     // Claude Code stores MCP config in ~/.claude.json
-    const mcpPath = path.join(os.homedir(), '.claude.json');
+    const { file: mcpPath, keyPath } = mcpTarget('claude');
     try {
-        const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+        const ok = await mergeJsoncFile(mcpPath, keyPath, getMcpEntry());
         if (ok) {
             result.configured.push('Claude Code');
         }
@@ -240,7 +229,7 @@ async function installClaudeCodeSkills(result) {
     const claudeDir = path.join(os.homedir(), '.claude');
     if (!(await dirExists(claudeDir)))
         return;
-    const skillsDir = path.join(claudeDir, 'skills');
+    const skillsDir = skillTarget('claude').dir;
     try {
         const installed = await installSkillsTo(skillsDir);
         if (installed.length > 0) {
@@ -357,11 +346,12 @@ async function installClaudeCodeHooks(result) {
     const claudeDir = path.join(os.homedir(), '.claude');
     if (!(await dirExists(claudeDir)))
         return;
-    const settingsPath = path.join(claudeDir, 'settings.json');
+    const claudeHook = hookTarget('claude');
+    const settingsPath = claudeHook.settingsFile;
     // 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');
+    const destHooksDir = claudeHook.scriptDir;
     try {
         await fs.mkdir(destHooksDir, { recursive: true });
         const src = path.join(pluginHooksPath, 'gitnexus-hook.cjs');
@@ -410,7 +400,7 @@ async function installClaudeCodeHooks(result) {
         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')) {
+        if (!hasGitnexusHook(parsed?.hooks, 'PreToolUse', claudeHook.needle)) {
             hookEntries.push({
                 eventName: 'PreToolUse',
                 value: {
@@ -426,7 +416,7 @@ async function installClaudeCodeHooks(result) {
                 },
             });
         }
-        if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse')) {
+        if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse', claudeHook.needle)) {
             hookEntries.push({
                 eventName: 'PostToolUse',
                 value: {
@@ -477,9 +467,9 @@ async function setupAntigravity(result) {
         result.skipped.push('Antigravity (not installed)');
         return;
     }
-    const mcpPath = path.join(antigravityDir, 'mcp_config.json');
+    const { file: mcpPath, keyPath } = mcpTarget('antigravity');
     try {
-        const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+        const ok = await mergeJsoncFile(mcpPath, keyPath, getMcpEntry());
         if (ok) {
             result.configured.push('Antigravity');
         }
@@ -500,7 +490,7 @@ async function installAntigravitySkills(result) {
     const antigravityDir = path.join(os.homedir(), '.gemini', 'antigravity');
     if (!(await dirExists(antigravityDir)))
         return;
-    const skillsDir = path.join(antigravityDir, 'skills');
+    const skillsDir = skillTarget('antigravity').dir;
     try {
         const installed = await installSkillsTo(skillsDir);
         if (installed.length > 0) {
@@ -526,9 +516,9 @@ async function installAntigravityHooks(result) {
     const antigravityDir = path.join(os.homedir(), '.gemini', 'antigravity');
     if (!(await dirExists(antigravityDir)))
         return;
-    const geminiDir = path.join(os.homedir(), '.gemini');
-    const settingsPath = path.join(geminiDir, 'settings.json');
-    const destHooksDir = path.join(geminiDir, 'config', 'hooks', 'gitnexus');
+    const antigravityHook = hookTarget('antigravity');
+    const settingsPath = antigravityHook.settingsFile;
+    const destHooksDir = antigravityHook.scriptDir;
     // The antigravity adapter shares its lock/probe helpers with the claude
     // adapter — same DB, same concurrency rules — so we reuse those CJS files
     // from gitnexus/hooks/claude/ rather than duplicating them.
@@ -585,7 +575,7 @@ async function installAntigravityHooks(result) {
             }
         })();
         const hookEntries = [];
-        if (!hasGitnexusHook(parsed?.hooks, 'AfterTool', 'gitnexus-antigravity-hook')) {
+        if (!hasGitnexusHook(parsed?.hooks, 'AfterTool', antigravityHook.needle)) {
             // Matcher follows the Gemini CLI built-in tool naming (snake_case).
             // search_file_content / glob cover content + filename search; run_shell_command
             // catches rg/grep invocations and the git commit family for stale-index hints.
@@ -629,9 +619,9 @@ async function setupOpenCode(result) {
         result.skipped.push('OpenCode (not installed)');
         return;
     }
-    const configPath = path.join(opencodeDir, 'opencode.json');
+    const { file: configPath, keyPath } = mcpTarget('opencode');
     try {
-        const ok = await mergeJsoncFile(configPath, ['mcp', 'gitnexus'], getOpenCodeMcpEntry());
+        const ok = await mergeJsoncFile(configPath, keyPath, getOpenCodeMcpEntry());
         if (ok) {
             result.configured.push('OpenCode');
         }
@@ -650,7 +640,7 @@ function getCodexMcpTomlSection() {
     const entry = getMcpEntry();
     const command = JSON.stringify(entry.command);
     const args = `[${entry.args.map((arg) => JSON.stringify(arg)).join(', ')}]`;
-    return `[mcp_servers.gitnexus]\ncommand = ${command}\nargs = ${args}\n`;
+    return `[${getEditorTargets().codex.tomlSection}]\ncommand = ${command}\nargs = ${args}\n`;
 }
 /**
  * Append GitNexus MCP server config to Codex's config.toml if missing.
@@ -663,7 +653,7 @@ async function upsertCodexConfigToml(configPath) {
     catch {
         existing = '';
     }
-    if (existing.includes('[mcp_servers.gitnexus]')) {
+    if (existing.includes(`[${getEditorTargets().codex.tomlSection}]`)) {
         return;
     }
     const section = getCodexMcpTomlSection();
@@ -690,7 +680,7 @@ async function setupCodex(result) {
         // Fallback for environments where `codex` binary isn't on PATH.
     }
     try {
-        const configPath = path.join(codexDir, 'config.toml');
+        const configPath = getEditorTargets().codex.configFile;
         await upsertCodexConfigToml(configPath);
         result.configured.push('Codex (MCP added to ~/.codex/config.toml)');
     }
@@ -794,7 +784,7 @@ async function installCursorSkills(result) {
     const cursorDir = path.join(os.homedir(), '.cursor');
     if (!(await dirExists(cursorDir)))
         return;
-    const skillsDir = path.join(cursorDir, 'skills');
+    const skillsDir = skillTarget('cursor').dir;
     try {
         const installed = await installSkillsTo(skillsDir);
         if (installed.length > 0) {
@@ -812,7 +802,7 @@ async function installOpenCodeSkills(result) {
     const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
     if (!(await dirExists(opencodeDir)))
         return;
-    const skillsDir = path.join(opencodeDir, 'skills');
+    const skillsDir = skillTarget('opencode').dir;
     try {
         const installed = await installSkillsTo(skillsDir);
         if (installed.length > 0) {
@@ -830,7 +820,7 @@ async function installCodexSkills(result) {
     const codexDir = path.join(os.homedir(), '.codex');
     if (!(await dirExists(codexDir)))
         return;
-    const skillsDir = path.join(os.homedir(), '.agents', 'skills');
+    const skillsDir = skillTarget('codex').dir;
     try {
         const installed = await installSkillsTo(skillsDir);
         if (installed.length > 0) {

package/dist/cli/uninstall.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Uninstall Command
+ *
+ * Reverses `gitnexus setup`: removes the GitNexus MCP server entries,
+ * skills, and hooks that setup writes into each detected AI editor's
+ * global configuration. The set of targets (paths, key paths, hook events,
+ * needles, script dirs) is shared with setup.ts via editor-targets.ts, so the
+ * two stay in lock-step.
+ *
+ * Surgical and idempotent: only gitnexus-owned keys/entries/dirs are
+ * removed. Unrelated user config (other MCP servers, other hooks, JSONC
+ * comments, indentation) is preserved. Files that are absent or that
+ * never contained a gitnexus entry are left untouched.
+ *
+ * Ownership is by name: skill directories are matched by the bundled gitnexus
+ * skill names, MCP entries by the `gitnexus` key, hooks by the gitnexus command
+ * needle. There is no per-install provenance marker yet (a user dir that
+ * happens to share a bundled skill name, or files a user added inside an
+ * installed skill dir, are matched purely by name) — which is why uninstall is
+ * a dry-run preview by default and prints the exact paths it will remove.
+ * Richer provenance tracking is a tracked follow-up.
+ *
+ * Intentionally NOT done here (printed as hints instead, since both are
+ * destructive in ways setup never caused):
+ *   - per-repo indexes      → `gitnexus clean --all`
+ *   - the global npm package → `npm uninstall -g gitnexus`
+ *
+ * Default is a dry-run preview; pass --force to apply.
+ */
+export declare const uninstallCommand: (options?: {
+    force?: boolean;
+}) => Promise<void>;

package/dist/cli/uninstall.js

@@ -0,0 +1,458 @@
+/**
+ * Uninstall Command
+ *
+ * Reverses `gitnexus setup`: removes the GitNexus MCP server entries,
+ * skills, and hooks that setup writes into each detected AI editor's
+ * global configuration. The set of targets (paths, key paths, hook events,
+ * needles, script dirs) is shared with setup.ts via editor-targets.ts, so the
+ * two stay in lock-step.
+ *
+ * Surgical and idempotent: only gitnexus-owned keys/entries/dirs are
+ * removed. Unrelated user config (other MCP servers, other hooks, JSONC
+ * comments, indentation) is preserved. Files that are absent or that
+ * never contained a gitnexus entry are left untouched.
+ *
+ * Ownership is by name: skill directories are matched by the bundled gitnexus
+ * skill names, MCP entries by the `gitnexus` key, hooks by the gitnexus command
+ * needle. There is no per-install provenance marker yet (a user dir that
+ * happens to share a bundled skill name, or files a user added inside an
+ * installed skill dir, are matched purely by name) — which is why uninstall is
+ * a dry-run preview by default and prints the exact paths it will remove.
+ * Richer provenance tracking is a tracked follow-up.
+ *
+ * Intentionally NOT done here (printed as hints instead, since both are
+ * destructive in ways setup never caused):
+ *   - per-repo indexes      → `gitnexus clean --all`
+ *   - the global npm package → `npm uninstall -g gitnexus`
+ *
+ * Default is a dry-run preview; pass --force to apply.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
+import { parseTree, modify, applyEdits, findNodeAtLocation, parse as parseJsonc, } from 'jsonc-parser';
+import { getEditorTargets, detectIndentation } from './editor-targets.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const execFileAsync = promisify(execFile);
+/**
+ * Remove a single key (by JSON path) from a JSONC file, preserving the
+ * surrounding comments and formatting. Returns:
+ *   - 'missing': file does not exist
+ *   - 'absent':  file exists but the key isn't there (nothing to do)
+ *   - 'corrupt': file isn't valid JSONC — left untouched on purpose
+ *   - 'removed': the key was present (and removed unless dryRun)
+ */
+async function removeJsoncKey(filePath, keyPath, dryRun) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return 'missing';
+    }
+    if (raw.trim().length === 0)
+        return 'absent';
+    const parseErrors = [];
+    const tree = parseTree(raw, parseErrors);
+    if (!tree || tree.type !== 'object' || parseErrors.length > 0)
+        return 'corrupt';
+    if (!findNodeAtLocation(tree, keyPath))
+        return 'absent';
+    if (!dryRun) {
+        const formattingOptions = detectIndentation(raw);
+        const edits = modify(raw, keyPath, undefined, { formattingOptions });
+        await fs.writeFile(filePath, applyEdits(raw, edits), 'utf-8');
+    }
+    return 'removed';
+}
+/**
+ * Remove the gitnexus hook command(s) — those whose command string contains
+ * `commandNeedle` — from the given `eventNames` arrays in a JSONC settings
+ * file. Mirrors the idempotency probes in setup.ts (hasGitnexusHook /
+ * geminiHasGitnexusHook). Returns how many event entries contained a gitnexus
+ * command.
+ *
+ * Removal is element-granular to honor the "other hooks are preserved"
+ * contract: only the matching command object inside an entry's `hooks[]` is
+ * deleted. The surrounding matcher entry is removed only when it becomes
+ * empty (i.e. it held nothing but gitnexus commands — which is exactly what
+ * setup creates). A user who hand-added their own command alongside ours
+ * keeps it. Edits are applied highest-index-first so earlier indices stay
+ * valid across edits.
+ */
+async function removeHookEntries(filePath, eventNames, commandNeedle, dryRun) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return { status: 'missing', count: 0 };
+    }
+    if (raw.trim().length === 0)
+        return { status: 'absent', count: 0 };
+    const parseErrors = [];
+    const tree = parseTree(raw, parseErrors);
+    if (!tree || tree.type !== 'object' || parseErrors.length > 0) {
+        return { status: 'corrupt', count: 0 };
+    }
+    const parsed = parseJsonc(raw);
+    const formattingOptions = detectIndentation(raw);
+    let current = raw;
+    let total = 0;
+    const isGitnexusHook = (hh) => typeof hh?.command === 'string' && hh.command.includes(commandNeedle);
+    for (const eventName of eventNames) {
+        const entries = parsed?.hooks?.[eventName];
+        if (!Array.isArray(entries))
+            continue;
+        // Walk entries high → low so removing a later one never shifts the
+        // index of an earlier one.
+        for (let entryIdx = entries.length - 1; entryIdx >= 0; entryIdx--) {
+            const entry = entries[entryIdx];
+            if (!Array.isArray(entry?.hooks))
+                continue;
+            const hookIdxs = [];
+            entry.hooks.forEach((hh, hi) => {
+                if (isGitnexusHook(hh))
+                    hookIdxs.push(hi);
+            });
+            if (hookIdxs.length === 0)
+                continue;
+            total += 1;
+            if (dryRun)
+                continue;
+            if (hookIdxs.length === entry.hooks.length) {
+                // The entry held only gitnexus command(s) — drop the whole entry.
+                const edits = modify(current, ['hooks', eventName, entryIdx], undefined, {
+                    formattingOptions,
+                });
+                current = applyEdits(current, edits);
+            }
+            else {
+                // The entry also holds user command(s) — delete only ours, keep
+                // the rest. Highest hook index first to keep lower indices valid.
+                for (const hi of hookIdxs.reverse()) {
+                    const edits = modify(current, ['hooks', eventName, entryIdx, 'hooks', hi], undefined, {
+                        formattingOptions,
+                    });
+                    current = applyEdits(current, edits);
+                }
+            }
+        }
+    }
+    if (total === 0)
+        return { status: 'absent', count: 0 };
+    if (!dryRun)
+        await fs.writeFile(filePath, current, 'utf-8');
+    return { status: 'removed', count: total };
+}
+/**
+ * Remove a directory tree if it exists. Returns true when something was
+ * (or would be) removed.
+ */
+async function removeDir(dirPath, dryRun) {
+    try {
+        await fs.access(dirPath);
+    }
+    catch {
+        return false;
+    }
+    if (!dryRun)
+        await fs.rm(dirPath, { recursive: true, force: true });
+    return true;
+}
+/**
+ * The exact set of skill directory names setup installs, derived from the
+ * bundled `skills/` source the same way installSkillsTo does (flat
+ * `{name}.md` and `{name}/SKILL.md` layouts). Deriving the set — rather
+ * than globbing `gitnexus-*` — ensures we never delete a user's own
+ * similarly-named skill folder.
+ */
+async function listGitnexusSkillNames() {
+    const skillsRoot = process.env.GITNEXUS_TEST_SKILLS_ROOT ?? path.join(__dirname, '..', '..', 'skills');
+    const names = new Set();
+    try {
+        const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                // Guard against a bare `.md` file: basename('.md', '.md') === '',
+                // which would later resolve to the skills dir itself and wipe it.
+                const base = path.basename(entry.name, '.md');
+                if (base)
+                    names.add(base);
+            }
+            else if (entry.isDirectory()) {
+                try {
+                    await fs.access(path.join(skillsRoot, entry.name, 'SKILL.md'));
+                    names.add(entry.name);
+                }
+                catch {
+                    // Not a skill directory — skip.
+                }
+            }
+        }
+    }
+    catch {
+        return [];
+    }
+    return [...names];
+}
+/**
+ * Remove the gitnexus skill directories from a target skills folder. Returns
+ * the absolute paths that were removed (or would be removed in dryRun) so the
+ * caller can show the user exactly what is affected.
+ */
+async function removeSkillsFrom(targetDir, skillNames, dryRun) {
+    const removed = [];
+    for (const name of skillNames) {
+        // Defense in depth: an empty/relative/absolute name would resolve back to
+        // targetDir (or escape it) and wipe unrelated content. Only act on a
+        // plain child directory name.
+        if (!name ||
+            name.includes('/') ||
+            name.includes('\\') ||
+            name === '.' ||
+            name === '..' ||
+            path.isAbsolute(name)) {
+            continue;
+        }
+        const dir = path.join(targetDir, name);
+        if (await removeDir(dir, dryRun))
+            removed.push(dir);
+    }
+    return removed;
+}
+/**
+ * Remove the `[mcp_servers.gitnexus]` table — and any of its descendant
+ * sub-tables (`[mcp_servers.gitnexus.env]`, `[[mcp_servers.gitnexus.x]]`) —
+ * from Codex's config.toml. Used only as a fallback when the `codex` binary
+ * isn't on PATH; the CLI's `codex mcp remove` is preferred.
+ *
+ * Hand-rolled (no TOML dependency), but careful about the cases a naive
+ * line-scan gets wrong:
+ *   - descendant sub-tables of the section are also removed (else they'd be
+ *     left dangling, referencing a server that no longer exists);
+ *   - `[...]`-shaped lines inside a multiline string (`"""`/`'''`) are NOT
+ *     treated as table headers;
+ *   - unrelated whitespace/formatting elsewhere in the file is left intact
+ *     (no global blank-line reflow). Only a single blank separator line
+ *     directly above the removed section is dropped.
+ */
+function stripTomlSection(raw, sectionName) {
+    const header = `[${sectionName}]`;
+    const childTable = `[${sectionName}.`;
+    const childArray = `[[${sectionName}.`;
+    // Capture group 1 is the bracket token only, so a trailing inline comment
+    // (`[mcp_servers.gitnexus] # note`) is stripped before classification —
+    // otherwise an exact `=== header` check fails and the section is left behind.
+    const headerRe = /^(\[\[?[^[\]]+\]\]?)\s*(#.*)?$/;
+    const isSectionHeader = (token) => token === header || token.startsWith(childTable) || token.startsWith(childArray);
+    // Return the multiline-string delimiter still OPEN at the end of `line`,
+    // given the state at its start (null = outside any multiline string). Scans
+    // left→right so the delimiter that actually opens first wins — a line with an
+    // odd count of BOTH `"""` and `'''` (e.g. `x = '''has """ inside`) no longer
+    // mis-picks the wrong delimiter and desyncs the scanner.
+    const multilineStateAfter = (line, startState) => {
+        let state = startState;
+        let i = 0;
+        while (i < line.length) {
+            if (state) {
+                const close = line.indexOf(state, i);
+                if (close === -1)
+                    return state; // still open at end of line
+                i = close + state.length;
+                state = null;
+            }
+            else {
+                const a = line.indexOf('"""', i);
+                const b = line.indexOf("'''", i);
+                if (a === -1 && b === -1)
+                    return null;
+                const useA = b === -1 || (a !== -1 && a < b);
+                state = useA ? '"""' : "'''";
+                i = (useA ? a : b) + 3;
+            }
+        }
+        return state;
+    };
+    const lines = raw.split(/\r?\n/);
+    const out = [];
+    let skipping = false;
+    let mlDelim = null;
+    for (const line of lines) {
+        if (mlDelim) {
+            // Inside a multiline string: brackets here are data, not headers.
+            mlDelim = multilineStateAfter(line, mlDelim);
+            if (!skipping)
+                out.push(line);
+            continue;
+        }
+        const trimmed = line.trim();
+        const headerMatch = trimmed.match(headerRe);
+        if (headerMatch) {
+            if (isSectionHeader(headerMatch[1])) {
+                // Drop a single blank separator line immediately above the section.
+                if (!skipping && out.length > 0 && out[out.length - 1].trim() === '')
+                    out.pop();
+                skipping = true;
+                continue;
+            }
+            // A non-descendant header ends the section.
+            skipping = false;
+            out.push(line);
+            continue;
+        }
+        // Track whether this (non-header) line opens a multiline string so a
+        // bracketed line inside it isn't mistaken for a header.
+        mlDelim = multilineStateAfter(line, null);
+        if (!skipping)
+            out.push(line);
+    }
+    // Preserve the file's line endings: a CRLF (Windows) config.toml should not
+    // be silently rewritten to LF. Rejoin with the dominant EOL of the input.
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    let result = out.join(eol);
+    if (!result.endsWith(eol))
+        result += eol;
+    return result;
+}
+async function uninstallCodex(result, dryRun, configPath, tomlSection) {
+    let raw;
+    try {
+        raw = await fs.readFile(configPath, 'utf-8');
+    }
+    catch {
+        result.skipped.push('Codex MCP (not configured)');
+        return;
+    }
+    if (!raw.includes(`[${tomlSection}]`)) {
+        result.skipped.push('Codex MCP (not configured)');
+        return;
+    }
+    if (dryRun) {
+        result.removed.push(`Codex MCP server — [${tomlSection}] in ${configPath}`);
+        return;
+    }
+    // Prefer the official CLI (mirrors setup's `codex mcp add`); fall back
+    // to editing config.toml directly when the binary isn't on PATH.
+    try {
+        await execFileAsync('codex', ['mcp', 'remove', 'gitnexus'], {
+            shell: process.platform === 'win32',
+            windowsHide: true,
+            timeout: 10000,
+        });
+        result.removed.push("Codex MCP server — via 'codex mcp remove gitnexus'");
+        return;
+    }
+    catch {
+        // Fall through to manual edit.
+    }
+    try {
+        await fs.writeFile(configPath, stripTomlSection(raw, tomlSection), 'utf-8');
+        result.removed.push(`Codex MCP server — [${tomlSection}] in ${configPath}`);
+    }
+    catch (err) {
+        result.errors.push(`Codex: ${err.message}`);
+    }
+}
+// ─── Main command ──────────────────────────────────────────────────
+export const uninstallCommand = async (options) => {
+    const dryRun = !options?.force;
+    const targets = getEditorTargets();
+    console.log('');
+    console.log('  GitNexus Uninstall');
+    console.log('  ==================');
+    console.log('');
+    if (dryRun) {
+        console.log('  Dry run — nothing will be changed. Re-run with --force to apply.');
+        console.log('');
+    }
+    const result = { removed: [], skipped: [], errors: [] };
+    // ─── MCP server entries (JSONC editors) ──────────────────────────
+    for (const target of targets.mcpJsonc) {
+        try {
+            const status = await removeJsoncKey(target.file, target.keyPath, dryRun);
+            if (status === 'removed')
+                result.removed.push(`${target.label} MCP server — ${target.keyPath.join('.')} in ${target.file}`);
+            else if (status === 'corrupt')
+                result.errors.push(`${target.label}: ${path.basename(target.file)} is corrupt — left untouched`);
+            else
+                result.skipped.push(`${target.label} MCP (not configured)`);
+        }
+        catch (err) {
+            result.errors.push(`${target.label}: ${err.message}`);
+        }
+    }
+    await uninstallCodex(result, dryRun, targets.codex.configFile, targets.codex.tomlSection);
+    // ─── Hooks ───────────────────────────────────────────────────────
+    for (const hook of targets.hooks) {
+        try {
+            const { status, count } = await removeHookEntries(hook.settingsFile, hook.events, hook.needle, dryRun);
+            if (status === 'removed')
+                result.removed.push(`${hook.label} hooks (${count}) — ${hook.settingsFile}`);
+            else if (status === 'corrupt')
+                result.errors.push(`${hook.label} hooks: ${path.basename(hook.settingsFile)} is corrupt — left untouched`);
+            // Don't delete the hook script while a registered entry may still point
+            // at it (corrupt = we couldn't parse/remove the entry) — that would
+            // leave the editor invoking a missing script on every matched tool call.
+            if (status !== 'corrupt' && (await removeDir(hook.scriptDir, dryRun)))
+                result.removed.push(`${hook.label} hook scripts — ${hook.scriptDir}`);
+        }
+        catch (err) {
+            result.errors.push(`${hook.label} hooks: ${err.message}`);
+        }
+    }
+    // ─── Skills ──────────────────────────────────────────────────────
+    // Skill directories are identified by the bundled gitnexus skill names; the
+    // exact paths are listed below so the user can see what will be removed.
+    const skillNames = await listGitnexusSkillNames();
+    for (const target of targets.skills) {
+        try {
+            const removedDirs = await removeSkillsFrom(target.dir, skillNames, dryRun);
+            for (const dir of removedDirs)
+                result.removed.push(`${target.label} skill — ${dir}`);
+        }
+        catch (err) {
+            result.errors.push(`${target.label} skills: ${err.message}`);
+        }
+    }
+    // ─── Report ──────────────────────────────────────────────────────
+    const verb = dryRun ? 'Would remove' : 'Removed';
+    if (result.removed.length > 0) {
+        console.log(`  ${verb}:`);
+        for (const name of result.removed)
+            console.log(`    - ${name}`);
+    }
+    else {
+        console.log('  Nothing to remove — GitNexus is not configured in any detected editor.');
+    }
+    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}`);
+        // Signal partial failure to callers/CI without aborting the remaining
+        // cleanup (which has already run by this point).
+        process.exitCode = 1;
+    }
+    console.log('');
+    console.log('  Note: skill directories are matched by bundled gitnexus skill name. If you');
+    console.log('  customized files inside an installed skill dir, back them up before --force.');
+    console.log('');
+    console.log('  Not removed automatically:');
+    console.log('    - Per-repo indexes — run: gitnexus clean --all');
+    console.log('    - The global npm package — run: npm uninstall -g gitnexus');
+    if (dryRun && result.removed.length > 0) {
+        console.log('');
+        console.log('  Re-run with --force to apply the changes above.');
+    }
+    console.log('');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.7-rc.7",
+  "version": "1.6.7-rc.8",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",