@veewo/gitnexus 1.3.6 → 1.3.8

package/README.md

@@ -24,11 +24,16 @@ npx gitnexus analyze
 
 That's it. This indexes the codebase, updates `AGENTS.md` / `CLAUDE.md` context files, and (when using project scope) installs repo-local agent skills.
 
-To configure MCP + skills, run `npx gitnexus setup` once (default global mode), or use `npx gitnexus setup --scope project` for project-local mode.
+To configure MCP + skills, run `npx gitnexus setup --agent <claude|opencode|codex>` once (default global mode), or add `--scope project` for project-local mode.
 
-`gitnexus setup` supports two scopes:
-- `global` (default): configures global editor MCP + installs global skills
-- `project`: writes repo-local `.mcp.json` + installs repo-local skills
+`gitnexus setup` requires an agent selection:
+- `--agent claude`: configure Claude MCP only
+- `--agent opencode`: configure OpenCode MCP only
+- `--agent codex`: configure Codex MCP only
+
+It also supports two scopes:
+- `global` (default): writes MCP to the selected agent's global config + installs global skills
+- `project`: writes MCP to the selected agent's project-local config + installs repo-local skills
 
 ## Team Deployment and Distribution
 
@@ -38,6 +43,7 @@ For small-team rollout (single stable channel only), follow:
 Key links:
 - [npm publish workflow](../.github/workflows/publish.yml)
 - [CLI package config](./package.json)
+- [Agent install + acceptance runbook](../INSTALL-GUIDE.md)
 
 ### Editor Support
 
@@ -64,7 +70,7 @@ If you prefer to configure manually instead of using `gitnexus setup`:
 ### Claude Code (full support — MCP + skills + hooks)
 
 ```bash
-claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+claude mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
 ```
 
 ### Cursor / Windsurf
@@ -76,7 +82,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "gitnexus": {
       "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "args": ["-y", "@veewo/gitnexus@latest", "mcp"]
     }
   }
 }
@@ -84,14 +90,14 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
 
 ### OpenCode
 
-Add to `~/.config/opencode/config.json`:
+Add to `~/.config/opencode/opencode.json`:
 
 ```json
 {
   "mcp": {
     "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "type": "local",
+      "command": ["npx", "-y", "@veewo/gitnexus@latest", "mcp"]
     }
   }
 }
@@ -100,7 +106,7 @@ Add to `~/.config/opencode/config.json`:
 ### Codex
 
 ```bash
-codex mcp add gitnexus -- npx -y gitnexus@latest mcp
+codex mcp add gitnexus -- npx -y @veewo/gitnexus@latest mcp
 ```
 
 ## How It Works
@@ -154,13 +160,14 @@ Your AI agent gets these tools automatically:
 ## CLI Commands
 
 ```bash
-gitnexus setup                    # Default: global MCP + global skills
-gitnexus setup --scope project    # Project-local MCP + project-local skills
+gitnexus setup --agent claude                     # Global setup for Claude
+gitnexus setup --agent codex                      # Global setup for Codex
+gitnexus setup --scope project --agent opencode   # Project-local setup for OpenCode
 gitnexus analyze [path]           # Index a repository (or update stale index)
 gitnexus analyze --force          # Force full re-index
 gitnexus analyze --embeddings     # Enable semantic embeddings (off by default)
 gitnexus analyze --scope-prefix Assets/NEON/Code --scope-prefix Packages/com.veewo.*  # Scoped multi-directory indexing
-gitnexus analyze --scope-manifest ./scope.txt --repo-alias neonspark-v1-subset         # Scoped indexing + stable repo alias
+gitnexus analyze --scope-manifest .gitnexus/sync-manifest.txt --repo-alias neonspark-v1-subset  # Scoped indexing + stable repo alias
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus list                    # List all indexed repositories
@@ -216,6 +223,7 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 Installation rules:
 
 - `gitnexus setup` controls skill scope:
+  - requires `--agent <claude|opencode|codex>`
   - default `global`: installs to `~/.agents/skills/gitnexus/`
   - `--scope project`: installs to `.agents/skills/gitnexus/` in current repo
 - `gitnexus analyze` always updates `AGENTS.md` / `CLAUDE.md`; skill install follows configured setup scope.

package/dist/cli/analyze-custom-modules-regression.test.d.ts

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

