optave-codegraph 3.13.0

package/src/cli/commands/flow.ts

@@ -0,0 +1,34 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'flow [name]',
+  description:
+    'Trace execution flow forward from an entry point (route, command, event) through callees to leaves',
+  queryOpts: true,
+  options: [
+    ['--list', 'List all entry points grouped by type'],
+    ['--depth <n>', 'Max forward traversal depth', '10'],
+    ['-f, --file <path>', 'Scope to a specific file (partial match, repeatable)', collectFile],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+  ],
+  validate([name], opts) {
+    if (!name && !opts.list) {
+      return 'Provide a function/entry point name or use --list to see all entry points.';
+    }
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([name], opts, ctx) {
+    const { flow } = await import('../../presentation/flow.js');
+    flow(name, opts.db, {
+      list: opts.list,
+      depth: parseInt(opts.depth as string, 10),
+      file: opts.file,
+      kind: opts.kind,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/fn-impact.ts

@@ -0,0 +1,34 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { fnImpact } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'fn-impact <name>',
+  description: 'Function-level impact: what functions break if this one changes',
+  queryOpts: true,
+  options: [
+    ['--depth <n>', 'Max transitive depth', '5'],
+    [
+      '-f, --file <path>',
+      'Scope search to functions in this file (partial match, repeatable)',
+      collectFile,
+    ],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['--no-implementations', 'Exclude interface/trait implementors from blast radius'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    fnImpact(name!, opts.db, {
+      depth: parseInt(opts.depth as string, 10),
+      file: opts.file,
+      kind: opts.kind,
+      includeImplementors: opts.implementations !== false,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/impact.ts

@@ -0,0 +1,13 @@
+import { impactAnalysis } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'impact <file>',
+  description: 'Show what depends on this file (transitive)',
+  queryOpts: true,
+  execute([file], opts, ctx) {
+    impactAnalysis(file!, opts.db, {
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/implementations.ts

@@ -0,0 +1,30 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { implementations } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'implementations <name>',
+  description: 'List all concrete types implementing a given interface or trait',
+  queryOpts: true,
+  options: [
+    [
+      '-f, --file <path>',
+      'Scope search to symbols in this file (partial match, repeatable)',
+      collectFile,
+    ],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    implementations(name!, opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/info.ts

@@ -0,0 +1,79 @@
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'info',
+  description: 'Show codegraph engine info and diagnostics',
+  options: [['-d, --db <path>', 'Path to graph.db']],
+  async execute(_args, opts, ctx) {
+    const { getNativePackageVersion, isNativeAvailable, loadNative } = await import(
+      '../../infrastructure/native.js'
+    );
+    const { getActiveEngine } = await import('../../domain/parser.js');
+
+    const engine = ctx.program.opts().engine;
+    const { name: activeName, version: activeVersion } = getActiveEngine({ engine });
+    const nativeAvailable = isNativeAvailable();
+
+    console.log('\nCodegraph Diagnostics');
+    console.log('====================');
+    console.log(`  Version       : ${ctx.program.version()}`);
+    console.log(`  Node.js       : ${process.version}`);
+    console.log(`  Platform      : ${process.platform}-${process.arch}`);
+    console.log(`  Native engine : ${nativeAvailable ? 'available' : 'unavailable'}`);
+    if (nativeAvailable) {
+      const native = loadNative()!;
+      const binaryVersion =
+        typeof native.engineVersion === 'function' ? native.engineVersion() : 'unknown';
+      const pkgVersion = getNativePackageVersion();
+      const knownBinaryVersion = binaryVersion !== 'unknown' ? binaryVersion : null;
+      if (pkgVersion && knownBinaryVersion && pkgVersion !== knownBinaryVersion) {
+        console.log(
+          `  Native version: ${pkgVersion} (binary built as ${knownBinaryVersion}, engine loaded OK)`,
+        );
+      } else {
+        console.log(`  Native version: ${pkgVersion ?? binaryVersion}`);
+      }
+    }
+    console.log(`  Engine flag   : --engine ${engine}`);
+    console.log(`  Active engine : ${activeName}${activeVersion ? ` (v${activeVersion})` : ''}`);
+    console.log();
+
+    try {
+      const { findDbPath, getBuildMeta } = await import('../../db/index.js');
+      const Database = (await import('better-sqlite3')).default;
+      const dbPath = findDbPath(opts.db as string | undefined);
+      const fs = await import('node:fs');
+      if (fs.existsSync(dbPath)) {
+        const db = new Database(dbPath, { readonly: true });
+        const buildEngine = getBuildMeta(db, 'engine');
+        const buildVersion = getBuildMeta(db, 'codegraph_version');
+        const builtAt = getBuildMeta(db, 'built_at');
+        db.close();
+
+        if (buildEngine || buildVersion || builtAt) {
+          console.log('Build metadata');
+          console.log(
+            '\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500',
+          );
+          if (buildEngine) console.log(`  Engine        : ${buildEngine}`);
+          if (buildVersion) console.log(`  Version       : ${buildVersion}`);
+          if (builtAt) console.log(`  Built at      : ${builtAt}`);
+
+          if (buildVersion && buildVersion !== ctx.program.version()) {
+            console.log(
+              `  \u26A0 DB was built with v${buildVersion}, current is v${ctx.program.version()}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          if (buildEngine && buildEngine !== activeName) {
+            console.log(
+              `  \u26A0 DB was built with ${buildEngine} engine, active is ${activeName}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          console.log();
+        }
+      }
+    } catch {
+      /* diagnostics must never crash */
+    }
+  },
+};

package/src/cli/commands/interfaces.ts

@@ -0,0 +1,30 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { interfaces } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'interfaces <name>',
+  description: 'List all interfaces and traits that a class or struct implements',
+  queryOpts: true,
+  options: [
+    [
+      '-f, --file <path>',
+      'Scope search to symbols in this file (partial match, repeatable)',
+      collectFile,
+    ],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    interfaces(name!, opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/map.ts

@@ -0,0 +1,20 @@
+import { moduleMap } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'map',
+  description: 'High-level module overview with most-connected nodes',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-n, --limit <number>', 'Number of top nodes', '20'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  execute(_args, opts, ctx) {
+    moduleMap(opts.db, parseInt(opts.limit as string, 10), {
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+  },
+};

package/src/cli/commands/mcp.ts

@@ -0,0 +1,19 @@
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'mcp',
+  description: 'Start MCP (Model Context Protocol) server for AI assistant integration',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--multi-repo', 'Enable access to all registered repositories'],
+    ['--repos <names>', 'Comma-separated list of allowed repo names (restricts access)'],
+  ],
+  async execute(_args, opts) {
+    const { startMCPServer } = await import('../../mcp/index.js');
+    const mcpOpts = {
+      multiRepo: opts.multiRepo || !!opts.repos,
+      allowedRepos: opts.repos ? (opts.repos as string).split(',').map((s) => s.trim()) : undefined,
+    };
+    await startMCPServer(opts.db as string | undefined, mcpOpts);
+  },
+};

package/src/cli/commands/models.ts

@@ -0,0 +1,29 @@
+import { DEFAULT_MODEL, MODELS } from '../../domain/search/index.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'models',
+  description: 'List available embedding models',
+  execute(_args, _opts, ctx) {
+    const embeddingsConfig = ctx.config.embeddings;
+    const defaultModel = (embeddingsConfig?.model as string) || DEFAULT_MODEL;
+    console.log('\nAvailable embedding models:\n');
+
+    interface ModelEntry {
+      dim: number;
+      desc: string;
+      contextWindow?: number;
+    }
+
+    for (const [key, cfg] of Object.entries(MODELS)) {
+      const def = key === defaultModel ? ' (default)' : '';
+      const modelCfg = cfg as ModelEntry;
+      const ctxWindow = modelCfg.contextWindow ? `${modelCfg.contextWindow} ctx` : '';
+      console.log(
+        `  ${key.padEnd(12)} ${String(modelCfg.dim).padStart(4)}d  ${ctxWindow.padEnd(9)} ${modelCfg.desc}${def}`,
+      );
+    }
+    console.log('\nUsage: codegraph embed --model <name> --strategy <structured|source>');
+    console.log('       codegraph search "query" --model <name>\n');
+  },
+};

package/src/cli/commands/owners.ts

@@ -0,0 +1,28 @@
+import { collectFile } from '../../db/query-builder.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'owners [target]',
+  description: 'Show CODEOWNERS mapping for files and functions',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--owner <owner>', 'Filter to a specific owner'],
+    ['--boundary', 'Show cross-owner boundary edges'],
+    ['-f, --file <path>', 'Scope to a specific file (repeatable)', collectFile],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  async execute([target], opts, ctx) {
+    const { owners } = await import('../../presentation/owners.js');
+    owners(opts.db, {
+      owner: opts.owner,
+      boundary: opts.boundary,
+      file: opts.file && (opts.file as unknown[]).length > 0 ? opts.file : target,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+  },
+};

package/src/cli/commands/path.ts

@@ -0,0 +1,42 @@
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { symbolPath } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'path <from> <to>',
+  description: 'Find shortest path between two symbols (or files with --file)',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-f, --file', 'Treat <from> and <to> as file paths instead of symbol names'],
+    ['--reverse', 'Follow edges backward'],
+    [
+      '--kinds <kinds>',
+      'Comma-separated edge kinds to follow (default: calls; file mode: imports,imports-type)',
+    ],
+    ['--from-file <path>', 'Disambiguate source symbol by file'],
+    ['--to-file <path>', 'Disambiguate target symbol by file'],
+    ['--depth <n>', 'Max traversal depth', '10'],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  validate([_from, _to], opts) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([from, to], opts, ctx) {
+    symbolPath(from!, to!, opts.db, {
+      maxDepth: opts.depth ? parseInt(opts.depth as string, 10) : 10,
+      edgeKinds: opts.kinds ? (opts.kinds as string).split(',').map((s) => s.trim()) : undefined,
+      reverse: opts.reverse,
+      fromFile: opts.fromFile,
+      toFile: opts.toFile,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      file: opts.file,
+    });
+  },
+};

package/src/cli/commands/plot.ts

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { toErrorMessage } from '../../shared/errors.js';
+import { openGraph } from '../shared/open-graph.js';
+import type { CommandDefinition } from '../types.js';
+
+interface PlotConfig {
+  layout?: { algorithm?: string; direction?: string };
+  physics?: { enabled?: boolean; nodeDistance?: number };
+  nodeColors?: Record<string, string>;
+  roleColors?: Record<string, string>;
+  colorBy?: string;
+  edgeStyle?: { color?: string; smooth?: boolean };
+  filter?: { kinds?: string[] | null; roles?: string[] | null; files?: string[] | null };
+  title?: string;
+  seedStrategy?: string;
+  seedCount?: number;
+  clusterBy?: string;
+  sizeBy?: string;
+  overlays?: { complexity?: boolean; risk?: boolean };
+  riskThresholds?: { highBlastRadius?: number; lowMI?: number };
+}
+
+export const command: CommandDefinition = {
+  name: 'plot',
+  description: 'Generate an interactive HTML dependency graph viewer',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--functions', 'Function-level graph instead of file-level'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['--min-confidence <score>', 'Minimum edge confidence threshold (default: 0.5)', '0.5'],
+    ['-o, --output <file>', 'Write HTML to file'],
+    ['-c, --config <path>', 'Path to .plotDotCfg config file'],
+    ['--no-open', 'Do not open in browser'],
+    ['--cluster <mode>', 'Cluster nodes: none | community | directory'],
+    ['--overlay <list>', 'Comma-separated overlays: complexity,risk'],
+    ['--seed <strategy>', 'Seed strategy: all | top-fanin | entry'],
+    ['--seed-count <n>', 'Number of seed nodes (default: 30)'],
+    ['--size-by <metric>', 'Size nodes by: uniform | fan-in | fan-out | complexity'],
+    ['--color-by <mode>', 'Color nodes by: kind | role | community | complexity'],
+  ],
+  async execute(_args, opts, ctx) {
+    const { generatePlotHTML, loadPlotConfig } = await import('../../features/graph-enrichment.js');
+    const os = await import('node:os');
+    const { db, close } = openGraph(opts as { db?: string });
+
+    let plotCfg: PlotConfig;
+    let html: string;
+    try {
+      if (opts.config) {
+        try {
+          plotCfg = JSON.parse(fs.readFileSync(opts.config as string, 'utf-8')) as PlotConfig;
+        } catch (e: unknown) {
+          console.error(`Failed to load config: ${toErrorMessage(e)}`);
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        plotCfg = loadPlotConfig(process.cwd()) as PlotConfig;
+      }
+
+      if (opts.cluster) plotCfg.clusterBy = opts.cluster;
+      if (opts.colorBy) plotCfg.colorBy = opts.colorBy;
+      if (opts.sizeBy) plotCfg.sizeBy = opts.sizeBy;
+      if (opts.seed) plotCfg.seedStrategy = opts.seed;
+      if (opts.seedCount) plotCfg.seedCount = parseInt(opts.seedCount as string, 10);
+      if (opts.overlay) {
+        const parts = (opts.overlay as string).split(',').map((s) => s.trim());
+        if (!plotCfg.overlays) plotCfg.overlays = {};
+        if (parts.includes('complexity')) plotCfg.overlays.complexity = true;
+        if (parts.includes('risk')) plotCfg.overlays.risk = true;
+      }
+
+      html = generatePlotHTML(db, {
+        fileLevel: !opts.functions,
+        noTests: ctx.resolveNoTests(opts),
+        minConfidence: parseFloat(opts.minConfidence as string),
+        // PlotConfig shapes are structurally compatible; bridge the two declarations
+        config: plotCfg as never,
+      });
+    } finally {
+      close();
+    }
+
+    if (!html) {
+      console.error('generatePlotHTML returned no output');
+      process.exitCode = 1;
+      return;
+    }
+
+    const outPath =
+      (opts.output as string) || path.join(os.tmpdir(), `codegraph-plot-${Date.now()}.html`);
+    fs.writeFileSync(outPath, html, 'utf-8');
+    console.log(`Plot written to ${outPath}`);
+
+    if (opts.open !== false) {
+      const { execFile } = await import('node:child_process');
+      const args: [string, string[]] =
+        process.platform === 'win32'
+          ? ['cmd', ['/c', 'start', '', outPath]]
+          : process.platform === 'darwin'
+            ? ['open', [outPath]]
+            : ['xdg-open', [outPath]];
+      execFile(args[0], args[1], (err) => {
+        if (err) console.error('Could not open browser:', err.message);
+      });
+    }
+  },
+};

package/src/cli/commands/query.ts

@@ -0,0 +1,51 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { fnDeps, symbolPath } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'query <name>',
+  description: 'Function-level dependency chain or shortest path between symbols',
+  queryOpts: true,
+  options: [
+    ['--depth <n>', 'Transitive caller depth', '3'],
+    [
+      '-f, --file <path>',
+      'Scope search to functions in this file (partial match, repeatable)',
+      collectFile,
+    ],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['--path <to>', 'Path mode: find shortest path to <to>'],
+    ['--kinds <kinds>', 'Path mode: comma-separated edge kinds to follow (default: calls)'],
+    ['--reverse', 'Path mode: follow edges backward'],
+    ['--from-file <path>', 'Path mode: disambiguate source symbol by file'],
+    ['--to-file <path>', 'Path mode: disambiguate target symbol by file'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    if (opts.path) {
+      console.error('Note: "query --path" is deprecated, use "codegraph path <from> <to>" instead');
+      symbolPath(name!, opts.path as string, opts.db, {
+        maxDepth: opts.depth ? parseInt(opts.depth as string, 10) : 10,
+        edgeKinds: opts.kinds ? (opts.kinds as string).split(',').map((s) => s.trim()) : undefined,
+        reverse: opts.reverse,
+        fromFile: opts.fromFile,
+        toFile: opts.toFile,
+        kind: opts.kind,
+        noTests: ctx.resolveNoTests(opts),
+        json: opts.json,
+      });
+    } else {
+      fnDeps(name!, opts.db, {
+        depth: parseInt(opts.depth as string, 10),
+        file: opts.file,
+        kind: opts.kind,
+        ...ctx.resolveQueryOpts(opts),
+      });
+    }
+  },
+};

package/src/cli/commands/registry.ts

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  listRepos,
+  pruneRegistry,
+  REGISTRY_PATH,
+  registerRepo,
+  unregisterRepo,
+} from '../../infrastructure/registry.js';
+import { ConfigError } from '../../shared/errors.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'registry',
+  description: 'Manage the multi-repo project registry',
+  subcommands: [
+    {
+      name: 'list',
+      description: 'List all registered repositories',
+      options: [['-j, --json', 'Output as JSON']],
+      execute(_args, opts) {
+        pruneRegistry();
+        const repos = listRepos();
+        if (opts.json) {
+          console.log(JSON.stringify(repos, null, 2));
+        } else if (repos.length === 0) {
+          console.log(`No repositories registered.\nRegistry: ${REGISTRY_PATH}`);
+        } else {
+          console.log(`Registered repositories (${REGISTRY_PATH}):\n`);
+          for (const r of repos) {
+            const dbExists = fs.existsSync(r.dbPath);
+            const status = dbExists ? '' : ' [DB missing]';
+            console.log(`  ${r.name}${status}`);
+            console.log(`    Path: ${r.path}`);
+            console.log(`    DB:   ${r.dbPath}`);
+            console.log();
+          }
+        }
+      },
+    },
+    {
+      name: 'add <dir>',
+      description: 'Register a project directory',
+      options: [['-n, --name <name>', 'Custom name (defaults to directory basename)']],
+      execute([dir], opts) {
+        const absDir = path.resolve(dir!);
+        const { name, entry } = registerRepo(absDir, opts.name as string | undefined);
+        console.log(`Registered "${name}" → ${entry.path}`);
+      },
+    },
+    {
+      name: 'remove <name>',
+      description: 'Unregister a repository by name',
+      execute([name]) {
+        const removed = unregisterRepo(name!);
+        if (removed) {
+          console.log(`Removed "${name}" from registry.`);
+        } else {
+          throw new ConfigError(`Repository "${name}" not found in registry.`);
+        }
+      },
+    },
+    {
+      name: 'prune',
+      description: 'Remove stale registry entries (missing directories or idle beyond TTL)',
+      options: [
+        ['--ttl <days>', 'Days of inactivity before pruning (default: 30)', '30'],
+        ['--exclude <names>', 'Comma-separated repo names to preserve from pruning'],
+        ['--dry-run', 'Show what would be pruned without removing anything'],
+      ],
+      execute(_args, opts) {
+        const excludeNames = opts.exclude
+          ? (opts.exclude as string)
+              .split(',')
+              .map((s) => s.trim())
+              .filter((s) => s.length > 0)
+          : [];
+        const dryRun = !!opts.dryRun;
+        const pruned = pruneRegistry(
+          undefined,
+          parseInt(opts.ttl as string, 10),
+          excludeNames,
+          dryRun,
+        );
+        if (pruned.length === 0) {
+          console.log('No stale entries found.');
+        } else {
+          const prefix = dryRun ? 'Would prune' : 'Pruned';
+          for (const entry of pruned) {
+            const tag = entry.reason === 'expired' ? 'expired' : 'missing';
+            console.log(`${prefix} "${entry.name}" (${entry.path}) [${tag}]`);
+          }
+          if (dryRun) {
+            console.log(
+              `\nDry run: ${pruned.length} ${pruned.length === 1 ? 'entry' : 'entries'} would be removed.`,
+            );
+          } else {
+            console.log(
+              `\nRemoved ${pruned.length} stale ${pruned.length === 1 ? 'entry' : 'entries'}.`,
+            );
+          }
+        }
+      },
+    },
+  ],
+};