homegraph 1.1.2 → 1.2.0

package/dist/bin/homegraph.js

@@ -20,7 +20,7 @@
  *   homegraph callers <symbol>   Find what calls a function/method
  *   homegraph callees <symbol>   Find what a function/method calls
  *   homegraph impact <symbol>    Analyze what code is affected by changing a symbol
- *   homegraph affected [files]   Find test files affected by changes
+ *   homegraph index-api <tools>   Build OHOS API db from command-line-tools
  *   homegraph upgrade [version]  Update HomeGraph to the latest release
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -61,12 +61,14 @@ const commander_1 = require("commander");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const directory_1 = require("../directory");
+const utils_1 = require("../spec/utils");
 const worktree_1 = require("../sync/worktree");
 const shimmer_progress_1 = require("../ui/shimmer-progress");
 const glyphs_1 = require("../ui/glyphs");
 const node_version_check_1 = require("./node-version-check");
 const fatal_handler_1 = require("./fatal-handler");
 const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
+const command_supervision_1 = require("./command-supervision");
 const extraction_version_1 = require("../extraction/extraction-version");
 const telemetry_1 = require("../telemetry");
 // Lazy-load heavy modules (HomeGraph, runInstaller) to keep CLI startup fast.
@@ -235,6 +237,38 @@ function main() {
         // Not found - return original path (will fail later with helpful error)
         return absolutePath;
     }
+    /**
+     * Resolve the project root for spec operations by walking up from a path
+     * looking for `${SPEC_DATA_DIR}/meta.json` or `${SPEC_DATA_DIR}/commit4spec.db`.
+     * Falls back to the starting path when neither marker is found (callers
+     * handle the not-found case).
+     */
+    function resolveSpecProjectPath(pathArg) {
+        const startPath = path.resolve(pathArg || process.cwd());
+        // Direct hit
+        const checkDirs = [
+            `${utils_1.SPEC_DATA_DIR}/meta.json`,
+            `${utils_1.SPEC_DATA_DIR}/commit4spec.db`,
+        ];
+        for (const check of checkDirs) {
+            if (fs.existsSync(path.join(startPath, check)))
+                return startPath;
+        }
+        // Walk up
+        let current = startPath;
+        const root = path.parse(current).root;
+        while (current !== root) {
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+            for (const check of checkDirs) {
+                if (fs.existsSync(path.join(current, check)))
+                    return current;
+            }
+        }
+        return startPath; // fallback — callers handle not-found
+    }
     /**
      * Format a number with commas
      */
@@ -383,6 +417,19 @@ function main() {
                 fs.unlinkSync(logPath);
             }
         }