package/dist/cli/analyze-custom-modules-regression.test.js

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
+const FIXTURE_REPO = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../benchmarks/fixtures/unity-mini');
+async function copyFixtureRepo() {
+    const tmpRepo = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-custom-modules-'));
+    await fs.cp(FIXTURE_REPO, tmpRepo, { recursive: true });
+    await fs.mkdir(path.join(tmpRepo, '.gitnexus'), { recursive: true });
+    return tmpRepo;
+}
+test('pipeline mixed mode writes config module + auto fallback memberships', { timeout: 120_000 }, async () => {
+    const repoPath = await copyFixtureRepo();
+    const configPath = path.join(repoPath, '.gitnexus', 'modules.json');
+    await fs.writeFile(configPath, JSON.stringify({
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            {
+                name: 'Factory',
+                defaultPriority: 100,
+                rules: [
+                    {
+                        id: 'factory-file-rule',
+                        when: {
+                            all: [{ field: 'file.path', op: 'contains', value: 'MinionFactory.cs' }],
+                        },
+                    },
+                ],
+            },
+            {
+                name: 'Battle',
+                defaultPriority: 100,
+                rules: [],
+            },
+        ],
+    }), 'utf-8');
+    const result = await runPipelineFromRepo(repoPath, () => { }, { includeExtensions: ['.cs'] });
+    const communities = [...result.graph.iterNodes()].filter((n) => n.label === 'Community');
+    const memberships = [...result.graph.iterRelationships()].filter((r) => r.type === 'MEMBER_OF');
+    const commById = new Map(communities.map((c) => [c.id, c]));
+    const labels = communities.map((c) => String(c.properties.heuristicLabel || c.properties.name || c.id));
+    assert.ok(labels.includes('Factory'));
+    assert.ok(labels.includes('Battle'));
+    const createMembership = memberships.find((m) => m.sourceId.includes('MinionFactory.cs:Create'));
+    assert.ok(createMembership);
+    const targetCommunity = commById.get(createMembership.targetId);
+    assert.ok(targetCommunity);
+    assert.equal(String(targetCommunity.properties.heuristicLabel), 'Factory');
+    const uniquePerSymbol = new Set(memberships.map((m) => m.sourceId));
+    assert.equal(uniquePerSymbol.size, memberships.length);
+    const battleCommunity = communities.find((c) => String(c.properties.heuristicLabel) === 'Battle');
+    assert.ok(battleCommunity);
+    assert.ok(!memberships.some((m) => m.targetId === battleCommunity.id));
+    const membershipCommunities = new Set(memberships.map((m) => m.targetId));
+    const processCommunities = new Set((result.processResult?.processes || []).flatMap((p) => p.communities || []));
+    for (const processCommunity of processCommunities) {
+        assert.ok(membershipCommunities.has(processCommunity));
+    }
+});
+test('pipeline mixed + invalid modules.json fails fast', { timeout: 120_000 }, async () => {
+    const repoPath = await copyFixtureRepo();
+    const configPath = path.join(repoPath, '.gitnexus', 'modules.json');
+    await fs.writeFile(configPath, JSON.stringify({
+        version: 1,
+        mode: 'mixed',
+        modules: [
+            { name: 'Dup', defaultPriority: 100, rules: [] },
+            { name: 'Dup', defaultPriority: 100, rules: [] },
+        ],
+    }), 'utf-8');
+    await assert.rejects(runPipelineFromRepo(repoPath, () => { }, { includeExtensions: ['.cs'] }), /duplicate module name/i);
+});

package/dist/cli/analyze-modules-diagnostics.test.d.ts

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

