#!/usr/bin/env node

/**

* CodeGraph CLI

*

* Command-line interface for CodeGraph code intelligence.

*

* Usage:

* codegraph Run interactive installer (when no args)

* codegraph install Run interactive installer

* codegraph uninstall Remove CodeGraph from your agents

* codegraph init [path] Initialize CodeGraph in a project

* codegraph uninit [path] Remove CodeGraph from a project

* codegraph index [path] Index all files in the project

* codegraph sync [path] Sync changes since last index

* codegraph status [path] Show index status

* codegraph query <search> Search for symbols

* codegraph files [options] Show project file structure

* codegraph context <task> Build context for a task

* codegraph callers <symbol> Find what calls a function/method

* codegraph callees <symbol> Find what a function/method calls

* codegraph impact <symbol> Analyze what code is affected by changing a symbol

* codegraph affected [files] Find test files affected by changes

* codegraph upgrade [version] Update CodeGraph to the latest release

*/

// FIRST import, before anything else loads: capture process.ppid while our

// launcher is (almost certainly) still alive. A launcher killed mid-startup

// otherwise blinds the PPID watchdog forever (#1185) — see early-ppid.ts.

import '../mcp/early-ppid';

// Persist V8 compile artifacts across runs (Node ≥22.8). Every invocation —

// and every worker thread, which re-requires the whole extraction module

// graph — skips recompiling unchanged sources. Worth hundreds of ms of

// worker-boot latency per bulk index; harmless no-op when unavailable.

try {

// eslint-disable-next-line @typescript-eslint/no-require-imports

(require('node:module') as { enableCompileCache?: () => void }).enableCompileCache?.();

} catch { /* cache is best-effort */ }

import { Command } from 'commander';

import * as path from 'path';

import * as fs from 'fs';

import { getCodeGraphDir, isInitialized, unsafeIndexRootReason, findNearestCodeGraphRoot, planFrontload, hasStructuralKeyword, extractCodeTokens } from '../directory';

import { extractProseCandidates } from '../search/identifier-segments';

import { detectWorktreeIndexMismatch, worktreeMismatchWarning } from '../sync/worktree';

import { createShimmerProgress } from '../ui/shimmer-progress';

import { getGlyphs } from '../ui/glyphs';

import { ansiColorsEnabled } from '../ui/color';

import { buildNode25BlockBanner, buildNodeTooOldBanner, MIN_NODE_MAJOR } from './node-version-check';

import { installFatalHandlers } from './fatal-handler';

import { relaunchWithWasmRuntimeFlagsIfNeeded } from '../extraction/wasm-runtime-flags';

import { installCommandSupervision } from './command-supervision';

import { EXTRACTION_VERSION } from '../extraction/extraction-version';

import { getTelemetry, TELEMETRY_DOCS, recordIndexEvent } from '../telemetry';

// Decided once, before `--color`/`--no-color` are stripped from argv below

// (#1281). Piped/redirected stdout, NO_COLOR, or --no-color -> plain output.

const COLORS_ENABLED = ansiColorsEnabled();

// Lazy-load heavy modules (CodeGraph, runInstaller) to keep CLI startup fast.

async function loadCodeGraph(): Promise<typeof import('../index')> {

try {

return await import('../index');

} catch (err) {

const msg = err instanceof Error ? err.message : String(err);

const [red, reset] = COLORS_ENABLED ? ['\x1b[31m', '\x1b[0m'] : ['', ''];

console.error(`${red}${getGlyphs().err}${reset} Failed to load CodeGraph modules.`);

console.error(`\n Node: ${process.version} Platform: ${process.platform} ${process.arch}`);

console.error(`\n Error: ${msg}`);

console.error('\n Try reinstalling with: npm install -g @colbymchenry/codegraph\n');

process.exit(1);

}

}

// Dynamic import helper — tsc compiles import() to require() in CJS mode,

// which fails for ESM-only packages. This bypasses the transformation.

// eslint-disable-next-line @typescript-eslint/no-implied-eval

const importESM = new Function('specifier', 'return import(specifier)') as

(specifier: string) => Promise<typeof import('@clack/prompts')>;

// Block CodeGraph on Node.js 25.x — V8's turboshaft WASM JIT has a Zone

// allocator bug that reliably crashes when compiling tree-sitter

// grammars (see #54, #81, #140). The previous behaviour was a soft

// console.warn that scrolls off-screen before the OOM crash 30 seconds

// later, leading to a steady stream of "what is this OOM" reports.

// Hard-exit before any WASM work; allow override via env var for users

// who patched V8 themselves or want to test a future fix.

