homegraph 1.1.3 → 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) {
@@ -60,14 +60,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
-const utils_1 = require("../spec/utils");
 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.
@@ -416,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
@@ -512,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);
@@ -620,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,
-                });
+            finally {
+                supervision.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();
-            }
-            printIndexResult(clack, result, projectPath);
-            await recordIndexTelemetry(cg, result);
-            if (!result.success) {
-                process.exit(1);
-            }
-            clack.outro('Done');
-            cg.destroy();
         }
         catch (err) {
             error(`Failed to index: ${err instanceof Error ? err.message : String(err)}`);
@@ -763,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();
@@ -788,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,
@@ -842,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) {
@@ -918,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}`));
@@ -1019,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
@@ -1043,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 });
@@ -1078,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)')
@@ -1093,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)) {
@@ -1114,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;
             }
@@ -1850,6 +1915,92 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * homegraph install
+     */
+    program
+        .command('install')
+        .description('Install homegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
+        .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt')
+        .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
+        .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
+        .option('--no-permissions', 'Skip writing the auto-allow permissions list (Claude Code only)')
+        .option('--print-config <id>', 'Print MCP config snippet for the named agent and exit (no file writes)')
+        .action(async (opts) => {
+        if (opts.printConfig) {
+            const { getTarget, listTargetIds } = await Promise.resolve().then(() => __importStar(require('../installer/targets/registry')));
+            const target = getTarget(opts.printConfig);
+            if (!target) {
+                const known = listTargetIds().join(', ');
+                error(`Unknown target "${opts.printConfig}". Known: ${known}.`);
+                process.exit(1);
+            }
+            const loc = (opts.location === 'local' ? 'local' : 'global');
+            process.stdout.write(target.printConfig(loc));
+            return;
+        }
+        const { runInstallerWithOptions } = await Promise.resolve().then(() => __importStar(require('../installer')));
+        if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
+            error(`--location must be "global" or "local" (got "${opts.location}").`);
+            process.exit(1);
+        }
+        try {
+            // Commander's `--no-permissions` makes `opts.permissions === false`;
+            // omitting the flag leaves it `true` (the positive-form default).
+            // We MUST treat the default-true as "user did not override — let
+            // the orchestrator prompt" and only forward an explicit `false`
+            // (or `true` when --yes implies it). Otherwise the auto-allow
+            // prompt is silently skipped on every interactive run.
+            const explicitNoPermissions = opts.permissions === false;
+            const autoAllow = explicitNoPermissions
+                ? false
+                : opts.yes
+                    ? true
+                    : undefined;
+            await runInstallerWithOptions({
+                target: opts.target,
+                location: opts.location,
+                autoAllow,
+                yes: opts.yes,
+            });
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    /**
+     * homegraph uninstall
+     *
+     * Inverse of `install`. Removes the homegraph MCP server entry,
+     * instructions block, and permissions from every agent (or a
+     * `--target` subset). Prompts global-vs-local when not given. Does NOT
+     * delete the `.homegraph/` index — that's `homegraph uninit`.
+     */
+    program
+        .command('uninstall')
+        .description('Remove homegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
+        .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "all". Default: all')
+        .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
+        .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all')
+        .action(async (opts) => {
+        const { runUninstaller } = await Promise.resolve().then(() => __importStar(require('../installer')));
+        if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
+            error(`--location must be "global" or "local" (got "${opts.location}").`);
+            process.exit(1);
+        }
+        try {
+            await runUninstaller({
+                target: opts.target,
+                location: opts.location,
+                yes: opts.yes,
+            });
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     // =============================================================================
     // Spec commands (Commit4Spec knowledge graph)
     // =============================================================================
@@ -1926,7 +2077,6 @@ function main() {
             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 { initSpecSchema } = await Promise.resolve().then(() => __importStar(require('../spec/db/schema')));
             const { searchAndGetContext } = await Promise.resolve().then(() => __importStar(require('../spec/graph/queries')));
             const dbPath = resolveDbPath(repoPath, options.dbPath);
             if (!fs.existsSync(dbPath)) {
@@ -1935,7 +2085,6 @@ function main() {
             }
             const created = createDatabase(dbPath);
             db = created.db;
-            initSpecSchema(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);
@@ -1996,6 +2145,298 @@ function main() {
             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
      */
@@ -2069,8 +2510,12 @@ function main() {
                 '# 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`,