package/dist/cli/analyze-modules-diagnostics.test.js

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { formatModuleDiagnostics } from './analyze.js';
+test('prints one-time fallback warning for mixed + missing modules.json', () => {
+    const lines = formatModuleDiagnostics({
+        mode: 'mixed',
+        usedFallbackAuto: true,
+        warnings: ['modules.json missing in mixed mode, fallback to auto'],
+        emptyModules: [],
+        configuredModuleCount: 0,
+        finalModuleCount: 3,
+    });
+    assert.ok(lines.some((line) => /fallback to auto/i.test(line)));
+});
+test('prints warning for empty modules', () => {
+    const lines = formatModuleDiagnostics({
+        mode: 'mixed',
+        usedFallbackAuto: false,
+        warnings: [],
+        emptyModules: ['Battle'],
+        configuredModuleCount: 1,
+        finalModuleCount: 2,
+    });
+    assert.ok(lines.some((line) => /empty module/i.test(line)));
+    assert.ok(lines.some((line) => /Battle/.test(line)));
+});
+test('README mentions modules.json mode semantics and fallback behavior', async () => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const readmePath = path.resolve(here, '../../README.md');
+    const readme = await fs.readFile(readmePath, 'utf-8');
+    assert.match(readme, /\.gitnexus\/modules\.json/);
+    assert.match(readme, /mixed.*fallback.*auto/i);
+});

package/dist/cli/index.js

@@ -59,8 +59,9 @@ program
     .version(resolveCliVersion());
 program
     .command('setup')
-    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')
+    .description('One-time setup: configure MCP for a selected coding agent (claude/opencode/codex)')
     .option('--scope <scope>', 'Install target: global (default) or project')
+    .option('--agent <agent>', 'Target coding agent: claude, opencode, or codex')
     .action(setupCommand);
 program
     .command('analyze [path]')
@@ -69,7 +70,7 @@ program
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
     .option('--extensions <list>', 'Comma-separated file extensions to include (e.g. .cs,.ts)')
     .option('--repo-alias <name>', 'Override indexed repository name with a stable alias')
-    .option('--scope-manifest <path>', 'Manifest file with scope rules (supports comments and * wildcard)')
+    .option('--scope-manifest <path>', 'Manifest file with scope rules (supports comments and * wildcard; recommended: .gitnexus/sync-manifest.txt)')
     .option('--scope-prefix <pathPrefix>', 'Add a scope path prefix rule (repeatable)', collectValues, [])
     .action(analyzeCommand);
 program

package/dist/cli/setup.d.ts

@@ -1,12 +1,13 @@
 /**
  * Setup Command
  *
- * One-time global MCP configuration writer.
- * Detects installed AI editors and writes the appropriate MCP config
- * so the GitNexus MCP server is available in all projects.
+ * One-time MCP configuration writer with explicit agent targeting.
+ * Configures only the selected coding agent's MCP entry
+ * in either global or project scope.
  */
 interface SetupOptions {
     scope?: string;
+    agent?: string;
 }
 export declare const setupCommand: (options?: SetupOptions) => Promise<void>;
 export {};

package/dist/cli/setup.js

@@ -1,11 +1,12 @@
 /**
  * Setup Command
  *
- * One-time global MCP configuration writer.
- * Detects installed AI editors and writes the appropriate MCP config
- * so the GitNexus MCP server is available in all projects.
+ * One-time MCP configuration writer with explicit agent targeting.
+ * Configures only the selected coding agent's MCP entry
+ * in either global or project scope.
  */
 import fs from 'fs/promises';
+import { readFileSync } from 'node:fs';
 import path from 'path';
 import os from 'os';
 import { execFile } from 'node:child_process';