const nodeVersion = process.versions.node;

const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);

if (nodeMajor >= 25) {

process.stderr.write(buildNode25BlockBanner(nodeVersion) + '\n');

if (!process.env.CODEGRAPH_ALLOW_UNSAFE_NODE) {

process.exit(1);

}

// Override active — banner shown for visibility, continuing.

}

// Enforce the supported Node floor. `engines` in package.json only *warns* on

// install (unless engine-strict), so hard-block here to actually keep users off

// unsupported versions. Mirrors the 25+ block above. See package.json `engines`.

if (nodeMajor < MIN_NODE_MAJOR) {

process.stderr.write(buildNodeTooOldBanner(nodeVersion) + '\n');

if (!process.env.CODEGRAPH_ALLOW_UNSAFE_NODE) {

process.exit(1);

}

// Override active — banner shown for visibility, continuing.

}

// Re-exec with V8's `--liftoff-only` if it isn't already set, so tree-sitter's

// large WASM grammars never hit the turboshaft Zone OOM (`Fatal process out of

// memory: Zone`) on Node >= 22. No-op under the bundled launcher, which already

// passes the flag. Must run before any grammar (in the parse worker, which

// inherits this process's flags) is compiled. See ../extraction/wasm-runtime-flags.

relaunchWithWasmRuntimeFlagsIfNeeded(__filename);

// Last-resort fatal handlers: log a bounded line and exit non-zero. A fault

// that reaches here escaped every boundary, so the process is in an undefined

// state — keeping it alive is what let the detached MCP daemon orphan and pin a

// CPU core with no recovery (#799, #850). Installed before the command branch

// so it also covers a synchronous throw during startup. See ./fatal-handler.

installFatalHandlers();

// Check if running with no arguments - run installer

if (process.argv.length === 2) {

import('../installer').then(({ runInstaller }) =>

runInstaller()

).catch((err) => {

console.error('Installation failed:', err instanceof Error ? err.message : String(err));

process.exit(1);

});

} else {

// Normal CLI flow

main();

}