+        const ohosApiWarnings = result.errors.filter((e) => e.severity === 'warning' && e.code?.startsWith('ohos_api_'));
+        if (ohosApiWarnings.length > 0) {
+            clack.log.warn('OHOS SDK API db not attached — project index is complete; explore uses project code only.');
+            clack.note(ohosApiWarnings.map((e) => e.message).join('\n'), 'OHOS API notice');
+        }
+        const arktsDegraded = result.errors.filter((e) => e.code === 'arkts_degraded');
+        if (arktsDegraded.length > 0) {
+            clack.log.warn('ArkTS index quality notice — see details below.');
+            clack.note(`${arktsDegraded[0].message}\n\n` +
+                'Large ArkTS repos on Windows use an isolated indexer with enableMethodBodyBuild=true.\n' +
+                'If indexing failed, set HOMEGRAPH_ARKTS_STACK_SIZES_KB=65536,131072,262144 and retry:\n' +
+                '  node --stack-size=65536 dist/bin/homegraph.js index <path>', 'ArkTS quality notice');
+        }
     }
     /**
      * Write detailed error log to .homegraph/errors.log
@@ -479,20 +526,27 @@ function main() {
             // 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).
+            const supervision = (0, command_supervision_1.installCommandSupervision)('init');
             let result;
-            if (options.verbose) {
-                result = await cg.indexAll({
-                    onProgress: createVerboseProgress(),
-                    verbose: true,
-                });
+            try {
+                if (options.verbose) {
+                    result = await cg.indexAll({
+                        onProgress: createVerboseProgress(),
+                        verbose: true,
+                    });
+                }
+                else {
+                    process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
+                    const progress = (0, shimmer_progress_1.createShimmerProgress)();
+                    result = await cg.indexAll({
+                        onProgress: progress.onProgress,
+                    });
+                    await progress.stop();
+                }
             }
-            else {
-                process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
-                const progress = (0, shimmer_progress_1.createShimmerProgress)();
-                result = await cg.indexAll({
-                    onProgress: progress.onProgress,
-                });
-                await progress.stop();
+            finally {
+                supervision.stop();
             }
             printIndexResult(clack, result, projectPath);
             await recordIndexTelemetry(cg, result);
@@ -587,47 +641,56 @@ function main() {
                 process.exit(1);
             }
             const { default: HomeGraph } = await loadHomeGraph();
-            const cg = await HomeGraph.open(projectPath);
-            if (options.quiet) {
-                // Quiet mode: no UI, just run. `index` is a full re-index, so clear the
-                // existing graph and rebuild from scratch (see the note below — #874).
-                cg.clear();
-                const result = await cg.indexAll();
-                if (!result.success)
+            // `index` is a FULL re-index — identical to a fresh `init`. RECREATE the
+            // database from scratch (discard .homegraph/homegraph.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 HomeGraph.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).
+            const supervision = (0, command_supervision_1.installCommandSupervision)('index');
+            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');
+                let result;
+                if (options.verbose) {
+                    result = await cg.indexAll({
+                        onProgress: createVerboseProgress(),
+                        verbose: true,
+                    });
+                }
+                else {
+                    process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
+                    const progress = (0, shimmer_progress_1.createShimmerProgress)();
+                    result = await cg.indexAll({
+                        onProgress: progress.onProgress,
+                    });
+                    await progress.stop();
+                }
+                printIndexResult(clack, result, projectPath);
+                await recordIndexTelemetry(cg, result);
+                if (!result.success) {
                     process.exit(1);
+                }
+                clack.outro('Done');
                 cg.destroy();
-                return;
-            }
-            const clack = await importESM('@clack/prompts');
-            clack.intro('Indexing project');
-            // `index` is a FULL re-index: clear the existing graph and rebuild it from
-            // scratch so the result is identical to a fresh `init`. Without the clear,
-            // indexAll() skips every unchanged file by its content hash and reports
-            // "0 nodes, 0 edges" against the already-populated graph — which reads as
-            // "index wiped my index" (#874). For fast incremental updates use `sync`.
-            cg.clear();
-            let result;
-            if (options.verbose) {
-                result = await cg.indexAll({
-                    onProgress: createVerboseProgress(),
-                    verbose: true,
-                });
-            }
-            else {
-                process.stdout.write(`${colors.dim}${(0, glyphs_1.getGlyphs)().rail}${colors.reset}\n`);
-                const progress = (0, shimmer_progress_1.createShimmerProgress)();
-                result = await cg.indexAll({
-                    onProgress: progress.onProgress,
-                });
-                await progress.stop();
             }
-            printIndexResult(clack, result, projectPath);
-            await recordIndexTelemetry(cg, result);
-            if (!result.success) {
-                process.exit(1);
+            finally {
+                supervision.stop();
             }
-            clack.outro('Done');
-            cg.destroy();
         }
         catch (err) {
             error(`Failed to index: ${err instanceof Error ? err.message : String(err)}`);
@@ -730,6 +793,7 @@ function main() {
             const journalMode = cg.getJournalMode();
             const buildInfo = cg.getIndexBuildInfo();
             const reindexRecommended = cg.isIndexStale();
+            const ohosApi = cg.getOhosApiBinding();
             // JSON output mode
             if (options.json) {
                 const lastIndexedMs = cg.getLastIndexedAt();
@@ -755,6 +819,9 @@ function main() {
                     worktreeMismatch: worktreeMismatch
                         ? { worktreeRoot: worktreeMismatch.worktreeRoot, indexRoot: worktreeMismatch.indexRoot }
                         : null,
+                    ohosApi: ohosApi
+                        ? { version: ohosApi.version, packageName: ohosApi.packageName, dbPath: ohosApi.dbPath }
+                        : null,
                     index: {
                         builtWithVersion: buildInfo.version,
                         builtWithExtractionVersion: buildInfo.extractionVersion,
@@ -809,6 +876,13 @@ function main() {
                 console.log(`  ${lang.padEnd(15)} ${formatNumber(count)}`);
             }
             console.log();
+            if (ohosApi) {
+                console.log(chalk.bold('OHOS API Database:'));
+                console.log(`  Version:   ${ohosApi.version}`);
+                console.log(`  Package:   ${ohosApi.packageName}`);
+                console.log(`  DB:        ${ohosApi.dbPath}`);
+                console.log();
+            }
             // Pending changes
             const totalChanges = changes.added.length + changes.modified.length + changes.removed.length;
             if (totalChanges > 0) {
@@ -885,13 +959,16 @@ function main() {
                 }
                 else {
                     console.log(chalk.bold(`\nSearch Results for "${search}":\n`));
+                    // Results arrive already ranked by relevance, so the order conveys
+                    // it. We don't print the raw score: it's an unbounded BM25/FTS value
+                    // (relative-ranking only), and the old `(score * 100)%` rendered it
+                    // as nonsensical percentages like "12042%" (#1045). The MCP search
+                    // tool likewise shows no score. Raw `score` stays in --json output.
                     for (const result of results) {
                         const node = result.node;
                         const location = `${node.filePath}:${node.startLine}`;
-                        const score = chalk.dim(`(${(result.score * 100).toFixed(0)}%)`);
                         console.log(chalk.cyan(node.kind.padEnd(12)) +
-                            chalk.white(node.name) +
-                            ' ' + score);
+                            chalk.white(node.name));
                         console.log(chalk.dim(`  ${location}`));
                         if (node.signature) {
                             console.log(chalk.dim(`  ${node.signature}`));
@@ -986,11 +1063,15 @@ function main() {
                 return;
             }
             const prompt = String(input.prompt || '');
-            // Gate: only structural / flow / impact / where-how prompts get context.
-            // A cheap regex keeps every other prompt ("fix this typo") a zero-cost
-            // no-op so we never add latency where there's no structural answer to give.
-            const STRUCTURAL = /\b(how|where|trace|flow|path|reach(?:es|ed)?|call(?:s|ed|er|ers|ee)?|depend|impact|affect|wired?|connect|implement|architect|structure|breaks?|what calls|why does)\b/i;
-            if (!prompt || !STRUCTURAL.test(prompt))
+            // Gate: only structural / flow / impact / where-how prompts get context, so
+            // every other prompt ("fix this typo") stays a zero-cost no-op. Language-aware
+            // (English + CJK keywords, plus code-shaped tokens) so it fires for non-English
+            // prompts too (issue #994). A keyword fires on its own; a code-token is only a
+            // CANDIDATE — verified against the graph below, so a tech brand ("JavaScript")
+            // that looks like a symbol but isn't one here doesn't inject spurious context.
+            const keyworded = (0, directory_1.hasStructuralKeyword)(prompt);
+            const codeTokens = keyworded ? [] : (0, directory_1.extractCodeTokens)(prompt);
+            if (!keyworded && codeTokens.length === 0)
                 return;
             // Decide what to inject, shaped by WHERE the index(es) are: the nearest
             // indexed ancestor of cwd, or — when cwd is an un-indexed workspace root
@@ -1010,6 +1091,13 @@ function main() {
                 const { default: HomeGraph } = await loadHomeGraph();
                 const cg = await HomeGraph.open(plan.exploreRoot);
                 try {
+                    // Code-token-only prompt: require that at least one token is a REAL symbol
+                    // in THIS index before front-loading. Without it, a brand name or common
+                    // word that merely looks like code ("JavaScript", "GitHub") would run
+                    // explore and inject ~16KB of low-relevance context (issue #994 follow-up).
+                    // A keyword-bearing prompt skips this — the keyword is signal enough.
+                    if (!keyworded && !codeTokens.some((t) => cg.getNodesByName(t).length > 0))
+                        return;
                     const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
                     const handler = new ToolHandler(cg);
                     const result = await handler.execute('homegraph_explore', { query: prompt });
@@ -1045,14 +1133,17 @@ function main() {
         }
     });
     /**
-     * homegraph node <name>
+     * homegraph node [name]
      *
      * The CLI face of the MCP homegraph_node tool: one symbol's source +
      * caller/callee trail, or a whole file with line numbers + dependents
      * (Read-parity). Same subagent/non-MCP rationale as `explore`.
+     *
+     * `name` is OPTIONAL because `--file` (file-read mode) carries no symbol —
+     * a required `<name>` made `codegraph node -f <file>` unreachable (#1044).
      */
     program