-                `"${homegraphBin}" spec evolve process --path "$(pwd)" --json \\`,
-                `    >> ${utils_1.SPEC_DATA_DIR}/logs/evolve-hook.log 2>&1 &`,
+                '# 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;
@@ -2111,15 +2556,85 @@ function main() {
             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 a commit through the spec self-evolve pipeline')
+        .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('--commit-hash <hash>', 'Commit hash to process (default: HEAD)', 'HEAD')
         .option('-j, --json', 'Output as JSON')
         .action(async (options) => {
         let db;
@@ -2129,7 +2644,7 @@ function main() {
             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 { runEvolvePipeline } = await Promise.resolve().then(() => __importStar(require('../spec/evolve/pipeline')));
+            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}`);
@@ -2141,25 +2656,77 @@ function main() {
             initSpecSchema(db);
             const config = loadSpecConfig(repoPath);
             const llmConfig = config.llm;
-            const commitHash = options.commitHash || 'HEAD';
-            const result = await runEvolvePipeline(repoPath, db, commitHash, llmConfig);
+            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 {
-                console.log(chalk.bold(`Processing commit ${result.commitHash.slice(0, 7)}`));
-                console.log(`Is logic change: ${result.isLogicChange ? chalk.green('✅ yes') : chalk.red('❌ no')}`);
-                console.log(`Reason: ${result.logicCheckReason}`);
-                if (result.generateSpecId) {
-                    console.log(chalk.cyan(`Link Path A - GENERATE ${result.generateSpecId}`));
+                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)}`);
                 }
-                if (result.evolvedSpecs.length > 0) {
-                    console.log(chalk.cyan(`Cycle Path B - Self-evolve (${result.affectedSpecCount} affected)`));
-                    for (const evolved of result.evolvedSpecs) {
-                        console.log(`  ${evolved.specId}: ${evolved.action}`);
+                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}`);
                 }
-                console.log(`Summary: fragments=${result.fragmentsCount}, relations=${result.relationsCreated}`);
             }
         }
         catch (err) {
@@ -2179,92 +2746,6 @@ function main() {
             catch { /* best effort */ }
         }
     });
-    /**
-     * homegraph install
-     */
-    program
-        .command('install')
-        .description('Install homegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
-        .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt')
-        .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
-        .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
-        .option('--no-permissions', 'Skip writing the auto-allow permissions list (Claude Code only)')
-        .option('--print-config <id>', 'Print MCP config snippet for the named agent and exit (no file writes)')
-        .action(async (opts) => {
-        if (opts.printConfig) {
-            const { getTarget, listTargetIds } = await Promise.resolve().then(() => __importStar(require('../installer/targets/registry')));
-            const target = getTarget(opts.printConfig);
-            if (!target) {
-                const known = listTargetIds().join(', ');
-                error(`Unknown target "${opts.printConfig}". Known: ${known}.`);
-                process.exit(1);
-            }
-            const loc = (opts.location === 'local' ? 'local' : 'global');
-            process.stdout.write(target.printConfig(loc));
-            return;
-        }
-        const { runInstallerWithOptions } = await Promise.resolve().then(() => __importStar(require('../installer')));
-        if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
-            error(`--location must be "global" or "local" (got "${opts.location}").`);
-            process.exit(1);
-        }
-        try {
-            // Commander's `--no-permissions` makes `opts.permissions === false`;
-            // omitting the flag leaves it `true` (the positive-form default).
-            // We MUST treat the default-true as "user did not override — let
-            // the orchestrator prompt" and only forward an explicit `false`
-            // (or `true` when --yes implies it). Otherwise the auto-allow
-            // prompt is silently skipped on every interactive run.
-            const explicitNoPermissions = opts.permissions === false;
-            const autoAllow = explicitNoPermissions
-                ? false
-                : opts.yes
-                    ? true
-                    : undefined;
-            await runInstallerWithOptions({
-                target: opts.target,
-                location: opts.location,
-                autoAllow,
-                yes: opts.yes,
-            });
-        }
-        catch (err) {
-            error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    });
-    /**
-     * homegraph uninstall
-     *
-     * Inverse of `install`. Removes the homegraph MCP server entry,
-     * instructions block, and permissions from every agent (or a
-     * `--target` subset). Prompts global-vs-local when not given. Does NOT
-     * delete the `.homegraph/` index — that's `homegraph uninit`.
-     */
-    program
-        .command('uninstall')
-        .description('Remove homegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, DevEco Code, CodeBuddy, Hermes Agent)')
-        .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "all". Default: all')
-        .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
-        .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all')
-        .action(async (opts) => {
-        const { runUninstaller } = await Promise.resolve().then(() => __importStar(require('../installer')));
-        if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
-            error(`--location must be "global" or "local" (got "${opts.location}").`);
-            process.exit(1);
-        }
-        try {
-            await runUninstaller({
-                target: opts.target,
-                location: opts.location,
-                yes: opts.yes,
-            });
-        }
-        catch (err) {
-            error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    });
     /**
      * homegraph telemetry [on|off|status]
      */
@@ -2304,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]
      *