function main() {

const program = new Command();

// Version from package.json

const packageJson = JSON.parse(

fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8')

);

// Make the version trivial to reach. commander's `.version()` (below) wires up

// `--version` and `-V`; intercept the spellings it can't — lowercase `-v` and

// single-dash `-version` — before any parsing. (commander's version short flag

// is the capital `-V`, and its parser rejects a multi-character single-dash

// flag.) The bare `codegraph version` subcommand is registered further down so

// the affordance also shows up in `codegraph --help`.

const firstArg = process.argv[2];

if (firstArg === '-v' || firstArg === '-version') {

console.log(packageJson.version);

return;

}

// =============================================================================

// ANSI Color Helpers (avoid chalk ESM issues)

// =============================================================================

// `--color` / `--no-color` are global and position-independent — they were

// already read by ansiColorsEnabled() at module load, so strip them before

// commander parses (a subcommand would otherwise reject the unknown flag).

process.argv = process.argv.filter((a) => a !== '--color' && a !== '--no-color');

const colors = COLORS_ENABLED

? {

reset: '\x1b[0m',

bold: '\x1b[1m',

dim: '\x1b[2m',

red: '\x1b[31m',

green: '\x1b[32m',

yellow: '\x1b[33m',

blue: '\x1b[34m',

cyan: '\x1b[36m',

white: '\x1b[37m',

gray: '\x1b[90m',

}

: {

reset: '',

bold: '',

dim: '',

red: '',

green: '',

yellow: '',

blue: '',

cyan: '',

white: '',

gray: '',

};

const chalk = {

bold: (s: string) => `${colors.bold}${s}${colors.reset}`,

dim: (s: string) => `${colors.dim}${s}${colors.reset}`,

red: (s: string) => `${colors.red}${s}${colors.reset}`,

green: (s: string) => `${colors.green}${s}${colors.reset}`,

yellow: (s: string) => `${colors.yellow}${s}${colors.reset}`,

blue: (s: string) => `${colors.blue}${s}${colors.reset}`,

cyan: (s: string) => `${colors.cyan}${s}${colors.reset}`,

white: (s: string) => `${colors.white}${s}${colors.reset}`,

gray: (s: string) => `${colors.gray}${s}${colors.reset}`,

};

program

.name('codegraph')

.description('Code intelligence and knowledge graph for any codebase')

.version(packageJson.version)

// Parsed manually before commander runs (any argv position works); declared

// here so they show up in --help. NO_COLOR / FORCE_COLOR env vars are also

// honored, and piped output defaults to no color (#1281).

.option('--color', 'force ANSI colors even when stdout is not a TTY')

.option('--no-color', 'disable ANSI colors (NO_COLOR env is also honored)');

// Anonymous usage telemetry (see TELEMETRY.md): record the invoked subcommand

// NAME only — never arguments or paths. Counts buffer locally; network sends

// piggyback on commands that run long anyway (quick commands only append to

// the local buffer at exit, costing nothing).

// install/uninstall are absent on purpose: the installer flushes at its own

// end, AFTER its consent prompt — a flush here would fire the first-run

// notice before the user ever sees the toggle.

const TELEMETRY_FLUSH_COMMANDS = new Set(['init', 'uninit', 'index', 'sync', 'upgrade']);

program.hook('preAction', (_thisCommand, actionCommand) => {

try {

// The detached daemon re-invokes `serve --mcp` internally — not a user action.

if (process.env.CODEGRAPH_DAEMON_INTERNAL) return;

const name = actionCommand.name();

if (name === 'telemetry') return; // managing telemetry is not usage

getTelemetry().recordUsage('cli_command', name, true);

if (TELEMETRY_FLUSH_COMMANDS.has(name)) getTelemetry().maybeFlush();

} catch {

/* telemetry must never break the CLI */

}

});

// =============================================================================

// Helper Functions

// =============================================================================

/**

* Resolve project path from argument or current directory

* Walks up parent directories to find nearest initialized CodeGraph project

* (must have .codegraph/codegraph.db, not just .codegraph/lessons.db)

*/

function resolveProjectPath(pathArg?: string): string {

const absolutePath = path.resolve(pathArg || process.cwd());

// If exact path is initialized (has codegraph.db), use it

if (isInitialized(absolutePath)) {

return absolutePath;

}

// Walk up to find nearest parent with CodeGraph initialized

// Note: findNearestCodeGraphRoot finds any .codegraph folder, but we need one with codegraph.db

let current = absolutePath;

const root = path.parse(current).root;

while (current !== root) {

const parent = path.dirname(current);

if (parent === current) break;

current = parent;

if (isInitialized(current)) {

return current;

}

}

// Not found - return original path (will fail later with helpful error)

return absolutePath;

}

/**

* Format a number with commas

*/

function formatNumber(n: number): string {

return n.toLocaleString();

}

/**

* Format duration in milliseconds to human readable

*/

function formatDuration(ms: number): string {

if (ms < 1000) {

return `${ms}ms`;

}

const seconds = ms / 1000;

if (seconds < 60) {

return `${seconds.toFixed(1)}s`;

}

const minutes = Math.floor(seconds / 60);

const remainingSeconds = seconds % 60;

return `${minutes}m ${remainingSeconds.toFixed(0)}s`;

}

// Shimmer progress renderer (runs in a worker thread for smooth animation)

// Imported at top of file from '../ui/shimmer-progress'

/**

* Create a plain-text progress callback for --verbose mode.

* No animations, no ANSI tricks — just timestamped lines to stdout.

*/

function createVerboseProgress(): (progress: { phase: string; current: number; total: number; currentFile?: string }) => void {

let lastPhase = '';

let lastPct = -1;

const startTime = Date.now();

return (progress) => {

const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);

if (progress.phase !== lastPhase) {

lastPhase = progress.phase;

lastPct = -1;

console.log(`[${elapsed}s] Phase: ${progress.phase}`);

}

if (progress.total > 0) {

const pct = Math.floor((progress.current / progress.total) * 100);

// Log every 5% to keep output manageable

if (pct >= lastPct + 5 || progress.current === progress.total) {

lastPct = pct;

console.log(`[${elapsed}s] ${progress.current}/${progress.total} (${pct}%)${progress.currentFile ? ` ${getGlyphs().dash} ${progress.currentFile}` : ''}`);

}

} else if (progress.current > 0) {

// Scanning phase (no total yet) — log periodically

if (progress.current % 1000 === 0 || progress.current === 1) {

console.log(`[${elapsed}s] ${formatNumber(progress.current)} files found`);

}

}

};

}

/**

* Print success message

*/

function success(message: string): void {

console.log(chalk.green(getGlyphs().ok) + ' ' + message);

}

/**

* Print error message

*/

function error(message: string): void {

console.error(chalk.red(getGlyphs().err) + ' ' + message);

}

/**

* Print info message

*/

function info(message: string): void {

console.log(chalk.blue(getGlyphs().info) + ' ' + message);

}

/**

* Print warning message

*/

function warn(message: string): void {

console.log(chalk.yellow(getGlyphs().warn) + ' ' + message);

}