-        .command('node <name>')
+        .command('node [name]')
         .description('One symbol\'s source + caller/callee trail, or read a file with line numbers + dependents (same output as the homegraph_node MCP tool)')
         .option('-p, --path <path>', 'Project path')
         .option('-f, --file <file>', 'Treat as file mode (or disambiguate a symbol to this file)')
@@ -1060,6 +1151,13 @@ function main() {
         .option('--limit <number>', 'File mode: maximum lines')
         .option('--symbols-only', 'File mode: just the symbol map + dependents')
         .action(async (name, options) => {
+        // Need a symbol (positional) OR a file (--file / a path-like positional).
+        // With [name] optional, a bare `codegraph node` reaches here with neither
+        // and must be told what to pass, rather than crashing downstream.
+        if (!name && !options.file) {
+            error("Pass a symbol name (e.g. 'codegraph node parseToken') or a file (e.g. 'codegraph node -f src/auth.ts', or 'codegraph node src/auth.ts').");
+            process.exit(1);
+        }
         const projectPath = resolveProjectPath(options.path);
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
@@ -1081,10 +1179,10 @@ function main() {
                 if (name && name !== options.file)
                     args.symbol = name;
             }
-            else if (name.includes('/') || name.includes('\\')) {
+            else if (name && (name.includes('/') || name.includes('\\'))) {
                 args.file = name.replace(/\\/g, '/');
             }
-            else {
+            else if (name) {
                 args.symbol = name;
                 args.includeCode = true;
             }
@@ -1393,15 +1491,15 @@ function main() {
                 console.error(chalk.bold('\nHomeGraph MCP Server\n'));
                 console.error(chalk.blue((0, glyphs_1.getGlyphs)().info) + ' Use --mcp flag to start the MCP server');
                 console.error('\nTo use with Claude Code, add to your MCP configuration:');
-                console.error(chalk.dim(`
-{
-  "mcpServers": {
-    "homegraph": {
-      "command": "homegraph",
-      "args": ["serve", "--mcp"]
-    }
-  }
-}
+                console.error(chalk.dim(`
+{
+  "mcpServers": {
+    "homegraph": {
+      "command": "homegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
 `));
                 console.error('Available tools:');
                 console.error(chalk.cyan('  homegraph_explore') + '   - Primary: source of the relevant symbols for any question');
@@ -1903,6 +2001,751 @@ function main() {
             process.exit(1);
         }
     });
+    // =============================================================================
+    // Spec commands (Commit4Spec knowledge graph)
+    // =============================================================================
+    const specCommand = program
+        .command('spec')
+        .description('Manage spec knowledge graph (reverse-mining, search, self-evolve)');
+    /**
+     * homegraph spec mine
+     */
+    specCommand
+        .command('mine')
+        .description('Reverse-mine spec knowledge from Git history')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--spec-storage-path <path>', 'Path to the .spec directory')
+        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('-v, --verbose', 'Show detailed output')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const repoPath = path.resolve(options.path || process.cwd());
+            const specStoragePath = options.specStoragePath ?? path.join(repoPath, '.spec');
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { runMiningPipeline } = await Promise.resolve().then(() => __importStar(require('../spec/mining/pipeline')));
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            if (!isGitRepo(repoPath)) {
+                error(`Not a git repository: ${repoPath}`);
+                process.exit(1);
+            }
+            if (options.verbose) {
+                info(`Repository: ${repoPath}`);
+                info(`Spec storage: ${specStoragePath}`);
+                info(`Database: ${dbPath}`);
+            }
+            const { db } = createDatabase(dbPath);
+            const result = runMiningPipeline(repoPath, specStoragePath, db);
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                info(`Specs found: ${result.specsFound}`);
+                info(`Commits found: ${result.commitsFound}`);
+                info(`Fragments: ${result.fragmentsFound}`);
+                info(`Relations: ${result.relationsCreated}`);
+                info(`Total entries: ${result.totalEntries}`);
+                info(`Skipped: ${result.skippedEntries.length}`);
+                if (result.skippedEntries.length > 0) {
+                    for (const entry of result.skippedEntries) {
+                        warn(`${entry.specId}: ${entry.reason}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            error(`Mining failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * homegraph spec match <text>
+     */
+    specCommand
+        .command('match <text>')
+        .description('Search the spec knowledge graph for a term or phrase')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('--top-k <number>', 'Number of results to return', '5')
+        .option('--no-fragments', 'Exclude code fragments from results')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (text, options) => {
+        let db;
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { resolveDbPath, computeBudgetProfile } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const { searchAndGetContext } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
+            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            if (!fs.existsSync(dbPath)) {
+                error(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`);
+                process.exit(1);
+            }
+            const created = createDatabase(dbPath);
+            db = created.db;
+            const topK = Math.max(1, Math.min(parseInt(options.topK || '5', 10) || 5, 50));
+            const includeFragments = options.fragments !== false;
+            const contexts = searchAndGetContext(db, text, topK, includeFragments);
+            if (contexts.length === 0) {
+                info('No specs matched your query.');
+                return;
+            }
+            const profile = computeBudgetProfile(contexts.length);
+            const results = contexts.map((ctx) => ({
+                spec_id: ctx.spec.id,
+                title: ctx.spec.title,
+                subtitles: ctx.spec.subtitles,
+                file_path: ctx.spec.filePath,
+                commits: ctx.commits.map((c) => ({
+                    hash: c.commit.hash,
+                    message: c.commit.message,
+                    relation_type: c.relationType,
+                    fragments: c.fragments.map((f) => ({
+                        file_path: f.filePath,
+                        change_type: f.changeType,
+                        start_line: f.startLine,
+                        end_line: f.endLine,
+                        code_diff: f.codeDiff,
+                    })),
+                })),
+            }));
+            if (options.json) {
+                console.log(JSON.stringify({
+                    query: text.slice(0, 200),
+                    matched_count: contexts.length,
+                    results,
+                }, null, 2));
+            }
+            else {
+                console.log(chalk.bold(`\n${contexts.length} spec${contexts.length !== 1 ? 's' : ''} matched:\n`));
+                for (const r of results) {
+                    console.log(chalk.bold(r.title));
+                    for (const commit of r.commits) {
+                        console.log(`  ${chalk.yellow(commit.hash.slice(0, 7))} ${commit.message}`);
+                        if (includeFragments && commit.fragments && commit.fragments.length > 0) {
+                            for (const fragment of commit.fragments.slice(0, profile.maxFragments || 3)) {
+                                console.log(chalk.dim(`    ${fragment.file_path}:${fragment.start_line}-${fragment.end_line} [${fragment.change_type}]`));
+                            }
+                        }
+                    }
+                    console.log();
+                }
+            }
+        }
+        catch (err) {
+            error(`Match failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        finally {
+            try {
+                db?.close();
+            }
+            catch { /* best effort */ }
+        }
+    });
+    /**
+     * homegraph spec find <filePath>
+     */
+    specCommand
+        .command('find <filePath>')
+        .description('Find specs related to the given file path via code-fragment matching')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (filePath, options) => {
+        let db;
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const { findSpecsByFilePath } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
+            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            if (!fs.existsSync(dbPath)) {
+                error(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`);
+                process.exit(1);
+            }
+            const created = createDatabase(dbPath);
+            db = created.db;
+            const result = findSpecsByFilePath(db, filePath);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    filePath,
+                    matched_count: result.matched_count,
+                    truncated: result.truncated,
+                    results: result.results,
+                }, null, 2));
+            }
+            else {
+                console.log(chalk.bold(`\n${result.matched_count} spec${result.matched_count !== 1 ? 's' : ''} matched for ${filePath}:\n`));
+                for (const r of result.results) {
+                    console.log(`  ${chalk.cyan(r.id.padEnd(16))} ${r.title.padEnd(32)} ${chalk.green(r.status.padEnd(12))} v${r.version}  ${chalk.dim(r.filePath)}`);
+                }
+                console.log();
+                if (result.truncated) {
+                    console.log(chalk.yellow(`  ... and more (showing first ${result.matched_count} of >${result.matched_count} results)`));
+                    console.log();
+                }
+                if (result.matched_count === 0) {
+                    info(`No specs found for file path "${filePath}". Try a partial path (e.g. "src/auth" instead of "src/auth/login.ts").`);
+                }
+            }
+        }
+        catch (err) {
+            error(`Find failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        finally {
+            try {
+                db?.close();
+            }
+            catch { /* best effort */ }
+        }
+    });
+    /**
+     * homegraph spec trace <symbol>
+     */
+    specCommand
+        .command('trace <symbol>')
+        .description('Trace a code symbol back to its associated design Specs')
+        .option('-f, --file <path>', 'File path for symbol disambiguation')
+        .option('-l, --line <number>', 'Line number for symbol disambiguation')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('--top-k <number>', 'Number of results to return', '10')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (symbol, options) => {
+        let db;
+        let cg;
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            // isNaN check so --line 0 is handled correctly (parseInt('0') → 0 is falsy)
+            const lineRaw = options.line !== undefined ? parseInt(options.line, 10) : NaN;
+            const line = isNaN(lineRaw) ? undefined : lineRaw;
+            // Open HomeGraph code index
+            const { default: HomeGraph } = await Promise.resolve().then(() => __importStar(require('../index')));
+            cg = await HomeGraph.open(repoPath);
+            // Inline symbol resolution (mirrors findSymbolMatches in tools.ts)
+            const isQualified = /[.\/]|::/.test(symbol);
+            const { isGeneratedFile } = await Promise.resolve().then(() => __importStar(require('../extraction/generated-detection')));
+            let nodes = [];
+            if (!isQualified) {
+                const exact = cg.getNodesByName(symbol);
+                if (exact.length > 0) {
+                    nodes = [...exact].sort((a, b) => (isGeneratedFile(a.filePath) ? 1 : 0) - (isGeneratedFile(b.filePath) ? 1 : 0));
+                }
+                else {
+                    const fuzzy = cg.searchNodes(symbol, { limit: 10 });
+                    if (fuzzy[0])
+                        nodes = [fuzzy[0].node];
+                }
+            }
+            else {
+                let results = cg.searchNodes(symbol, { limit: 50 });
+                if (results.length === 0) {
+                    const parts = symbol.split(/::|[./]/).filter((p) => p.length > 0);
+                    const tail = parts[parts.length - 1];
+                    if (tail && tail !== symbol)
+                        results = cg.searchNodes(tail, { limit: 50 });
+                }
+                // Rough matchesSymbol equivalent for CLI
+                const exactMatches = results.filter((r) => {
+                    const n = r.node;
+                    if (n.name === symbol)
+                        return true;
+                    const fileBase = n.filePath.split('/').pop()?.replace(/\.[^.]+$/, '');
+                    if (fileBase === symbol)
+                        return true;
+                    const parts = symbol.split(/::|[./]/);
+                    if (parts[parts.length - 1] === n.name) {
+                        const firstPart = parts[0];
+                        if (n.qualifiedName.includes(firstPart))
+                            return true;
+                        if (n.filePath.includes(firstPart))
+                            return true;
+                        return parts.length === 1;
+                    }
+                    return false;
+                });
+                if (exactMatches.length > 0) {
+                    nodes = exactMatches
+                        .sort((a, b) => (isGeneratedFile(a.node.filePath) ? 1 : 0) - (isGeneratedFile(b.node.filePath) ? 1 : 0))
+                        .map((r) => r.node);
+                }
+            }
+            if (nodes.length === 0) {
+                console.log(chalk.yellow(`No code entities found for symbol "${symbol}".`));
+                return;
+            }
+            // Disambiguate
+            if (options.file) {
+                // Use endsWith for precise file name matching (not substring matching)
+                const filePattern = options.file;
+                nodes = nodes.filter((n) => n.filePath.endsWith(filePattern));
+            }
+            if (line !== undefined && nodes.length > 1) {
+                const closest = nodes.reduce((best, n) => {
+                    const bestDist = Math.abs(best.startLine - line) + Math.abs(best.endLine - line);
+                    const curDist = Math.abs(n.startLine - line) + Math.abs(n.endLine - line);
+                    return curDist < bestDist ? n : best;
+                });
+                nodes = [closest];
+            }
+            const node = nodes[0];
+            if (!node) {
+                console.log(chalk.yellow(`Could not resolve symbol "${symbol}" to a specific code entity.`));
+                return;
+            }
+            // Open Spec database
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const { findSpecsByCodeSymbol } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
+            const { initSpecSchema, runSpecMigrations, getCurrentSpecVersion, CURRENT_SPEC_SCHEMA_VERSION } = await Promise.resolve().then(() => __importStar(require('../spec/db/schema')));
+            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            if (!fs.existsSync(dbPath)) {
+                console.log(chalk.yellow(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`));
+                return;
+            }
+            const created = createDatabase(dbPath);
+            db = created.db;
+            initSpecSchema(db);
+            const currentVersion = getCurrentSpecVersion(db);
+            if (currentVersion < CURRENT_SPEC_SCHEMA_VERSION) {
+                runSpecMigrations(db, currentVersion);
+            }
+            const topKRaw = parseInt(options.topK || '10', 10);
+            const topK = Math.max(1, Math.min(isNaN(topKRaw) ? 10 : topKRaw, 50));
+            console.log(chalk.dim(`Resolved: ${node.name} (${node.kind}) in ${node.filePath}:${node.startLine}-${node.endLine}`));
+            const result = findSpecsByCodeSymbol(db, {
+                name: node.name,
+                qualifiedName: node.qualifiedName,
+                kind: node.kind,
+                filePath: node.filePath,
+                startLine: node.startLine,
+                endLine: node.endLine,
+            }, topK);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    symbol,
+                    entity: {
+                        name: node.name,
+                        qualifiedName: node.qualifiedName,
+                        kind: node.kind,
+                        filePath: node.filePath,
+                        startLine: node.startLine,
+                        endLine: node.endLine,
+                    },
+                    matched_count: result.matches.length,
+                    total_candidates: result.totalCandidates,
+                    matches: result.matches.map((m) => ({
+                        spec_id: m.spec.id,
+                        title: m.spec.title,
+                        status: m.spec.status,
+                        version: m.spec.version,
+                        file_path: m.spec.filePath,
+                        score: Math.round(m.score * 1000) / 1000,
+                        score_detail: {
+                            file_path: Math.round(m.scoreDetail.filePathScore * 1000) / 1000,
+                            content: Math.round(m.scoreDetail.contentScore * 1000) / 1000,
+                            name: Math.round(m.scoreDetail.nameScore * 1000) / 1000,
+                            recency: Math.round(m.scoreDetail.recencyScore * 1000) / 1000,
+                            line_overlap: Math.round(m.scoreDetail.overlapScore * 1000) / 1000,
+                        },
+                        fragment_count: m.fragmentCount,
+                        commit_count: m.commitCount,
+                    })),
+                }, null, 2));
+            }
+            else {
+                console.log(chalk.bold(`\n${result.matches.length} spec${result.matches.length !== 1 ? 's' : ''} matched (${result.totalCandidates} candidates):\n`));
+                for (const m of result.matches) {
+                    const scoreColor = m.score >= 0.7 ? chalk.green : m.score >= 0.4 ? chalk.yellow : chalk.red;
+                    console.log(`  ${chalk.cyan(m.spec.id.padEnd(14))} ${m.spec.title.padEnd(36)} ${scoreColor((m.score * 100).toFixed(1) + '%')}`);
+                    console.log(chalk.dim(`    fp=${m.scoreDetail.filePathScore.toFixed(2)} content=${m.scoreDetail.contentScore.toFixed(2)} name=${m.scoreDetail.nameScore.toFixed(2)} recency=${m.scoreDetail.recencyScore.toFixed(2)} overlap=${m.scoreDetail.overlapScore.toFixed(2)}`));
+                    console.log();
+                }
+                if (result.matches.length === 0) {
+                    info(`No Specs found for symbol "${symbol}". Try a more specific file path or check that specs have been mined for this project.`);
+                }
+            }
+        }
+        catch (err) {
+            error(`Trace failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        finally {
+            try {
+                await cg?.close();
+            }
+            catch { /* best effort */ }
+            try {
+                db?.close();
+            }
+            catch { /* best effort */ }
+        }
+    });
+    /**
+     * homegraph spec stats
+     */
+    specCommand
+        .command('stats')
+        .description('Show statistics about the spec knowledge graph')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (options) => {
+        let db;
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const { getSpecStats } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
+            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            if (!fs.existsSync(dbPath)) {
+                error(`Database not found at ${dbPath}. Run 'homegraph spec mine' first.`);
+                process.exit(1);
+            }
+            const created = createDatabase(dbPath);
+            db = created.db;
+            const stats = getSpecStats(db);
+            if (options.json) {
+                console.log(JSON.stringify(stats, null, 2));
+            }
+            else {
+                console.log(chalk.bold('\nSpec Knowledge Graph Stats\n'));
+                console.log(`  Specs:       ${chalk.cyan(String(stats.specCount))}`);
+                console.log(`    Active:     ${chalk.green(String(stats.activeSpecCount))}`);
+                console.log(`    Deprecated: ${chalk.yellow(String(stats.deprecatedSpecCount))}`);
+                console.log(`  Commits:     ${stats.commitCount}`);
+                console.log(`  Fragments:   ${stats.fragmentCount}`);
+                console.log(`  Relations:   ${stats.relationCount}`);
+                console.log();
+                if (stats.specCount === 0) {
+                    info("No specs yet. Run 'homegraph spec mine' to build the knowledge graph.");
+                }
+            }
+        }
+        catch (err) {
+            error(`Stats failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        finally {
+            try {
+                db?.close();
+            }
+            catch { /* best effort */ }
+        }
+    });
+    /**
+     * homegraph spec evolve
+     */
+    const evolveCommand = specCommand
+        .command('evolve')
+        .description('Self-evolve specs after code changes');
+    /**
+     * homegraph spec evolve install
+     */
+    evolveCommand
+        .command('install')
+        .description('Install a git post-commit hook that triggers spec evolution')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('-f, --force', 'Overwrite existing hook without prompting')
+        .action(async (options) => {
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            if (!isGitRepo(repoPath)) {
+                error(`Not a git repository: ${repoPath}`);
+                process.exit(1);
+            }
+            const { execFileSync } = await Promise.resolve().then(() => __importStar(require('child_process')));
+            // Resolve the absolute path to homegraph so the hook works
+            // regardless of PATH (matching Python's shutil.which("c4s")).
+            let homegraphBin;
+            try {
+                homegraphBin = execFileSync('command', ['-v', 'homegraph'], {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                }).trim();
+            }
+            catch {
+                homegraphBin = '';
+            }
+            if (!homegraphBin) {
+                error('homegraph command not found in PATH.\n' +
+                    '  Make sure homegraph is installed globally: npm install -g homegraph');
+                process.exit(1);
+            }
+            const hooksDir = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+                cwd: repoPath,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
+            }).trim();
+            const resolvedHooksDir = path.isAbsolute(hooksDir)
+                ? hooksDir
+                : path.resolve(repoPath, hooksDir);
+            fs.mkdirSync(resolvedHooksDir, { recursive: true });
+            const hookPath = path.join(resolvedHooksDir, 'post-commit');
+            if (fs.existsSync(hookPath) && !options.force) {
+                const readline = await Promise.resolve().then(() => __importStar(require('readline')));
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                const answer = await new Promise((resolve) => {
+                    rl.question(chalk.yellow('A post-commit hook already exists. Overwrite? (y/N) '), resolve);
+                });
+                rl.close();
+                if (answer.toLowerCase() !== 'y') {
+                    info('Cancelled');
+                    return;
+                }
+            }
+            // Ensure logs directory
+            fs.mkdirSync(path.join(repoPath, utils_1.SPEC_DATA_DIR, 'logs'), { recursive: true });
+            // Marker constants matching the git-hooks pattern
+            const MARKER_BEGIN = '# >>> homegraph spec evolve hook >>>';
+            const MARKER_END = '# <<< homegraph spec evolve hook <<<';
+            const hookBlock = [
+                MARKER_BEGIN,
+                '# Triggers spec self-evolution after each commit. Runs in background.',
+                '# Installed by: homegraph spec evolve install',
+                `# Logs: ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log`,
+                '# Runtime guard: skip if homegraph is not available',
+                `HOMEGRAPH_BIN="${homegraphBin}"`,
+                'if [ -x "$HOMEGRAPH_BIN" ] || command -v homegraph >/dev/null 2>&1; then',
+                '  "${HOMEGRAPH_BIN:-homegraph}" spec evolve process --path "$(pwd)" --json \\',
+                `      >> ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log 2>&1 &`,
+                'fi',
+                MARKER_END,
+            ].join('\n');
+            let content;
+            if (fs.existsSync(hookPath)) {
+                // Strip any prior marker block, then re-append the current one
+                const existing = fs.readFileSync(hookPath, 'utf8');
+                const lines = existing.split('\n');
+                const kept = [];
+                let inBlock = false;
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (trimmed === MARKER_BEGIN) {
+                        inBlock = true;
+                        continue;
+                    }
+                    if (trimmed === MARKER_END) {
+                        inBlock = false;
+                        continue;
+                    }
+                    if (!inBlock)
+                        kept.push(line);
+                }
+                const base = kept.join('\n').replace(/\s*$/, '');
+                content = base.length > 0
+                    ? `${base}\n\n${hookBlock}\n`
+                    : `#!/bin/sh\n${hookBlock}\n`;
+            }
+            else {
+                content = `#!/bin/sh\n${hookBlock}\n`;
+            }
+            fs.writeFileSync(hookPath, content);
+            fs.chmodSync(hookPath, 0o755);
+            success(`Post-commit hook installed at ${hookPath}`);
+            info(`Logs written to ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log`);
+        }
+        catch (err) {
+            error(`Hook install failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * homegraph spec evolve uninstall
+     */
+    evolveCommand
+        .command('uninstall')
+        .description('Remove the git post-commit hook installed by spec evolve')
+        .option('-p, --path <path>', 'Path to the repository')
+        .action(async (options) => {
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            if (!isGitRepo(repoPath)) {
+                error(`Not a git repository: ${repoPath}`);
+                process.exit(1);
+            }
+            const { execFileSync } = await Promise.resolve().then(() => __importStar(require('child_process')));
+            const hooksDir = execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+                cwd: repoPath,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
+            }).trim();
+            const resolvedHooksDir = path.isAbsolute(hooksDir)
+                ? hooksDir
+                : path.resolve(repoPath, hooksDir);
+            const hookPath = path.join(resolvedHooksDir, 'post-commit');
+            if (!fs.existsSync(hookPath)) {
+                info('No post-commit hook found — nothing to uninstall.');
+                return;
+            }
+            const MARKER_BEGIN = '# >>> homegraph spec evolve hook >>>';
+            const MARKER_END = '# <<< homegraph spec evolve hook <<<';
+            const existing = fs.readFileSync(hookPath, 'utf8');
+            const lines = existing.split('\n');
+            const kept = [];
+            let inBlock = false;
+            let removedBlock = false;
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed === MARKER_BEGIN) {
+                    inBlock = true;
+                    removedBlock = true;
+                    continue;
+                }
+                if (trimmed === MARKER_END) {
+                    inBlock = false;
+                    continue;
+                }
+                if (!inBlock)
+                    kept.push(line);
+            }
+            if (!removedBlock) {
+                info('No homegraph spec evolve hook block found — nothing to uninstall.');
+                return;
+            }
+            const remaining = kept.join('\n').trim();
+            if (remaining.length === 0 || /^#!\/bin\/sh\s*$/.test(remaining)) {
+                // Hook only contained our block (or just a shebang) — delete entirely
+                fs.unlinkSync(hookPath);
+                success(`Removed post-commit hook at ${hookPath}`);
+            }
+            else {
+                fs.writeFileSync(hookPath, remaining + '\n');
+                success(`Removed spec evolve hook block from ${hookPath} (user content preserved)`);
+            }
+        }
+        catch (err) {
+            error(`Hook uninstall failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * homegraph spec evolve process
+     */
+    evolveCommand
+        .command('process')
+        .description('Process commits through the spec self-evolve pipeline since last evolve')
+        .option('-p, --path <path>', 'Path to the repository')
+        .option('--db-path <path>', 'Path to the SQLite database file')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (options) => {
+        let db;
+        try {
+            const repoPath = resolveSpecProjectPath(options.path);
+            const { createDatabase } = await Promise.resolve().then(() => __importStar(require('../db/sqlite-adapter')));
+            const { resolveDbPath } = await Promise.resolve().then(() => __importStar(require('../spec/utils')));
+            const { initSpecSchema } = await Promise.resolve().then(() => __importStar(require('../spec/db/schema')));
+            const { loadSpecConfig } = await Promise.resolve().then(() => __importStar(require('../spec/config')));
+            const { runBatchEvolvePipeline } = await Promise.resolve().then(() => __importStar(require('../spec/evolve/pipeline')));
+            const { isGitRepo } = await Promise.resolve().then(() => __importStar(require('../spec/mining/git-scanner')));
+            if (!isGitRepo(repoPath)) {
+                error(`Not a git repository: ${repoPath}`);
+                process.exit(1);
+            }
+            const dbPath = resolveDbPath(repoPath, options.dbPath);
+            const created = createDatabase(dbPath);
+            db = created.db;
+            initSpecSchema(db);
+            const config = loadSpecConfig(repoPath);
+            const llmConfig = config.llm;
+            if (!llmConfig) {
+                warn('LLM not configured — Path B (LLM-based spec evolution) will be skipped.');
+                warn('Only Path A (commit message scope → GENERATE) will be processed.');
+                warn('Configure LLM in .homegraph/commit4spec/configs.json for full functionality:\n' +
+                    '{\n' +
+                    '  "llm": {\n' +
+                    '    "provider": "openai",\n' +
+                    '    "apiKeyEnv": "OPENAI_API_KEY",\n' +
+                    '    "model": "gpt-4o"\n' +
+                    '  }\n' +
+                    '}');
+            }
+            const result = await runBatchEvolvePipeline(repoPath, db, llmConfig ?? undefined);
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                if (result.commitsProcessed === 0) {
+                    console.log(chalk.green('No new commits to evolve.'));
+                    console.log(`Last evolved commit: ${result.fromCommit ? result.fromCommit.slice(0, 7) : 'none'}`);
+                    console.log(`Current HEAD: ${result.toCommit.slice(0, 7)}`);
+                }
+                else {
+                    console.log(chalk.bold(`Evolve complete: ${result.commitsProcessed} commit(s) processed`));
+                    console.log(`Range: ${result.fromCommit ? result.fromCommit.slice(0, 7) : 'none'} → ${result.toCommit.slice(0, 7)}`);
+                    if (result.metaUpdated) {
+                        console.log(chalk.green(`meta.json updated (currentCommitID = ${result.toCommit.slice(0, 7)})`));
+                    }
+                    else if (result.failures > 0) {
+                        console.log(chalk.yellow(`⚠ meta.json NOT updated — ${result.failures} commit(s) failed`));
+                    }
+                    else if (result.skippedCommits > 0) {
+                        console.log(chalk.yellow('⚠ meta.json NOT updated — all commits were skipped (no Path A match, no LLM)'));
+                    }
+                    else {
+                        console.log(chalk.yellow('⚠ meta.json NOT updated'));
+                    }
+                    // Show per-commit summary
+                    for (const r of result.perCommitResults) {
+                        let prefix;
+                        if (r.skipped) {
+                            prefix = chalk.yellow('  ⚠');
+                        }
+                        else {
+                            prefix = r.persisted ? chalk.green('  ✓') : chalk.red('  ✗');
+                        }
+                        console.log(`${prefix} ${r.commitHash.slice(0, 7)}`);
+                        if (r.skipped) {
+                            console.log(`    skipped: ${r.skipReason}`);
+                        }
+                        if (r.isLogicChange) {
+                            console.log(`    logic change: ${r.logicCheckReason}`);
+                        }
+                        if (r.generateSpecId) {
+                            console.log(`    Path A - GENERATE ${r.generateSpecId}`);
+                        }
+                        for (const ev of r.evolvedSpecs) {
+                            console.log(`    ${ev.specId}: ${ev.action}`);
+                        }
+                    }
+                    // Aggregate summary
+                    const totalFragments = result.perCommitResults.reduce((s, r) => s + r.fragmentsCount, 0);
+                    const totalRelations = result.perCommitResults.reduce((s, r) => s + r.relationsCreated, 0);
+                    if (result.skippedCommits > 0) {
+                        console.log(chalk.yellow(`${result.skippedCommits} commit(s) skipped — no LLM configured, did not match Path A`));
+                    }
+                    if (result.failures > 0) {
+                        console.log(chalk.red(`${result.failures} commit(s) failed — see details above`));
+                    }
+                    console.log(`Summary: fragments=${totalFragments}, relations=${totalRelations}`);
+                }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('No meta.json found')) {
+                error("No meta.json found. Run 'homegraph spec mine' first.");
+            }
+            else {
+                error(`Evolve failed: ${message}`);
+            }
+            process.exit(1);
+        }
+        finally {
+            try {
+                db?.close();
+            }
+            catch { /* best effort */ }
+        }
+    });
     /**
      * homegraph telemetry [on|off|status]
      */