@@ -16,6 +17,7 @@ import { getGitRoot } from '../storage/git.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
+const FALLBACK_MCP_PACKAGE = 'gitnexus@latest';
 function resolveSetupScope(rawScope) {
     if (!rawScope || rawScope.trim() === '')
         return 'global';
@@ -23,6 +25,34 @@ function resolveSetupScope(rawScope) {
         return rawScope;
     throw new Error(`Invalid --scope value "${rawScope}". Use "global" or "project".`);
 }
+function resolveSetupAgent(rawAgent) {
+    if (!rawAgent || rawAgent.trim() === '') {
+        throw new Error('Missing --agent. Use one of: claude, opencode, codex.');
+    }
+    if (rawAgent === 'claude' || rawAgent === 'opencode' || rawAgent === 'codex') {
+        return rawAgent;
+    }
+    throw new Error(`Invalid --agent value "${rawAgent}". Use "claude", "opencode", or "codex".`);
+}
+/**
+ * Resolve the package spec used by MCP commands.
+ * Defaults to gitnexus@latest when package metadata is unavailable.
+ */
+function resolveMcpPackageSpec() {
+    try {
+        const packageJsonPath = path.join(__dirname, '..', '..', 'package.json');
+        const raw = readFileSync(packageJsonPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.name === 'string' && parsed.name.trim().length > 0) {
+            return `${parsed.name}@latest`;
+        }
+    }
+    catch {
+        // Fallback keeps behavior for unusual runtimes.
+    }
+    return FALLBACK_MCP_PACKAGE;
+}
+const MCP_PACKAGE_SPEC = resolveMcpPackageSpec();
 /**
  * The MCP server entry for all editors.
  * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
@@ -31,12 +61,19 @@ function getMcpEntry() {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', 'gitnexus@latest', 'mcp'],
+            args: ['/c', 'npx', '-y', MCP_PACKAGE_SPEC, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', 'gitnexus@latest', 'mcp'],
+        args: ['-y', MCP_PACKAGE_SPEC, 'mcp'],
+    };
+}
+function getOpenCodeMcpEntry() {
+    const entry = getMcpEntry();
+    return {
+        type: 'local',
+        command: [entry.command, ...entry.args],
     };
 }
 /**
@@ -53,6 +90,20 @@ function mergeMcpConfig(existing) {
     existing.mcpServers.gitnexus = getMcpEntry();
     return existing;
 }
+/**
+ * Merge gitnexus entry into an OpenCode config JSON object.
+ * Returns the updated config.
+ */
+function mergeOpenCodeConfig(existing) {
+    if (!existing || typeof existing !== 'object') {
+        existing = {};
+    }
+    if (!existing.mcp || typeof existing.mcp !== 'object') {
+        existing.mcp = {};
+    }
+    existing.mcp.gitnexus = getOpenCodeMcpEntry();
+    return existing;
+}
 /**
  * Try to read a JSON file, returning null if it doesn't exist or is invalid.
  */
@@ -84,6 +135,53 @@ async function dirExists(dirPath) {
         return false;
     }
 }