type IndexResult = {

success: boolean;

filesIndexed: number;

filesSkipped: number;

filesErrored: number;

nodesCreated: number;

edgesCreated: number;

errors: Array<{ message: string; filePath?: string; severity: string; code?: string }>;

durationMs: number;

};

/**

* Print indexing results using clack log methods

*/

function printIndexResult(clack: typeof import('@clack/prompts'), result: IndexResult, projectPath?: string): void {

const hasErrors = result.filesErrored > 0;

// Surface non-file-level failures (e.g. lock-acquisition failure

// when another indexer is running) before the file-count branches.

// Without this the CLI falls through to "No files found to index",

// which is actively misleading — the index DID run, it just couldn't

// get the lock.

//

// If success is false but no severity:'error' entry exists in

// `result.errors` (degenerate case — shouldn't happen in practice

// but worth guarding because the result shape is plumbed through

// multiple call sites), fall back to a generic message rather than

// continuing to the misleading "No files found" branch or throwing.

if (!result.success && !hasErrors && result.filesIndexed === 0) {

const generic = result.errors.find((e) => e.severity === 'error');

clack.log.error(generic?.message ?? `Indexing failed ${getGlyphs().dash} no further details available`);

return;

}

if (result.filesIndexed > 0) {

if (hasErrors) {

clack.log.success(`Indexed ${formatNumber(result.filesIndexed)} files (${formatNumber(result.filesErrored)} could not be parsed)`);

} else {

clack.log.success(`Indexed ${formatNumber(result.filesIndexed)} files`);

}

clack.log.info(`${formatNumber(result.nodesCreated)} nodes, ${formatNumber(result.edgesCreated)} edges in ${formatDuration(result.durationMs)}`);

// A PARTIAL index (files silently dropped mid-pipeline) must not pass

// as a clean run — it's the difference between "indexed the repo" and

// "indexed most of the repo, quietly". Only the completeness

// reconciliation warning; per-file extractor warnings stay in the

// error-code summary below.

for (const w of result.errors.filter((e) => e.code === 'index_partial')) {

clack.log.warn(w.message);

}

} else if (hasErrors) {

clack.log.error(`Indexing failed ${getGlyphs().dash} all ${formatNumber(result.filesErrored)} files had errors`);

} else {

clack.log.warn('No files found to index');

}

if (hasErrors) {

const errorsByCode = new Map<string, number>();

for (const err of result.errors) {

if (err.severity === 'error') {

const code = err.code || 'unknown';

errorsByCode.set(code, (errorsByCode.get(code) || 0) + 1);

}

}

const codeLabels: Record<string, string> = {

parse_error: 'files failed to parse',

read_error: 'files could not be read',

size_exceeded: 'files exceeded size limit',

path_traversal: 'blocked paths',

unsupported_language: 'unsupported language',

parser_error: 'parser initialization failures',

};

const breakdown = Array.from(errorsByCode)

.map(([code, count]) => `${formatNumber(count)} ${codeLabels[code] || code}`)

.join('\n');

clack.note(breakdown, 'Error breakdown');

if (projectPath) {

writeErrorLog(projectPath, result.errors);

clack.log.info('See .codegraph/errors.log for details');

}

if (result.filesIndexed > 0) {

clack.log.info(`The index is fully usable ${getGlyphs().dash} only the failed files are missing.`);

}

} else if (projectPath) {

const logPath = path.join(getCodeGraphDir(projectPath), 'errors.log');

if (fs.existsSync(logPath)) {

fs.unlinkSync(logPath);

}

}

}

/**

* When an `init`/`index` produced an EMPTY graph and the reason is that the

* project's own `.gitignore` excludes nested git repositories — the "super-repo

* gitignores its child repos" layout (#1156), where `init` at the parent

* correctly indexes ~nothing while `init` inside each child works — name those

* repos and offer to index them. An interactive terminal gets a yes/no prompt

* that writes `includeIgnored` to codegraph.json and re-indexes; a

* non-interactive run just prints the one-line opt-in snippet. The caller gates

* this on `nodesCreated === 0`, so a project that DID index real content is

* never nagged about the gitignored reference clones it deliberately keeps out

* (#970, #1065). Best-effort throughout: detection never breaks the command.

*/

