@codragraph/cli 1.6.2

package/dist/cli/index.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// 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 { createRequire } from 'node:module';
+import { createLazyAction } from './lazy-action.js';
+import { registerGroupCommands } from './group.js';
+const _require = createRequire(import.meta.url);
+const pkg = _require('../../package.json');
+const program = new Command();
+program
+    .name('@codragraph/cli')
+    .description('CodraGraph local CLI and MCP server')
+    .version(pkg.version);
+program
+    .command('setup')
+    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')
+    .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
+program
+    .command('analyze [path]')
+    .description('Index a repository (full analysis)')
+    .option('-f, --force', 'Force full re-index even if up to date')
+    .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+    .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('--skip-agents-md', 'Skip updating the codragraph section in AGENTS.md and CLAUDE.md')
+    .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
+    .option('--skip-git', 'Index a folder without requiring a .git directory')
+    .option('--name <alias>', 'Register this repo under a custom name in ~/.codragraph/registry.json ' +
+    '(disambiguates repos whose paths share a basename, e.g. two different .../app folders)')
+    .option('--allow-duplicate-name', 'Register this repo even if another path already uses the same --name alias. ' +
+    'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.')
+    .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
+    .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
+    .addHelpText('after', '\nEnvironment variables:\n' +
+    '  CODRAGRAPH_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .codragraphignore)\n' +
+    '  CODRAGRAPH_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
+    '\nTip: `.codragraphignore` supports `.gitignore`-style negation. Add e.g.\n' +
+    '     `!__tests__/` to index a directory that is auto-filtered by default (#771).')
+    .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
+program
+    .command('index [path...]')
+    .description('Register an existing .codragraph/ folder into the global registry (no re-analysis needed)')
+    .option('-f, --force', 'Register even if meta.json is missing (stats will be empty)')
+    .option('--allow-non-git', 'Allow registering folders that are not Git repositories')
+    .action(createLazyAction(() => import('./index-repo.js'), 'indexCommand'));
+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(createLazyAction(() => import('./serve.js'), 'serveCommand'));
+program
+    .command('mcp')
+    .description('Start MCP server (stdio) — serves all indexed repos')
+    .action(createLazyAction(() => import('./mcp.js'), 'mcpCommand'));
+program
+    .command('list')
+    .description('List all indexed repositories')
+    .action(createLazyAction(() => import('./list.js'), 'listCommand'));
+program
+    .command('status')
+    .description('Show index status for current repo')
+    .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
+program
+    .command('clean')
+    .description('Delete CodraGraph index for current repo')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .option('--all', 'Clean all indexed repos')
+    .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
+program
+    .command('remove <target>')
+    .description('Delete the CodraGraph index for a registered repo (by alias, name, or absolute path). ' +
+    'Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .action(createLazyAction(() => import('./remove.js'), 'removeCommand'));
+program
+    .command('wiki [path]')
+    .description('Generate repository wiki from knowledge graph')
+    .option('-f, --force', 'Force full regeneration even if up to date')
+    .option('--provider <provider>', 'LLM provider: openai or cursor (default: openai)')
+    .option('--model <model>', 'LLM model or Azure deployment name (default: minimax/minimax-m2.5)')
+    .option('--base-url <url>', 'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1')
+    .option('--api-key <key>', 'LLM API key or Azure api-key (saved to ~/.codragraph/config.json)')
+    .option('--api-version <version>', 'Azure api-version query param, e.g. 2024-10-21 (legacy Azure API only)')
+    .option('--reasoning-model', 'Mark deployment as reasoning model (o1/o3/o4-mini) — strips temperature, uses max_completion_tokens')
+    .option('--no-reasoning-model', 'Disable reasoning model mode (overrides saved config)')
+    .option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
+    .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
+    .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')
+    .option('--review', 'Stop after grouping to review module structure before generating pages')
+    .action(createLazyAction(() => import('./wiki.js'), 'wikiCommand'));
+program
+    .command('augment <pattern>')
+    .description('Augment a search pattern with knowledge graph context (used by hooks)')
+    .action(createLazyAction(() => import('./augment.js'), 'augmentCommand'));
+// ─── Direct Tool Commands (no MCP overhead) ────────────────────────
+// These invoke LocalBackend directly for use in eval, scripts, and CI.
+program
+    .command('query <search_query>')
+    .description('Search the knowledge graph for execution flows related to a concept')
+    .option('-r, --repo <name>', 'Target repository (omit if only one indexed)')
+    .option('-c, --context <text>', 'Task context to improve ranking')
+    .option('-g, --goal <text>', 'What you want to find')
+    .option('-l, --limit <n>', 'Max processes to return (default: 5)')
+    .option('--content', 'Include full symbol source code')
+    .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
+program
+    .command('context [name]')
+    .description('360-degree view of a code symbol: callers, callees, processes')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
+    .option('-f, --file <path>', 'File path to disambiguate common names')
+    .option('--content', 'Include full symbol source code')
+    .action(createLazyAction(() => import('./tool.js'), 'contextCommand'));
+program
+    .command('impact <target>')
+    .description('Blast radius analysis: what breaks if you change a symbol')
+    .option('-d, --direction <dir>', 'upstream (dependants) or downstream (dependencies)', 'upstream')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--depth <n>', 'Max relationship depth (default: 3)')
+    .option('--include-tests', 'Include test files in results')
+    .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(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
+program
+    .command('detect-changes')
+    .alias('detect_changes')
+    .description('Map git diff hunks to indexed symbols and affected execution flows')
+    .option('-s, --scope <scope>', 'What to analyze: unstaged, staged, all, or compare', 'unstaged')
+    .option('-b, --base-ref <ref>', 'Branch/commit for compare scope (e.g. main)')
+    .option('-r, --repo <name>', 'Target repository')
+    .action(createLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
+// ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
+program
+    .command('eval-server')
+    .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(createLazyAction(() => import('./eval-server.js'), 'evalServerCommand'));
+registerGroupCommands(program);
+// ─── Config: unified API-key model (~/.codragraph/config.json) ─────
+const configCmd = program
+    .command('config')
+    .description('Manage codragraph CLI config — provider API keys, base URLs, models');
+configCmd
+    .command('list', { isDefault: true })
+    .description('List configured providers (api keys redacted)')
+    .action(createLazyAction(() => import('./config.js'), 'configListCommand'));
+configCmd
+    .command('get <provider>')
+    .description("Show a provider's settings (api key redacted). Provider: claude, openai, opencode, openrouter, azure, cursor, custom.")
+    .action(createLazyAction(() => import('./config.js'), 'configGetCommand'));
+configCmd
+    .command('set <provider>')
+    .description('Set provider settings (writes ~/.codragraph/config.json with chmod 600 on POSIX).')
+    .option('-k, --api-key <key>', 'BYO API key for this provider')
+    .option('--base-url <url>', 'Override the default API base URL')
+    .option('--model <model>', 'Default model for this provider')
+    .option('--api-version <version>', 'Azure-only: api-version query param (e.g. 2024-10-21)')
+    .option('--reasoning-model', 'Mark deployment as reasoning model (o1/o3/o4-mini variants)')
+    .action(createLazyAction(() => import('./config.js'), 'configSetCommand'));
+configCmd
+    .command('remove <provider>')
+    .alias('rm')
+    .description("Remove a provider's configuration")
+    .action(createLazyAction(() => import('./config.js'), 'configRemoveCommand'));
+configCmd
+    .command('path')
+    .description('Print the canonical config-file path')
+    .action(createLazyAction(() => import('./config.js'), 'configPathCommand'));
+// ─── Versioned-graph commands (Phase 4) ────────────────────────────
+program
+    .command('log')
+    .description('Show the graph commit history for the current repo')
+    .option('-n, --limit <n>', 'Maximum number of commits to show', '50')
+    .action(createLazyAction(() => import('./graphstore.js'), 'logCommand'));
+const branchCmd = program.command('branch').description('Manage versioned-graph branches');
+branchCmd
+    .command('list', { isDefault: true })
+    .description('List branches')
+    .action(createLazyAction(() => import('./graphstore.js'), 'branchListCommand'));
+branchCmd
+    .command('create <name>')
+    .description('Create a new branch at HEAD (or at --from <target>)')
+    .option('--from <target>', 'Branch / commit id to start from (defaults to HEAD)')
+    .action(createLazyAction(() => import('./graphstore.js'), 'branchCreateCommand'));
+branchCmd
+    .command('delete <name>')
+    .description('Delete a branch ref (refuses the currently checked-out branch)')
+    .action(createLazyAction(() => import('./graphstore.js'), 'branchDeleteCommand'));
+program
+    .command('diff <from> <to>')
+    .description('Structural diff between two graph commits or branches')
+    .option('--semantic', 'Use the semantic differ (added APIs, classified modifications, processes)')
+    .action(async (from, to, opts) => {
+    const mod = await import('./graphstore.js');
+    if (opts.semantic)
+        await mod.diffSemanticCommand(from, to);
+    else
+        await mod.diffCommand(from, to);
+});
+program
+    .command('merge <branch>')
+    .description('Three-way merge <branch> into the current branch')
+    .option('-m, --message <message>', 'Override the default merge commit message')
+    .action(createLazyAction(() => import('./graphstore.js'), 'mergeCommand'));
+program
+    .command('gc')
+    .description('Garbage-collect unreachable graphstore objects (mark-and-sweep)')
+    .option('--dry-run', 'List what would be deleted without removing anything')
+    .action(createLazyAction(() => import('./graphstore.js'), 'gcCommand'));
+program
+    .command('commit')
+    .description('Re-snapshot the live graph and create a labelled commit')
+    .requiredOption('-m, --message <message>', 'Commit message')
+    .action(createLazyAction(() => import('./graphstore.js'), 'commitCommand'));
+program
+    .command('checkout <target>')
+    .description('Move HEAD to a branch or commit; --materialize also rebuilds the live LadybugDB')
+    .option('--materialize', 'Rebuild the live LadybugDB from the target snapshot (destructive)')
+    .action(createLazyAction(() => import('./graphstore.js'), 'checkoutCommand'));
+program
+    .command('materialize <target>')
+    .description('Rebuild a target snapshot into a fresh LadybugDB at --into <path> (read-only inspection)')
+    .requiredOption('--into <path>', 'Output LadybugDB file path')
+    .action(createLazyAction(() => import('./graphstore.js'), 'materializeCommand'));
+program
+    .command('blame <symbolId>')
+    .description("Show every commit where a symbol's row hash changed")
+    .option('--table <name>', 'Restrict to a specific node table (Function, Class, …)')
+    .option('-n, --limit <n>', 'Maximum number of changes to show', '20')
+    .action(createLazyAction(() => import('./graphstore.js'), 'blameCommand'));
+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/list.d.ts

@@ -0,0 +1,6 @@
+/**
+ * List Command
+ *
+ * Shows all indexed repositories from the global registry.
+ */
+export declare const listCommand: () => Promise<void>;

package/dist/cli/list.js

@@ -0,0 +1,40 @@
+/**
+ * List Command
+ *
+ * Shows all indexed repositories from the global registry.
+ */
+import { listRegisteredRepos } from '../storage/repo-manager.js';
+export const listCommand = async () => {
+    const entries = await listRegisteredRepos({ validate: true });
+    if (entries.length === 0) {
+        console.log('No indexed repositories found.');
+        console.log('Run `codragraph analyze` in a git repo to index it.');
+        return;
+    }
+    console.log(`\n  Indexed Repositories (${entries.length})\n`);
+    // Count occurrences of each name so colliding entries can be
+    // disambiguated in the header (#829). Unique-name entries render
+    // identically to pre-#829 output; only collisions gain a suffix.
+    const nameCounts = new Map();
+    for (const e of entries) {
+        const key = e.name.toLowerCase();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    for (const entry of entries) {
+        const indexedDate = new Date(entry.indexedAt).toLocaleString();
+        const stats = entry.stats || {};
+        const commitShort = entry.lastCommit?.slice(0, 7) || 'unknown';
+        const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;
+        const header = hasCollision ? `${entry.name}  (${entry.path})` : entry.name;
+        console.log(`  ${header}`);
+        console.log(`    Path:    ${entry.path}`);
+        console.log(`    Indexed: ${indexedDate}`);
+        console.log(`    Commit:  ${commitShort}`);
+        console.log(`    Stats:   ${stats.files ?? 0} files, ${stats.nodes ?? 0} symbols, ${stats.edges ?? 0} edges`);
+        if (stats.communities)
+            console.log(`    Clusters:   ${stats.communities}`);
+        if (stats.processes)
+            console.log(`    Processes:  ${stats.processes}`);
+        console.log('');
+    }
+};

package/dist/cli/mcp.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Command
+ *
+ * Starts the MCP server in standalone mode.
+ * Loads all indexed repos from the global registry.
+ * No longer depends on cwd — works from any directory.
+ */
+export declare const mcpCommand: () => Promise<void>;

package/dist/cli/mcp.js

@@ -0,0 +1,36 @@
+/**
+ * MCP Command
+ *
+ * Starts the MCP server in standalone mode.
+ * Loads all indexed repos from the global registry.
+ * No longer depends on cwd — works from any directory.
+ */
+import { startMCPServer } from '../mcp/server.js';
+import { LocalBackend } from '../mcp/local/local-backend.js';
+export const mcpCommand = async () => {
+    // Prevent unhandled errors from crashing the MCP server process.
+    // LadybugDB lock conflicts and transient errors should degrade gracefully.
+    process.on('uncaughtException', (err) => {
+        console.error(`CodraGraph 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);
+        console.error(`CodraGraph MCP: unhandled rejection — ${msg}`);
+    });
+    // Initialize multi-repo backend from registry.
+    // The server starts even with 0 repos — tools call refreshRepos() lazily,
+    // so repos indexed after the server starts are discovered automatically.
+    const backend = new LocalBackend();
+    await backend.init();
+    const repos = await backend.listRepos();
+    if (repos.length === 0) {
+        console.error('CodraGraph: No indexed repos yet. Run `codragraph analyze` in a git repo — the server will pick it up automatically.');
+    }
+    else {
+        console.error(`CodraGraph: MCP server starting with ${repos.length} repo(s): ${repos.map((r) => r.name).join(', ')}`);
+    }
+    // Start MCP server (serves all repos, discovers new ones lazily)
+    await startMCPServer(backend);
+};

package/dist/cli/remove.d.ts

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

package/dist/cli/remove.js

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

package/dist/cli/serve.d.ts

@@ -0,0 +1,4 @@
+export declare const serveCommand: (options?: {
+    port?: string;
+    host?: string;
+}) => Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,37 @@
+import { createServer } from '../server/api.js';
+// Catch anything that would cause a silent exit
+process.on('uncaughtException', (err) => {
+    console.error('\n[codragraph serve] Uncaught exception:', err.message);
+    if (process.env.DEBUG)
+        console.error(err.stack);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    console.error('\n[codragraph serve] Unhandled rejection:', reason?.message || reason);
+    if (process.env.DEBUG)
+        console.error(reason?.stack);
+    process.exit(1);
+});
+export const serveCommand = async (options) => {
+    const port = Number(options?.port ?? 4747);
+    // Default to 'localhost' so the OS decides whether to bind to 127.0.0.1 or
+    // ::1 based on system configuration, avoiding spurious CORS errors when the
+    // hosted frontend at codragraph.vercel.app connects to localhost.
+    const host = options?.host ?? 'localhost';
+    try {
+        await createServer(port, host);
+    }
+    catch (err) {
+        console.error(`\nFailed to start CodraGraph server:\n`);
+        console.error(`  ${err.message || err}\n`);
+        if (err.code === 'EADDRINUSE') {
+            console.error(`  Port ${port} is already in use. Either:`);
+            console.error(`    1. Stop the other process using port ${port}`);
+            console.error(`    2. Use a different port: codragraph serve --port 4748\n`);
+        }
+        if (err.stack && process.env.DEBUG) {
+            console.error(err.stack);
+        }
+        process.exit(1);
+    }
+};

package/dist/cli/setup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Setup Command
+ *
+ * One-time global MCP configuration writer.
+ * Detects installed AI editors and writes the appropriate MCP config
+ * so the CodraGraph MCP server is available in all projects.
+ */
+export declare const setupCommand: () => Promise<void>;