+/**
+ * Check if a regular file exists.
+ */
+async function fileExists(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Escape a value for TOML string literals.
+ */
+function toTomlString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function buildCodexMcpTable() {
+    const entry = getMcpEntry();
+    return [
+        '[mcp_servers.gitnexus]',
+        `command = ${toTomlString(entry.command)}`,
+        `args = [${entry.args.map(toTomlString).join(', ')}]`,
+    ].join('\n');
+}
+function mergeCodexConfig(existingRaw) {
+    const table = buildCodexMcpTable();
+    const normalized = existingRaw.replace(/\r\n/g, '\n');
+    const tablePattern = /\[mcp_servers\.gitnexus\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/m;
+    if (tablePattern.test(normalized)) {
+        return normalized.replace(tablePattern, table).trimEnd() + '\n';
+    }
+    const trimmed = normalized.trimEnd();
+    if (trimmed.length === 0)
+        return `${table}\n`;
+    return `${trimmed}\n\n${table}\n`;
+}
+async function resolveOpenCodeConfigPath(opencodeDir) {
+    const preferredPath = path.join(opencodeDir, 'opencode.json');
+    const legacyPath = path.join(opencodeDir, 'config.json');
+    if (await fileExists(preferredPath))
+        return preferredPath;
+    if (await fileExists(legacyPath))
+        return legacyPath;
+    return preferredPath;
+}
 // ─── Editor-specific setup ─────────────────────────────────────────
 async function setupCursor(result) {
     const cursorDir = path.join(os.homedir(), '.cursor');
@@ -113,7 +211,7 @@ async function setupClaudeCode(result) {
     console.log('');
     console.log('  Claude Code detected. Run this command to add GitNexus MCP:');
     console.log('');
-    console.log('    claude mcp add gitnexus -- npx -y gitnexus mcp');
+    console.log(`    claude mcp add gitnexus -- npx -y ${MCP_PACKAGE_SPEC} mcp`);
     console.log('');
     result.configured.push('Claude Code (MCP manual step printed)');
 }
@@ -204,15 +302,12 @@ async function setupOpenCode(result) {
         result.skipped.push('OpenCode (not installed)');
         return;
     }
-    const configPath = path.join(opencodeDir, 'config.json');
+    const configPath = await resolveOpenCodeConfigPath(opencodeDir);
     try {
         const existing = await readJsonFile(configPath);
-        const config = existing || {};
-        if (!config.mcp)
-            config.mcp = {};
-        config.mcp.gitnexus = getMcpEntry();
+        const config = mergeOpenCodeConfig(existing);
         await writeJsonFile(configPath, config);
-        result.configured.push('OpenCode');
+        result.configured.push(`OpenCode (${path.basename(configPath)})`);
     }
     catch (err) {
         result.errors.push(`OpenCode: ${err.message}`);
@@ -244,6 +339,38 @@ async function setupProjectMcp(repoRoot, result) {
         result.errors.push(`Project MCP: ${err.message}`);
     }
 }
+async function setupProjectCodex(repoRoot, result) {
+    const codexConfigPath = path.join(repoRoot, '.codex', 'config.toml');
+    try {
+        let existingRaw = '';
+        try {
+            existingRaw = await fs.readFile(codexConfigPath, 'utf-8');
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                throw err;
+        }
+        const merged = mergeCodexConfig(existingRaw);
+        await fs.mkdir(path.dirname(codexConfigPath), { recursive: true });
+        await fs.writeFile(codexConfigPath, merged, 'utf-8');
+        result.configured.push(`Project Codex MCP (${path.relative(repoRoot, codexConfigPath)})`);
+    }
+    catch (err) {
+        result.errors.push(`Project Codex MCP: ${err.message}`);
+    }
+}
+async function setupProjectOpenCode(repoRoot, result) {
+    const opencodePath = path.join(repoRoot, 'opencode.json');
+    try {
+        const existing = await readJsonFile(opencodePath);
+        const merged = mergeOpenCodeConfig(existing);
+        await writeJsonFile(opencodePath, merged);
+        result.configured.push(`Project OpenCode MCP (${path.relative(repoRoot, opencodePath)})`);
+    }
+    catch (err) {
+        result.errors.push(`Project OpenCode MCP: ${err.message}`);
+    }
+}
 async function saveSetupScope(scope, result) {
     try {
         const existing = await loadCLIConfig();
@@ -321,8 +448,10 @@ export const setupCommand = async (options = {}) => {
     console.log('  ==============');
     console.log('');
     let scope;
+    let agent;
     try {
         scope = resolveSetupScope(options.scope);
+        agent = resolveSetupAgent(options.agent);
     }
     catch (err) {
         console.log(`  ${err?.message || String(err)}\n`);
@@ -338,15 +467,20 @@ export const setupCommand = async (options = {}) => {
         errors: [],
     };
     if (scope === 'global') {
-        // Detect and configure each editor's MCP
-        await setupCursor(result);
-        await setupClaudeCode(result);
-        await setupOpenCode(result);
-        await setupCodex(result);
+        // Configure only the selected agent MCP
+        if (agent === 'claude') {
+            await setupClaudeCode(result);
+            // Claude-only hooks should only be installed when Claude is selected.
+            await installClaudeCodeHooks(result);
+        }
+        else if (agent === 'opencode') {
+            await setupOpenCode(result);
+        }
+        else if (agent === 'codex') {
+            await setupCodex(result);
+        }
         // Install shared global skills once
         await installGlobalAgentSkills(result);
-        // Optional Claude-specific hooks
-        await installClaudeCodeHooks(result);
     }
     else {
         const repoRoot = getGitRoot(process.cwd());
@@ -355,7 +489,15 @@ export const setupCommand = async (options = {}) => {
             process.exitCode = 1;
             return;
         }
-        await setupProjectMcp(repoRoot, result);
+        if (agent === 'claude') {
+            await setupProjectMcp(repoRoot, result);
+        }
+        else if (agent === 'codex') {
+            await setupProjectCodex(repoRoot, result);
+        }
+        else if (agent === 'opencode') {
+            await setupProjectOpenCode(repoRoot, result);
+        }
         await installProjectAgentSkills(repoRoot, result);
     }
     await saveSetupScope(scope, result);
@@ -383,6 +525,7 @@ export const setupCommand = async (options = {}) => {
     console.log('');
     console.log('  Summary:');
     console.log(`    Scope: ${scope}`);
+    console.log(`    Agent: ${agent}`);
     console.log(`    MCP configured for: ${result.configured.filter(c => !c.includes('skills')).join(', ') || 'none'}`);
     console.log(`    Skills installed to: ${result.configured.filter(c => c.includes('skills')).length > 0 ? result.configured.filter(c => c.includes('skills')).join(', ') : 'none'}`);
     console.log('');