async function offerIndexIgnoredRepos(

clack: typeof import('@clack/prompts'),

projectPath: string,

reindex: () => Promise<IndexResult>,

opts: { interactive: boolean },

): Promise<IndexResult | undefined> {

let repos: string[];

try {

const { findUnindexedIgnoredRepos } = await import('../extraction');

repos = findUnindexedIgnoredRepos(projectPath);

} catch {

return; // detection is advisory — never let it break the command

}

if (repos.length === 0) return;

const { PROJECT_CONFIG_FILENAME } = await import('../project-config');

const isOne = repos.length === 1;

const SHOWN = 6;

const names = repos.slice(0, SHOWN).map((r) => r.replace(/\/$/, ''));

const extra = repos.length > SHOWN ? ` (+${formatNumber(repos.length - SHOWN)} more)` : '';

const snippet = `{ "includeIgnored": [${repos.map((p) => JSON.stringify(p)).join(', ')}] }`;

clack.log.warn(

`Your .gitignore excludes ${isOne ? 'a nested git repository' : `${formatNumber(repos.length)} nested git repositories`} here, ` +

`so ${isOne ? 'it was' : 'they were'} not indexed: ${names.join(', ')}${extra}.`,

);

const manualHint = () => {

clack.log.info(

`If ${isOne ? "it's" : "they're"} your code, add ${isOne ? 'it' : 'them'} to ${PROJECT_CONFIG_FILENAME} and re-index:`,

);

clack.log.info(` ${snippet}`);

};

if (!opts.interactive || !process.stdin.isTTY) {

manualHint();

return;

}

const yes = await clack.confirm({

message: `Index ${isOne ? 'it' : `these ${formatNumber(repos.length)}`} now? Adds ${isOne ? 'it' : 'them'} to ${PROJECT_CONFIG_FILENAME}.`,

initialValue: true,

});

if (clack.isCancel(yes) || !yes) {

manualHint();

return;

}

let added: number;

try {

const { addIncludeIgnoredPatterns } = await import('../project-config');

added = addIncludeIgnoredPatterns(projectPath, repos);

} catch (err) {

clack.log.error(`Could not update ${PROJECT_CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`);

manualHint();

return;

}

clack.log.success(`Added ${formatNumber(added)} ${added === 1 ? 'entry' : 'entries'} to ${PROJECT_CONFIG_FILENAME} ${getGlyphs().dash} re-indexing…`);

const result = await reindex();

printIndexResult(clack, result, projectPath);

return result;

}

/**

* Write detailed error log to .codegraph/errors.log

*/

function writeErrorLog(projectPath: string, errors: Array<{ message: string; filePath?: string; severity: string; code?: string }>): void {

const cgDir = getCodeGraphDir(projectPath);

if (!fs.existsSync(cgDir)) return;

const logPath = path.join(cgDir, 'errors.log');

// Group errors by file path

const errorsByFile = new Map<string, Array<{ message: string; code?: string }>>();

const noFileErrors: Array<{ message: string; code?: string }> = [];

for (const err of errors) {

if (err.severity !== 'error') continue;

if (err.filePath) {

let list = errorsByFile.get(err.filePath);

if (!list) {

list = [];

errorsByFile.set(err.filePath, list);

}

list.push({ message: err.message, code: err.code });

} else {

noFileErrors.push({ message: err.message, code: err.code });

}

}

const lines: string[] = [

`CodeGraph Error Log - ${new Date().toISOString()}`,

`${errorsByFile.size} files with errors`,

'',

];

for (const [filePath, fileErrors] of errorsByFile) {

for (const err of fileErrors) {

lines.push(`${filePath}: ${err.message}`);

}

}

for (const err of noFileErrors) {

lines.push(err.message);

}

fs.writeFileSync(logPath, lines.join('\n') + '\n');

}

/**

* Telemetry for a completed full index (see TELEMETRY.md). The bounded flush

* keeps init/index responsive (these commands just ran for seconds anyway)

* while delivering the event promptly.

*/

async function recordIndexTelemetry(

cg: { getStats(): { filesByLanguage: Record<string, number> }; getBackend(): string },

result: IndexResult,

): Promise<void> {

recordIndexEvent(cg, result);

await getTelemetry().flushNow();

}

// =============================================================================

// Commands

// =============================================================================

/**

* codegraph init [path]

*/

program

.command('init [path]')

.description('Initialize CodeGraph in a project directory and build the initial index')

.option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')

.option('-f, --force', 'Initialize even if the path looks like your home directory or a filesystem root')

.option('-v, --verbose', 'Show detailed worker lifecycle and memory info')