@@ -1942,6 +2785,63 @@ function main() {
         console.log(`Config:     ${s.configPath}`);
         console.log(chalk.dim(`\nExactly what is collected (and never collected): ${telemetry_1.TELEMETRY_DOCS}\n`));
     });
+    /**
+     * homegraph index-api <input> [version]
+     * Build a standalone OHOS API database from command-line-tools SDK.
+     */
+    program
+        .command('index-api <input> [version]')
+        .description('Index OpenHarmony SDK API declarations into a standalone SQLite db')
+        .option('-o, --output <path>', 'Output database path')
+        .option('-q, --quiet', 'Suppress progress output')
+        .action(async (input, versionArg, options) => {
+        try {
+            const { resolveOhosSdkInput, ohosApiDbFilename, indexOhosApiDb } = await Promise.resolve().then(() => __importStar(require('../extraction/languages/arkts')));
+            const resolved = resolveOhosSdkInput({
+                inputPath: input,
+                versionOverride: versionArg,
+            });
+            const outputPath = options.output ?? path.join(process.cwd(), ohosApiDbFilename(resolved.version));
+            if (!options.quiet) {
+                info(`SDK home: ${resolved.sdkHome}`);
+                info(`API version: ${resolved.version}`);
+                info(`Output: ${outputPath}`);
+            }
+            const result = await indexOhosApiDb({
+                sdkHome: resolved.sdkHome,
+                version: resolved.version,
+                outputPath,
+                onProgress: options.quiet
+                    ? undefined
+                    : (progress) => {
+                        if (progress.phase === 'arkts-batch') {
+                            const label = progress.subphase === 'scene' ? 'Scene' : 'Persist';
+                            process.stdout.write(`\r${label}: ${progress.current}/${progress.total} ${progress.currentFile ?? ''}`.padEnd(80));
+                        }
+                    },
+            });
+            resolved.cleanup?.();
+            if (!options.quiet) {
+                process.stdout.write('\n');
+                if (result.success) {
+                    info(`Indexed ${result.filesIndexed} SDK files → ${result.nodesCreated} nodes, ${result.edgesCreated} edges (${result.durationMs}ms)`);
+                }
+                else {
+                    error('OHOS API indexing failed');
+                    for (const err of result.errors.filter((e) => e.severity === 'error')) {
+                        error(err.message);
+                    }
+                }
+            }
+            if (!result.success) {
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     /**
      * homegraph upgrade [version]
      *