@veewo/gitnexus 1.3.11 → 1.4.6-rc

package/dist/cli/eval-server.js

@@ -1,7 +1,7 @@
 /**
  * Eval Server — Lightweight HTTP server for SWE-bench evaluation
  *
- * Keeps KuzuDB warm in memory so tool calls from the agent are near-instant.
+ * Keeps LadybugDB warm in memory so tool calls from the agent are near-instant.
  * Designed to run inside Docker containers during SWE-bench evaluation.
  *
  * KEY DESIGN: Returns LLM-friendly text, not raw JSON.
@@ -24,11 +24,12 @@
  *   POST /shutdown     — Graceful shutdown.
  */
 import http from 'http';
+import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 // ─── Text Formatters ──────────────────────────────────────────────────
 // Convert structured JSON results into compact, LLM-friendly text.
 // Design: minimize tokens, maximize actionability.
-function formatQueryResult(result) {
+export function formatQueryResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     const lines = [];
@@ -63,7 +64,7 @@ function formatQueryResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatContextResult(result) {
+export function formatContextResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     if (result.status === 'ambiguous') {
@@ -120,9 +121,11 @@ function formatContextResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatImpactResult(result) {
-    if (result.error)
-        return `Error: ${result.error}`;
+export function formatImpactResult(result) {
+    if (result.error) {
+        const suggestion = result.suggestion ? `\nSuggestion: ${result.suggestion}` : '';
+        return `Error: ${result.error}${suggestion}`;
+    }
     const target = result.target;
     const direction = result.direction;
     const byDepth = result.byDepth || {};
@@ -132,7 +135,11 @@ function formatImpactResult(result) {
     }
     const lines = [];
     const dirLabel = direction === 'upstream' ? 'depends on this (will break if changed)' : 'this depends on';
-    lines.push(`Blast radius for ${target?.kind || ''} ${target?.name} (${direction}): ${total} symbol(s) ${dirLabel}\n`);
+    lines.push(`Blast radius for ${target?.kind || ''} ${target?.name} (${direction}): ${total} symbol(s) ${dirLabel}`);
+    if (result.partial) {
+        lines.push('⚠️  Partial results — graph traversal was interrupted. Deeper impacts may exist.');
+    }
+    lines.push('');
     const depthLabels = {
         1: 'WILL BREAK (direct)',
         2: 'LIKELY AFFECTED (indirect)',
@@ -154,7 +161,7 @@ function formatImpactResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatCypherResult(result) {
+export function formatCypherResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     if (Array.isArray(result)) {
@@ -174,7 +181,7 @@ function formatCypherResult(result) {
     }
     return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
 }
-function formatDetectChangesResult(result) {
+export function formatDetectChangesResult(result) {
     if (result.error)
         return `Error: ${result.error}`;
     const summary = result.summary || {};
@@ -205,7 +212,7 @@ function formatDetectChangesResult(result) {
     }
     return lines.join('\n').trim();
 }
-function formatListReposResult(result) {
+export function formatListReposResult(result) {
     if (!Array.isArray(result) || result.length === 0) {
         return 'No indexed repositories.';
     }
@@ -349,10 +356,11 @@ export async function evalServerCommand(options) {
             console.error(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
         }
         try {
-            process.stdout.write(`GITNEXUS_EVAL_SERVER_READY:${port}\n`);
+            // Use fd 1 directly — LadybugDB captures process.stdout (#324)
+            writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${port}\n`);
         }
         catch {
-            // stdout may not be available
+            // stdout may not be available (e.g., broken pipe)
         }
     });
     resetIdleTimer();
@@ -365,10 +373,19 @@ export async function evalServerCommand(options) {
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+export const MAX_BODY_SIZE = 1024 * 1024; // 1MB
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on('data', (chunk) => chunks.push(chunk));
+        let totalSize = 0;
+        req.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_BODY_SIZE) {
+                req.destroy(new Error('Request body too large (max 1MB)'));
+                return;
+            }
+            chunks.push(chunk);
+        });
         req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
         req.on('error', reject);
     });

package/dist/cli/index.js

@@ -1,74 +1,23 @@
 #!/usr/bin/env node
-// Raise Node heap limit for large repos (e.g. Linux kernel).
-// Must run before any heavy allocation. If already set by the user, respect it.
-if (!process.env.NODE_OPTIONS?.includes('--max-old-space-size')) {
-    const execArgv = process.execArgv.join(' ');
-    if (!execArgv.includes('--max-old-space-size')) {
-        // Re-spawn with a larger heap (8 GB)
-        const { execFileSync } = await import('node:child_process');
-        try {
-            execFileSync(process.execPath, ['--max-old-space-size=8192', ...process.argv.slice(1)], {
-                stdio: 'inherit',
-                env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim() },
-            });
-            process.exit(0);
-        }
-        catch (e) {
-            const resolved = resolveChildProcessExit(e, 1);
-            if (resolved.bySignal && resolved.signal) {
-                process.stderr.write(`gitnexus: child process terminated by signal ${resolved.signal}\n`);
-            }
-            process.exit(resolved.code);
-        }
-    }
-}
+// Heap re-spawn removed — only analyze.ts needs the 8GB heap (via its own ensureHeap()).
+// Removing it from here improves MCP server startup time significantly.
 import { Command } from 'commander';
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { analyzeCommand } from './analyze.js';
-import { serveCommand } from './serve.js';
-import { listCommand } from './list.js';
-import { statusCommand } from './status.js';
-import { mcpCommand } from './mcp.js';
-import { cleanCommand } from './clean.js';
-import { setupCommand } from './setup.js';
-import { augmentCommand } from './augment.js';
-import { wikiCommand } from './wiki.js';
-import { queryCommand, contextCommand, impactCommand, cypherCommand } from './tool.js';
-import { evalServerCommand } from './eval-server.js';
-import { benchmarkUnityCommand } from './benchmark-unity.js';
-import { benchmarkAgentContextCommand } from './benchmark-agent-context.js';
-import { unityBindingsCommand } from './unity-bindings.js';
-import { benchmarkU2E2ECommand } from './benchmark-u2-e2e.js';
-import { resolveChildProcessExit } from './exit-code.js';
-function resolveCliVersion() {
-    try {
-        const currentFile = fileURLToPath(import.meta.url);
-        const packageJsonPath = path.resolve(path.dirname(currentFile), '..', '..', 'package.json');
-        const raw = fs.readFileSync(packageJsonPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.version === 'string' && parsed.version.length > 0) {
-            return parsed.version;
-        }
-    }
-    catch {
-        // fall through to default
-    }
-    return '0.0.0';
-}
+import { createRequire } from 'node:module';
+import { createLazyAction } from './lazy-action.js';
+const _require = createRequire(import.meta.url);
+const pkg = _require('../../package.json');
 const program = new Command();
 const collectValues = (value, previous) => [...previous, value];
 program
     .name('gitnexus')
     .description('GitNexus local CLI and MCP server')
-    .version(resolveCliVersion());
+    .version(pkg.version);
 program
     .command('setup')
     .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);
+    .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
@@ -77,33 +26,36 @@ 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('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .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);
+    .addHelpText('after', '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)')
+    .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 program
     .command('serve')
     .description('Start local HTTP server for web UI connection')
     .option('-p, --port <port>', 'Port number', '4747')
     .option('--host <host>', 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)')
-    .action(serveCommand);
+    .action(createLazyAction(() => import('./serve.js'), 'serveCommand'));
 program
     .command('mcp')
     .description('Start MCP server (stdio) — serves all indexed repos')
-    .action(mcpCommand);
+    .action(createLazyAction(() => import('./mcp.js'), 'mcpCommand'));
 program
     .command('list')
     .description('List all indexed repositories')
-    .action(listCommand);
+    .action(createLazyAction(() => import('./list.js'), 'listCommand'));
 program
     .command('status')
     .description('Show index status for current repo')
-    .action(statusCommand);
+    .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
-    .action(cleanCommand);
+    .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program
     .command('wiki [path]')
     .description('Generate repository wiki from knowledge graph')
@@ -113,11 +65,11 @@ program
     .option('--api-key <key>', 'LLM API key (saved to ~/.gitnexus/config.json)')
     .option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
     .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
-    .action(wikiCommand);
+    .action(createLazyAction(() => import('./wiki.js'), 'wikiCommand'));
 program
     .command('augment <pattern>')
     .description('Augment a search pattern with knowledge graph context (used by hooks)')
-    .action(augmentCommand);
+    .action(createLazyAction(() => import('./augment.js'), 'augmentCommand'));
 // ─── Direct Tool Commands (no MCP overhead) ────────────────────────
 // These invoke LocalBackend directly for use in eval, scripts, and CI.
 program
@@ -130,7 +82,7 @@ program
     .option('--content', 'Include full symbol source code')
     .option('--unity-resources <mode>', 'Unity resource retrieval mode: off|on|auto', 'off')
     .option('--unity-hydration <mode>', 'Unity hydration mode when resources are enabled: parity|compact', 'compact')
-    .action(queryCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
 program
     .command('context [name]')
     .description('360-degree view of a code symbol: callers, callees, processes')
@@ -140,15 +92,13 @@ program
     .option('--content', 'Include full symbol source code')
     .option('--unity-resources <mode>', 'Unity resource retrieval mode: off|on|auto', 'off')
     .option('--unity-hydration <mode>', 'Unity hydration mode when resources are enabled: parity|compact', 'compact')
-    .action(contextCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
     .command('unity-bindings <symbol>')
     .description('Experimental: inspect Unity resource bindings for a C# symbol')
     .option('--target-path <path>', 'Unity project root (default: cwd)')
     .option('--json', 'Output JSON')
-    .action(async (symbol, options) => {
-    await unityBindingsCommand(symbol, options);
-});
+    .action(createLazyAction(() => import('./unity-bindings.js'), 'unityBindingsCommand'));
 program
     .command('impact <target>')
     .description('Blast radius analysis: what breaks if you change a symbol')
@@ -159,19 +109,19 @@ program
     .option('--depth <n>', 'Max relationship depth (default: 3)')
     .option('--min-confidence <n>', 'Minimum edge confidence 0-1 (default: 0.3)')
     .option('--include-tests', 'Include test files in results')
-    .action(impactCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'impactCommand'));
 program
     .command('cypher <query>')
     .description('Execute raw Cypher query against the knowledge graph')
     .option('-r, --repo <name>', 'Target repository')
-    .action(cypherCommand);
+    .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')
     .description('Start lightweight HTTP server for fast tool calls during evaluation')
     .option('-p, --port <port>', 'Port number', '4848')
     .option('--idle-timeout <seconds>', 'Auto-shutdown after N seconds idle (0 = disabled)', '0')
-    .action(evalServerCommand);
+    .action(createLazyAction(() => import('./eval-server.js'), 'evalServerCommand'));
 program
     .command('benchmark-unity <dataset>')
     .description('Run Unity accuracy baseline and hard-gated regression checks')
@@ -184,7 +134,7 @@ program
     .option('--scope-manifest <path>', 'Analyze scope manifest file')
     .option('--scope-prefix <pathPrefix>', 'Analyze scope path prefix (repeatable)', collectValues, [])
     .option('--skip-analyze', 'Skip analyze stage and evaluate current index only')
-    .action(benchmarkUnityCommand);
+    .action(createLazyAction(() => import('./benchmark-unity.js'), 'benchmarkUnityCommand'));
 program
     .command('benchmark-agent-context <dataset>')
     .description('Run scenario-based agent refactor context benchmark')
@@ -197,15 +147,11 @@ program
     .option('--scope-manifest <path>', 'Analyze scope manifest file')
     .option('--scope-prefix <pathPrefix>', 'Analyze scope path prefix (repeatable)', collectValues, [])
     .option('--skip-analyze', 'Skip analyze stage and evaluate current index only')
-    .action(async (dataset, options) => {
-    await benchmarkAgentContextCommand(dataset, options);
-});
+    .action(createLazyAction(() => import('./benchmark-agent-context.js'), 'benchmarkAgentContextCommand'));
 program
     .command('benchmark-u2-e2e')
     .description('Run fail-fast full neonspark U2 E2E benchmark and emit evidence reports')
     .option('--config <path>', 'Path to E2E config JSON')
     .option('--report-dir <path>', 'Output directory for reports')
-    .action(async (options) => {
-    await benchmarkU2E2ECommand(options);
-});
+    .action(createLazyAction(() => import('./benchmark-u2-e2e.js'), 'benchmarkU2E2ECommand'));
 program.parse(process.argv);

package/dist/cli/lazy-action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates a lazy-loaded CLI action that defers module import until invocation.
+ * The generic constraints ensure the export name is a valid key of the module
+ * at compile time — catching typos when used with concrete module imports.
+ */
+export declare function createLazyAction<TModule extends Record<string, unknown>, TKey extends string & keyof TModule>(loader: () => Promise<TModule>, exportName: TKey): (...args: unknown[]) => Promise<void>;

package/dist/cli/lazy-action.js

@@ -0,0 +1,18 @@
+/**
+ * Creates a lazy-loaded CLI action that defers module import until invocation.
+ * The generic constraints ensure the export name is a valid key of the module
+ * at compile time — catching typos when used with concrete module imports.
+ */
+function isCallable(value) {
+    return typeof value === 'function';
+}
+export function createLazyAction(loader, exportName) {
+    return async (...args) => {
+        const module = await loader();
+        const action = module[exportName];
+        if (!isCallable(action)) {
+            throw new Error(`Lazy action export not found: ${exportName}`);
+        }
+        await action(...args);
+    };
+}

package/dist/cli/mcp.js

@@ -12,9 +12,11 @@ export const mcpCommand = async () => {
         process.env.GITNEXUS_UNITY_PARITY_WARMUP = '1';
     }
     // Prevent unhandled errors from crashing the MCP server process.
-    // KuzuDB lock conflicts and transient errors should degrade gracefully.
+    // LadybugDB lock conflicts and transient errors should degrade gracefully.
     process.on('uncaughtException', (err) => {
         console.error(`GitNexus MCP: uncaught exception — ${err.message}`);
+        // Process is in an undefined state after uncaughtException — exit after flushing
+        setTimeout(() => process.exit(1), 100);
     });
     process.on('unhandledRejection', (reason) => {
         const msg = reason instanceof Error ? reason.message : String(reason);

package/dist/cli/setup.js

@@ -14,10 +14,12 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'url';
 import { getGlobalDir, loadCLIConfig, saveCLIConfig } from '../storage/repo-manager.js';
 import { getGitRoot } from '../storage/git.js';
+import { glob } from 'glob';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
-const FALLBACK_MCP_PACKAGE = 'gitnexus@latest';
+const FALLBACK_MCP_PACKAGE = '@veewo/gitnexus@latest';
+const LEGACY_CURSOR_AGENT = 'cursor';
 function resolveSetupScope(rawScope) {
     if (!rawScope || rawScope.trim() === '')
         return 'global';
@@ -27,16 +29,28 @@ function resolveSetupScope(rawScope) {
 }
 function resolveSetupAgent(rawAgent) {
     if (!rawAgent || rawAgent.trim() === '') {
-        throw new Error('Missing --agent. Use one of: claude, opencode, codex.');
+        return 'claude';
     }
     if (rawAgent === 'claude' || rawAgent === 'opencode' || rawAgent === 'codex') {
         return rawAgent;
     }
     throw new Error(`Invalid --agent value "${rawAgent}". Use "claude", "opencode", or "codex".`);
 }
+async function installLegacyCursorSkills(result) {
+    const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Cursor skills (${installed.length} skills → ~/.cursor/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Cursor skills: ${err.message}`);
+    }
+}
 /**
  * Resolve the package spec used by MCP commands.
- * Defaults to gitnexus@latest when package metadata is unavailable.
+ * Defaults to @veewo/gitnexus@latest when package metadata is unavailable.
  */
 function resolveMcpPackageSpec() {
     try {
@@ -262,36 +276,39 @@ async function installClaudeCodeHooks(result) {
         const src = path.join(pluginHooksPath, 'gitnexus-hook.cjs');
         const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
         try {
-            const content = await fs.readFile(src, 'utf-8');
+            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);
+            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {
             // Script not found in source — skip
         }
-        const hookCmd = `node "${path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/')}"`;
+        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 = {};
-        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
-        // Session context is delivered via CLAUDE.md / skills instead.
-        // Add PreToolUse hook if not already present
-        if (!existing.hooks.PreToolUse)
-            existing.hooks.PreToolUse = [];
-        const hasPreToolHook = existing.hooks.PreToolUse.some((h) => h.hooks?.some((hh) => hh.command?.includes('gitnexus')));
-        if (!hasPreToolHook) {
-            existing.hooks.PreToolUse.push({
-                matcher: 'Grep|Glob|Bash',
-                hooks: [{
-                        type: 'command',
-                        command: hookCmd,
-                        timeout: 8000,
-                        statusMessage: 'Enriching with GitNexus graph context...',
-                    }],
-            });
+        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 }],
+                });
+            }
         }
+        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)');
+        result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
     }
     catch (err) {
         result.errors.push(`Claude Code hooks: ${err.message}`);
@@ -383,7 +400,6 @@ async function saveSetupScope(scope, result) {
     }
 }
 // ─── Skill Installation ───────────────────────────────────────────
-const SKILL_NAMES = ['gitnexus-exploring', 'gitnexus-debugging', 'gitnexus-impact-analysis', 'gitnexus-refactoring', 'gitnexus-guide', 'gitnexus-cli'];
 /**
  * Install GitNexus skills to a target directory.
  * Each skill is installed as {targetDir}/{skillName}/SKILL.md.
@@ -395,23 +411,36 @@ const SKILL_NAMES = ['gitnexus-exploring', 'gitnexus-debugging', 'gitnexus-impac
 async function installSkillsTo(targetDir) {
     const installed = [];
     const skillsRoot = path.join(__dirname, '..', '..', 'skills');
-    for (const skillName of SKILL_NAMES) {
+    let flatFiles = [];
+    let dirSkillFiles = [];
+    try {
+        [flatFiles, dirSkillFiles] = await Promise.all([
+            glob('*.md', { cwd: skillsRoot }),
+            glob('*/SKILL.md', { cwd: skillsRoot }),
+        ]);
+    }
+    catch {
+        return [];
+    }
+    const skillSources = new Map();
+    for (const relPath of dirSkillFiles) {
+        skillSources.set(path.dirname(relPath), { isDirectory: true });
+    }
+    for (const relPath of flatFiles) {
+        const skillName = path.basename(relPath, '.md');
+        if (!skillSources.has(skillName)) {
+            skillSources.set(skillName, { isDirectory: false });
+        }
+    }
+    for (const [skillName, source] of skillSources) {
         const skillDir = path.join(targetDir, skillName);
         try {
-            // Try directory-based skill first (skills/{name}/SKILL.md)
-            const dirSource = path.join(skillsRoot, skillName);
-            let isDirectory = false;
-            try {
-                const stat = await fs.stat(dirSource);
-                isDirectory = stat.isDirectory();
-            }
-            catch { /* not a directory */ }
-            if (isDirectory) {
+            if (source.isDirectory) {
+                const dirSource = path.join(skillsRoot, skillName);
                 await copyDirRecursive(dirSource, skillDir);
                 installed.push(skillName);
             }
             else {
-                // Fall back to flat file (skills/{name}.md)
                 const flatSource = path.join(skillsRoot, `${skillName}.md`);
                 const content = await fs.readFile(flatSource, 'utf-8');
                 await fs.mkdir(skillDir, { recursive: true });
@@ -450,6 +479,7 @@ export const setupCommand = async (options = {}) => {
     console.log('');
     let scope;
     let agent;
+    const legacyCursorMode = !options.agent || options.agent.trim() === '';
     try {
         scope = resolveSetupScope(options.scope);
         agent = resolveSetupAgent(options.agent);
@@ -468,20 +498,29 @@ export const setupCommand = async (options = {}) => {
         errors: [],
     };
     if (scope === 'global') {
-        // 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);
+        if (legacyCursorMode) {
+            await setupCursor(result);
+            await installLegacyCursorSkills(result);
+            await saveSetupScope(scope, result);
+            agent = LEGACY_CURSOR_AGENT;
         }
-        else if (agent === 'codex') {
-            await setupCodex(result);
+        else {
+            // 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);
+            await saveSetupScope(scope, result);
         }
-        // Install shared global skills once
-        await installGlobalAgentSkills(result);
     }
     else {
         const repoRoot = getGitRoot(process.cwd());
@@ -500,8 +539,8 @@ export const setupCommand = async (options = {}) => {
             await setupProjectOpenCode(repoRoot, result);
         }
         await installProjectAgentSkills(repoRoot, result);
+        await saveSetupScope(scope, result);
     }
-    await saveSetupScope(scope, result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -526,7 +565,7 @@ export const setupCommand = async (options = {}) => {
     console.log('');
     console.log('  Summary:');
     console.log(`    Scope: ${scope}`);
-    console.log(`    Agent: ${agent}`);
+    console.log(`    Agent: ${legacyCursorMode ? LEGACY_CURSOR_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('');

package/dist/cli/setup.test.js

@@ -16,21 +16,26 @@ const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 async function runSetup(args, env, cwd = packageRoot) {
     return execFileAsync(process.execPath, [cliPath, 'setup', ...args], { cwd, env });
 }
-test('setup requires --agent', async () => {
+test('setup without --agent uses legacy Cursor install path', async () => {
     const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-setup-home-'));
     try {
-        try {
-            await runSetup([], {
-                ...process.env,
-                HOME: fakeHome,
-                USERPROFILE: fakeHome,
-            });
-            assert.fail('expected setup without --agent to fail');
-        }
-        catch (err) {
-            assert.equal(typeof err?.stdout, 'string');
-            assert.match(err.stdout, /Missing --agent/);
-        }
+        await fs.mkdir(path.join(fakeHome, '.cursor'), { recursive: true });
+        await runSetup([], {
+            ...process.env,
+            HOME: fakeHome,
+            USERPROFILE: fakeHome,
+        });
+        const cursorMcpPath = path.join(fakeHome, '.cursor', 'mcp.json');
+        const cursorSkillPath = path.join(fakeHome, '.cursor', 'skills', 'gitnexus-cli', 'SKILL.md');
+        const configPath = path.join(fakeHome, '.gitnexus', 'config.json');
+        const cursorMcpRaw = await fs.readFile(cursorMcpPath, 'utf-8');
+        const cursorMcp = JSON.parse(cursorMcpRaw);
+        assert.equal(cursorMcp.mcpServers?.gitnexus?.command, 'npx');
+        assert.deepEqual(cursorMcp.mcpServers?.gitnexus?.args, ['-y', expectedMcpPackage, 'mcp']);
+        await fs.access(cursorSkillPath);
+        const configRaw = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(configRaw);
+        assert.equal(config.setupScope, 'global');
     }
     finally {
         await fs.rm(fakeHome, { recursive: true, force: true });