.action(async (pathArg: string | undefined, options: { index?: boolean; force?: boolean; verbose?: boolean }) => {

const projectPath = path.resolve(pathArg || process.cwd());

const clack = await importESM('@clack/prompts');

clack.intro('Initializing CodeGraph');

try {

// Refuse to index your home directory / a filesystem root — it pulls in

// caches, other projects, and your whole tree (a multi-GB index + watcher

// churn, and on pre-1.0 macOS a machine-crashing fd blowup, #845).

const unsafe = unsafeIndexRootReason(projectPath);

if (unsafe && !options.force) {

clack.log.error(`Refusing to initialize in ${projectPath} — it looks like ${unsafe}.`);

clack.log.info('Run this inside a specific project directory, or pass --force if you really mean to index everything under it.');

clack.outro('');

process.exitCode = 1;

return;

}

if (isInitialized(projectPath)) {

clack.log.warn(`Already initialized in ${projectPath}`);

clack.log.info('Use "codegraph index" to re-index or "codegraph sync" to update');

try {

const { offerWatchFallback } = await import('../installer');

await offerWatchFallback(clack, projectPath);

} catch { /* non-fatal */ }

clack.outro('');

return;

}

const { default: CodeGraph, getDatabasePath } = await loadCodeGraph();

const cg = await CodeGraph.init(projectPath, { index: false });

clack.log.success(`Initialized in ${projectPath}`);

// Indexing runs by default now. The legacy -i/--index flag is still

// accepted (so existing muscle memory and scripts don't break) but is a

// no-op — initializing always builds the initial index.

// Supervise the index: self-terminate if orphaned or wedged (#999).

// The DB + WAL paths let the liveness watchdog tell a slow store on

// degraded storage from a true wedge (#1231).

// A closure so we can re-run the exact same supervised, progress-rendered

// index if the user opts gitignored child repos in below (#1156).

const dbPath = getDatabasePath(projectPath);

const runIndex = async (): Promise<IndexResult> => {

const supervision = installCommandSupervision('init', { progressPaths: [dbPath, `${dbPath}-wal`] });

try {

if (options.verbose) {

return await cg.indexAll({ onProgress: createVerboseProgress(), verbose: true });

}

process.stdout.write(`${colors.dim}${getGlyphs().rail}${colors.reset}\n`);

const progress = createShimmerProgress();

const r = await cg.indexAll({ onProgress: progress.onProgress });

await progress.stop();

return r;

} finally {

supervision.stop();

}

};

const result = await runIndex();

printIndexResult(clack, result, projectPath);

await recordIndexTelemetry(cg, result);

// An empty graph at a git super-repo usually means `.gitignore` excludes

// the child repos that hold the code — surface them and offer to opt in

// rather than leaving the user with a silent 0-node "Done". (#1156)

if (result.nodesCreated === 0) {

await offerIndexIgnoredRepos(clack, projectPath, runIndex, { interactive: true });

}

try {

const { offerWatchFallback } = await import('../installer');

await offerWatchFallback(clack, projectPath);

} catch { /* non-fatal */ }

clack.outro('Done');

cg.destroy();

} catch (err) {

clack.log.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);

process.exit(1);

}

});

/**

* codegraph uninit [path]

*/

program

.command('uninit [path]')

.description('Remove CodeGraph from a project (deletes .codegraph/ directory)')

.option('-f, --force', 'Skip confirmation prompt')

.action(async (pathArg: string | undefined, options: { force?: boolean }) => {

const projectPath = resolveProjectPath(pathArg);

try {

if (!isInitialized(projectPath)) {

warn(`CodeGraph is not initialized in ${projectPath}`);

return;

}

if (!options.force) {

// Confirm with user

const readline = await import('readline');

const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

const answer = await new Promise<string>((resolve) => {

rl.question(

chalk.yellow(`${getGlyphs().warn} This will permanently delete all CodeGraph data. Continue? (y/N) `),

resolve

);

});

rl.close();

if (answer.toLowerCase() !== 'y') {

info('Cancelled');

return;

}

}

const { default: CodeGraph } = await loadCodeGraph();

const cg = CodeGraph.openSync(projectPath);

cg.uninitialize();

// Clean up any git sync hooks we installed (no-op if none / not a repo).

try {

const { removeGitSyncHook } = await import('../sync/git-hooks');

const removed = removeGitSyncHook(projectPath);

if (removed.installed.length > 0) {

info(`Removed git ${removed.installed.join(', ')} sync hook${removed.installed.length > 1 ? 's' : ''}`);

}

} catch { /* non-fatal */ }

success(`Removed CodeGraph from ${projectPath}`);

// Churn signal — and flush now, since after an uninit there may be no

// "next run" to deliver it.

try {

getTelemetry().recordLifecycle('uninstall', {});

await getTelemetry().flushNow();

} catch { /* non-fatal */ }

} catch (err) {

error(`Failed to uninitialize: ${err instanceof Error ? err.message : String(err)}`);

process.exit(1);

}

});

/**

* codegraph index [path]

*/

program

.command('index [path]')

.description('Rebuild the full index from scratch (same result as a fresh init)')

.option('-f, --force', 'Index even if the path looks like your home directory or a filesystem root')

.option('-q, --quiet', 'Suppress progress output')

.option('-v, --verbose', 'Show detailed worker lifecycle and memory info')

.action(async (pathArg: string | undefined, options: { force?: boolean; quiet?: boolean; verbose?: boolean }) => {

const projectPath = resolveProjectPath(pathArg);

try {

// Don't (re)index your home directory / a filesystem root (#845). --force

// doubles as the override.

const unsafe = unsafeIndexRootReason(projectPath);

if (unsafe && !options.force) {

error(`Refusing to index ${projectPath} — it looks like ${unsafe}. Pass --force to override.`);

process.exit(1);

}

if (!isInitialized(projectPath)) {

error(`CodeGraph not initialized in ${projectPath}`);

info('Run "codegraph init" first');

process.exit(1);

}

const { default: CodeGraph, getDatabasePath } = await loadCodeGraph();

// `index` is a FULL re-index — identical to a fresh `init`. RECREATE the

// database from scratch (discard .codegraph/codegraph.db + its WAL) rather

// than opening the old graph and DELETE-ing every row. The clear-then-index

// approach reported "0 nodes" without the clear (#874); the recreate keeps

// that fixed AND avoids the failure mode where, on a large or pre-fix

// poisoned index, the per-row FTS delete churn wedged the main thread long

// enough to trip the liveness watchdog before scanning even began (#1067).

// recreate() hands back a fresh, empty instance — no clear() needed. For

// fast incremental updates use `sync`.

const cg = await CodeGraph.recreate(projectPath);

// Supervise the indexer: self-terminate if orphaned (parent shim killed)

// or if the main thread wedges — neither was guarded on this path (#999).

// The DB + WAL paths let the liveness watchdog tell a slow store on

// degraded storage from a true wedge (#1231).

const dbPath = getDatabasePath(projectPath);

const supervision = installCommandSupervision('index', { progressPaths: [dbPath, `${dbPath}-wal`] });

try {

if (options.quiet) {

// Quiet mode: no UI, just run against the freshly-recreated graph.

const result = await cg.indexAll();

if (!result.success) process.exit(1);

cg.destroy();

return;

}

const clack = await importESM('@clack/prompts');

clack.intro('Indexing project');

// A closure so a re-index (after opting gitignored child repos in, #1156)

// renders identically. Supervision already wraps the whole command.

const renderIndex = async (): Promise<IndexResult> => {

if (options.verbose) {

return await cg.indexAll({ onProgress: createVerboseProgress(), verbose: true });

}

process.stdout.write(`${colors.dim}${getGlyphs().rail}${colors.reset}\n`);

const progress = createShimmerProgress();

const r = await cg.indexAll({ onProgress: progress.onProgress });

await progress.stop();

return r;

};

const result = await renderIndex();

printIndexResult(clack, result, projectPath);

await recordIndexTelemetry(cg, result);

// Empty graph at a git super-repo → likely `.gitignore`d child repos;

// name them and offer to opt in instead of a silent 0-node result (#1156).

let finalResult = result;

if (result.nodesCreated === 0) {

finalResult = (await offerIndexIgnoredRepos(clack, projectPath, renderIndex, { interactive: true })) ?? result;

}

if (!finalResult.success) {

process.exit(1);

}

clack.outro('Done');

cg.destroy();

} finally {

supervision.stop();

}

} catch (err) {

error(`Failed to index: ${err instanceof Error ? err.message : String(err)}`);

process.exit(1);

}

});

/**

* codegraph sync [path]

*/

program

.command('sync [path]')

.description('Sync changes since last index')

.option('-q, --quiet', 'Suppress output (for git hooks)')

.action(async (pathArg: string | undefined, options: { quiet?: boolean }) => {

const projectPath = resolveProjectPath(pathArg);

try {

if (!isInitialized(projectPath)) {

if (!options.quiet) {

error(`CodeGraph not initialized in ${projectPath}`);

}

process.exit(1);

}

const { default: CodeGraph } = await loadCodeGraph();

const cg = await CodeGraph.open(projectPath);

if (options.quiet) {

await cg.sync();

cg.destroy();

return;

}

const clack = await importESM('@clack/prompts');

clack.intro('Syncing CodeGraph');

process.stdout.write(`${colors.dim}${getGlyphs().rail}${colors.reset}\n`);

const progress = createShimmerProgress();

const result = await cg.sync({

onProgress: progress.onProgress,

});

await progress.stop();

const totalChanges = result.filesAdded + result.filesModified + result.filesRemoved;

if (totalChanges === 0) {

clack.log.info('Already up to date');

} else {

clack.log.success(`Synced ${formatNumber(totalChanges)} changed files`);

const details: string[] = [];

if (result.filesAdded > 0) details.push(`Added: ${result.filesAdded}`);

if (result.filesModified > 0) details.push(`Modified: ${result.filesModified}`);

if (result.filesRemoved > 0) details.push(`Removed: ${result.filesRemoved}`);

clack.log.info(`${details.join(', ')} ${getGlyphs().dash} ${formatNumber(result.nodesUpdated)} nodes in ${formatDuration(result.durationMs)}`);

}

clack.outro('Done');

cg.destroy();

} catch (err) {

if (!options.quiet) {

error(`Failed to sync: ${err instanceof Error ? err.message : String(err)}`);

}

process.exit(1);

}

});

/**

* codegraph status [path]

*/

program

.command('status [path]')

.description('Show index status and statistics')

.option('-j, --json', 'Output as JSON')

.action(async (pathArg: string | undefined, options: { json?: boolean }) => {

const projectPath = resolveProjectPath(pathArg);

// The directory the user actually ran from, before walking up to the index

// root. Used to detect when the resolved index lives in a different git

// working tree (e.g. a nested worktree borrowing the main checkout's index).

const startPath = path.resolve(pathArg || process.cwd());

const worktreeMismatch = detectWorktreeIndexMismatch(startPath, projectPath);

try {

if (!isInitialized(projectPath)) {

if (options.json) {

console.log(JSON.stringify({

initialized: false,

version: packageJson.version,

projectPath,

indexPath: getCodeGraphDir(projectPath),

lastIndexed: null,

}));

return;

}

console.log(chalk.bold('\nCodeGraph Status\n'));

info(`Project: ${projectPath}`);

warn('Not initialized');

info('Run "codegraph init" to initialize');

return;

}

const { default: CodeGraph } = await loadCodeGraph();

const cg = await CodeGraph.open(projectPath);

const stats = cg.getStats();

const changes = cg.getChangedFiles();

const backend = cg.getBackend();

const journalMode = cg.getJournalMode();

const buildInfo = cg.getIndexBuildInfo();

const reindexRecommended = cg.isIndexStale();

const indexState = cg.getIndexState();

// Zero on a healthy index; non-zero at rest means a resolution pass was

// interrupted, so some files' call edges are missing (#1187).

const pendingRefs = cg.getPendingReferenceCount();

// JSON output mode

if (options.json) {

const lastIndexedMs = cg.getLastIndexedAt();

console.log(JSON.stringify({

initialized: true,

version: packageJson.version,

projectPath,

indexPath: getCodeGraphDir(projectPath),

lastIndexed: lastIndexedMs != null ? new Date(lastIndexedMs).toISOString() : null,

fileCount: stats.fileCount,

nodeCount: stats.nodeCount,

edgeCount: stats.edgeCount,

dbSizeBytes: stats.dbSizeBytes,

walSizeBytes: stats.walSizeBytes,

backend,

journalMode,

nodesByKind: stats.nodesByKind,

languages: Object.entries(stats.filesByLanguage).filter(([, count]) => count > 0).map(([lang]) => lang),

pendingChanges: {

added: changes.added.length,

modified: changes.modified.length,

removed: changes.removed.length,

},

worktreeMismatch: worktreeMismatch

? { worktreeRoot: worktreeMismatch.worktreeRoot, indexRoot: worktreeMismatch.indexRoot }

: null,

index: {

builtWithVersion: buildInfo.version,

builtWithExtractionVersion: buildInfo.extractionVersion,

currentExtractionVersion: EXTRACTION_VERSION,

reindexRecommended,

// 'complete' | 'partial' (files silently dropped) | 'indexing'

// (a run was killed mid-index — the index is truncated) |

// 'failed' | null (predates the marker).

state: indexState,

// References awaiting resolution. Non-zero at rest means an

// interrupted resolution pass left edges missing; the next

// sync sweeps them (#1187).

pendingRefs,

},

}));

cg.destroy();

return;

}

console.log(chalk.bold('\nCodeGraph Status\n'));

// Project info

console.log(chalk.cyan('Project:'), projectPath);

if (worktreeMismatch) {