homegraph 1.5.2 → 1.5.4

package/dist/bin/homegraph.js

@@ -71,7 +71,7 @@ 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");
+const addon_commands_1 = require("./addon-commands");
 // Lazy-load heavy modules (HomeGraph, runInstaller) to keep CLI startup fast.
 async function loadHomeGraph() {
     try {
@@ -90,25 +90,13 @@ async function loadHomeGraph() {
 // which fails for ESM-only packages. This bypasses the transformation.
 // eslint-disable-next-line @typescript-eslint/no-implied-eval
 const importESM = new Function('specifier', 'return import(specifier)');
-// Block HomeGraph on Node.js 25.x — V8's turboshaft WASM JIT has a Zone
-// allocator bug that reliably crashes when compiling tree-sitter
-// grammars (see #54, #81, #140). The previous behaviour was a soft
-// console.warn that scrolls off-screen before the OOM crash 30 seconds
-// later, leading to a steady stream of "what is this OOM" reports.
-// Hard-exit before any WASM work; allow override via env var for users
-// who patched V8 themselves or want to test a future fix.
-const nodeVersion = process.versions.node;
-const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
-if (nodeMajor >= 25) {
-    process.stderr.write((0, node_version_check_1.buildNode25BlockBanner)(nodeVersion) + '\n');
-    if (!process.env.HOMEGRAPH_ALLOW_UNSAFE_NODE) {
-        process.exit(1);
-    }
-    // Override active — banner shown for visibility, continuing.
-}
 // Enforce the supported Node floor. `engines` in package.json only *warns* on
 // install (unless engine-strict), so hard-block here to actually keep users off
-// unsupported versions. Mirrors the 25+ block above. See package.json `engines`.
+// unsupported versions. See package.json `engines` and ./node-version-check.
+// Node ≥22 WASM Zone OOM is mitigated by --liftoff-only relaunch below — not by
+// blocking majors (Node 25+ is supported when that flag is applied).
+const nodeVersion = process.versions.node;
+const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
 if (nodeMajor < node_version_check_1.MIN_NODE_MAJOR) {
     process.stderr.write((0, node_version_check_1.buildNodeTooOldBanner)(nodeVersion) + '\n');
     if (!process.env.HOMEGRAPH_ALLOW_UNSAFE_NODE) {
@@ -184,30 +172,6 @@ function main() {
         .name('homegraph')
         .description('Code intelligence and knowledge graph for any codebase')
         .version(packageJson.version);
-    // Anonymous usage telemetry (see TELEMETRY.md): record the invoked subcommand
-    // NAME only — never arguments or paths. Counts buffer locally; network sends
-    // piggyback on commands that run long anyway (quick commands only append to
-    // the local buffer at exit, costing nothing).
-    // install/uninstall are absent on purpose: the installer flushes at its own
-    // end, AFTER its consent prompt — a flush here would fire the first-run
-    // notice before the user ever sees the toggle.
-    const TELEMETRY_FLUSH_COMMANDS = new Set(['init', 'uninit', 'index', 'sync', 'upgrade']);
-    program.hook('preAction', (_thisCommand, actionCommand) => {
-        try {
-            // The detached daemon re-invokes `serve --mcp` internally — not a user action.
-            if (process.env.HOMEGRAPH_DAEMON_INTERNAL)
-                return;
-            const name = actionCommand.name();
-            if (name === 'telemetry')
-                return; // managing telemetry is not usage
-            (0, telemetry_1.getTelemetry)().recordUsage('cli_command', name, true);
-            if (TELEMETRY_FLUSH_COMMANDS.has(name))
-                (0, telemetry_1.getTelemetry)().maybeFlush();
-        }
-        catch {
-            /* telemetry must never break the CLI */
-        }
-    });
     // =============================================================================
     // Helper Functions
     // =============================================================================
@@ -473,15 +437,6 @@ function main() {
         }
         fs.writeFileSync(logPath, lines.join('\n') + '\n');
     }
-    /**
-     * Telemetry for a completed full index (see TELEMETRY.md). The bounded flush
-     * keeps init/index responsive (these commands just ran for seconds anyway)
-     * while delivering the event promptly.
-     */
-    async function recordIndexTelemetry(cg, result) {
-        (0, telemetry_1.recordIndexEvent)(cg, result);
-        await (0, telemetry_1.getTelemetry)().flushNow();
-    }
     // =============================================================================
     // Commands
     // =============================================================================
@@ -550,7 +505,6 @@ function main() {
                 supervision.stop();
             }
             printIndexResult(clack, result, projectPath);
-            await recordIndexTelemetry(cg, result);
             try {
                 const { offerWatchFallback } = await Promise.resolve().then(() => __importStar(require('../installer')));
                 await offerWatchFallback(clack, projectPath);
@@ -604,13 +558,6 @@ function main() {
             }
             catch { /* non-fatal */ }
             success(`Removed HomeGraph from ${projectPath}`);
-            // Churn signal — and flush now, since after an uninit there may be no
-            // "next run" to deliver it.
-            try {
-                (0, telemetry_1.getTelemetry)().recordLifecycle('uninstall', {});
-                await (0, telemetry_1.getTelemetry)().flushNow();
-            }
-            catch { /* non-fatal */ }
         }
         catch (err) {
             error(`Failed to uninitialize: ${err instanceof Error ? err.message : String(err)}`);
@@ -682,7 +629,6 @@ function main() {
                     await progress.stop();
                 }
                 printIndexResult(clack, result, projectPath);
-                await recordIndexTelemetry(cg, result);
                 if (!result.success) {
                     process.exit(1);
                 }
@@ -715,7 +661,7 @@ function main() {
                 process.exit(1);
             }
             const { default: HomeGraph } = await loadHomeGraph();
-            const cg = await HomeGraph.open(projectPath);
+            const cg = await HomeGraph.open(projectPath, { sources: 'both' });
             if (options.quiet) {
                 await cg.sync();
                 cg.destroy();
@@ -809,6 +755,7 @@ function main() {
                     nodeCount: stats.nodeCount,
                     edgeCount: stats.edgeCount,
                     dbSizeBytes: stats.dbSizeBytes,
+                    walSizeBytes: stats.walSizeBytes,
                     backend,
                     journalMode,
                     nodesByKind: stats.nodesByKind,
@@ -824,6 +771,7 @@ function main() {
                     ohosApi: ohosApi
                         ? { version: ohosApi.version, packageName: ohosApi.packageName, dbPath: ohosApi.dbPath }
                         : null,
+                    graphSources: cg.getGraphSources(),
                     index: {
                         state: indexState,
                         builtWithVersion: buildInfo.version,
@@ -848,6 +796,19 @@ function main() {
             console.log(`  Nodes:     ${formatNumber(stats.nodeCount)}`);
             console.log(`  Edges:     ${formatNumber(stats.edgeCount)}`);
             console.log(`  DB Size:   ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`);
+            // Surface the WAL sidecar (#1431): a WAL that dwarfs the DB at rest is
+            // the killed-session leak — invisible before this line, it only showed
+            // up as a mysteriously full disk. open() above already kicked off the
+            // automatic heal for the oversized case.
+            if (stats.walSizeBytes > 0) {
+                const { WAL_HEAL_THRESHOLD_BYTES } = await Promise.resolve().then(() => __importStar(require('../db/index')));
+                const oversized = stats.walSizeBytes > Math.max(WAL_HEAL_THRESHOLD_BYTES, stats.dbSizeBytes);
+                const walLabel = `${(stats.walSizeBytes / 1024 / 1024).toFixed(2)} MB`;
+                console.log(`  WAL Size:  ${oversized ? chalk.yellow(walLabel) : walLabel}`);
+                if (oversized) {
+                    warn('The write-ahead log is larger than the database — killed sessions left it behind. It is reclaimed automatically on open; if it persists across runs, another live HomeGraph process is holding it.');
+                }
+            }
             // Prefer node:sqlite → better-sqlite3; wasm is last-resort (no WAL).
             const backendLabel = backend === 'node-sqlite' ? chalk.green('node-sqlite')
                 : backend === 'native' ? chalk.green('native (better-sqlite3)')
@@ -857,6 +818,7 @@ function main() {
                 ? chalk.green('wal')
                 : chalk.yellow(`${journalMode || 'unknown'} ${(0, glyphs_1.getGlyphs)().dash} WAL inactive; reads can block on writes`);
             console.log(`  Journal:   ${journalLabel}`);
+            console.log(`  Sources:   ${cg.getGraphSources()} (project index / OHOS SDK API)`);
             console.log();
             // Node breakdown
             console.log(chalk.bold('Nodes by Kind:'));
@@ -1441,75 +1403,102 @@ function main() {
         });
     });
     /**
-     * homegraph serve
+     * homegraph serve / homegraph serve mcp
+     *
+     * Preferred: `homegraph serve mcp`
+     * Legacy (still supported): `homegraph serve --mcp`
+     *
+     * Hidden from `--help`: this is the stdio entry point an AI agent launches
+     * for itself (the installer wires it into every agent's MCP config), not a
+     * command a human runs. It still works when invoked — hiding only removes it
+     * from the listing. See the interactive-TTY guard in `runServeMcp`, which
+     * explains this to anyone who runs it by hand.
      */
-    program
-        // Hidden from `--help`: this is the stdio entry point an AI agent launches
-        // for itself (the installer wires `args: ['serve','--mcp']` into every
-        // agent's MCP config), not a command a human runs. It still works when
-        // invoked — hiding only removes it from the listing. See the interactive-TTY
-        // guard below, which explains this to anyone who runs it by hand.
-        .command('serve', { hidden: true })
-        .description('Start HomeGraph as an MCP server for AI assistants')
-        .option('-p, --path <path>', 'Project path (optional for MCP mode, uses rootUri from client)')
-        .option('--mcp', 'Run as MCP server (stdio transport)')
-        .option('--no-watch', 'Disable the file watcher (no auto-sync; useful on slow filesystems like WSL2 /mnt drives)')
-        .action(async (options) => {
+    async function runServeMcp(options) {
         const projectPath = options.path ? resolveProjectPath(options.path) : undefined;
         // Commander sets watch=false when --no-watch is passed. Route it through
         // the same env-var chokepoint the watcher and MCP server already honor.
         if (options.watch === false) {
             process.env.HOMEGRAPH_NO_WATCH = '1';
         }
+        // Spec 0005: resolve --sources over HOMEGRAPH_SOURCES, then stamp env so
+        // detached daemons and in-process opens share the same mode.
+        const { resolveGraphSources, applyGraphSourcesToEnv, GRAPH_SOURCES_MODES } = await Promise.resolve().then(() => __importStar(require('../graph-sources')));
         try {
-            if (options.mcp) {
-                // `serve --mcp` is the stdio MCP server an AI agent launches for itself,
-                // not a command to run by hand. A human in a terminal would otherwise
-                // see it hang waiting for JSON-RPC on stdin, which reads as broken. If
-                // stdin is an interactive TTY, explain instead of hanging. The agent's
-                // pipe and the detached daemon both have a non-TTY stdin, so this only
-                // ever fires for a person who typed it.
-                if (process.stdin.isTTY && !process.env.HOMEGRAPH_DAEMON_INTERNAL) {
-                    console.error(chalk.bold('\nHomeGraph MCP server\n'));
-                    console.error("This is the MCP server your AI agent (Claude Code, Cursor, Codex, opencode, …)");
-                    console.error("starts automatically — you don't run it yourself.");
-                    console.error(`\nIt's already wired up by ${chalk.cyan('homegraph install')}. To check on things:`);
-                    console.error(`  ${chalk.cyan('homegraph status')}   ${chalk.dim('— is this project indexed and healthy?')}`);
-                    console.error(`  ${chalk.cyan('homegraph daemon')}   ${chalk.dim('— list or stop background MCP servers')}`);
-                    console.error(chalk.dim('\n(Running it directly only does something when an MCP client drives it over stdin.)'));
-                    return;
-                }
-                // Start MCP server - it handles initialization lazily based on rootUri from client
-                const { MCPServer } = await Promise.resolve().then(() => __importStar(require('../mcp/index')));
-                const server = new MCPServer(projectPath);
-                await server.start();
-                // Server will run until terminated
-            }
-            else {
-                // Default: show info about MCP mode.
-                // Use stderr so stdout stays clean for any piped/stdio usage.
-                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(`
+            const mode = resolveGraphSources(options.sources);
+            applyGraphSourcesToEnv(mode);
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : String(err));
+            error(`Valid values: ${GRAPH_SOURCES_MODES.join(', ')}`);
+            process.exit(1);
+        }
+        // The stdio MCP server an AI agent launches for itself — not a command to
+        // run by hand. A human in a terminal would otherwise see it hang waiting
+        // for JSON-RPC on stdin. The agent's pipe and the detached daemon both
+        // have a non-TTY stdin, so this only ever fires for a person who typed it.
+        if (process.stdin.isTTY && !process.env.HOMEGRAPH_DAEMON_INTERNAL) {
+            console.error(chalk.bold('\nHomeGraph MCP server\n'));
+            console.error("This is the MCP server your AI agent (Claude Code, Cursor, Codex, opencode, …)");
+            console.error("starts automatically — you don't run it yourself.");
+            console.error(`\nIt's already wired up by ${chalk.cyan('homegraph install')}. To check on things:`);
+            console.error(`  ${chalk.cyan('homegraph status')}   ${chalk.dim('— is this project indexed and healthy?')}`);
+            console.error(`  ${chalk.cyan('homegraph daemon')}   ${chalk.dim('— list or stop background MCP servers')}`);
+            console.error(chalk.dim('\n(Running it directly only does something when an MCP client drives it over stdin.)'));
+            return;
+        }
+        const { MCPServer } = await Promise.resolve().then(() => __importStar(require('../mcp/index')));
+        const server = new MCPServer(projectPath);
+        await server.start();
+    }
+    function printServeUsage() {
+        // Use stderr so stdout stays clean for any piped/stdio usage.
+        console.error(chalk.bold('\nHomeGraph MCP Server\n'));
+        console.error(chalk.blue((0, glyphs_1.getGlyphs)().info) + ' Start with: ' + chalk.cyan('homegraph serve mcp'));
+        console.error(chalk.dim('  (legacy alias also works: homegraph serve --mcp)'));
+        console.error('\nTo use with Claude Code, add to your MCP configuration:');
+        console.error(chalk.dim(`
 {
   "mcpServers": {
     "homegraph": {
       "command": "homegraph",
-      "args": ["serve", "--mcp"]
+      "args": ["serve", "mcp"]
     }
   }
 }
 `));
-                console.error('Available tools:');
-                console.error(chalk.cyan('  homegraph_explore') + '   - Primary: source of the relevant symbols for any question');
-                console.error(chalk.cyan('  homegraph_search') + '    - Search for code symbols');
-                console.error(chalk.cyan('  homegraph_callers') + '   - Find callers of a symbol');
-                console.error(chalk.cyan('  homegraph_callees') + '   - Find what a symbol calls');
-                console.error(chalk.cyan('  homegraph_impact') + '    - Analyze impact of changes');
-                console.error(chalk.cyan('  homegraph_node') + '      - Get symbol details');
-                console.error(chalk.cyan('  homegraph_files') + '     - Get project file structure');
-                console.error(chalk.cyan('  homegraph_status') + '    - Get index status');
+        console.error('Optional: --sources both|project|sdk|none (or HOMEGRAPH_SOURCES) to limit project vs OHOS SDK graphs.');
+        console.error('Available tools:');
+        console.error(chalk.cyan('  homegraph_explore') + '   - Primary: source of the relevant symbols for any question');
+        console.error(chalk.cyan('  homegraph_search') + '    - Search for code symbols');
+        console.error(chalk.cyan('  homegraph_callers') + '   - Find callers of a symbol');
+        console.error(chalk.cyan('  homegraph_callees') + '   - Find what a symbol calls');
+        console.error(chalk.cyan('  homegraph_impact') + '    - Analyze impact of changes');
+        console.error(chalk.cyan('  homegraph_node') + '      - Get symbol details');
+        console.error(chalk.cyan('  homegraph_files') + '     - Get project file structure');
+        console.error(chalk.cyan('  homegraph_status') + '    - Get index status');
+    }
+    // IMPORTANT: keep `mcp` as an argument (not a nested Commander subcommand).
+    // Nested `serve.command('mcp')` + a parent `-p/--path` made Commander 14 drop
+    // `--path` on `serve mcp --path <repo>` — the daemon then keyed off cwd, so
+    // prewarm/eval looked "timed out" while a useless daemon bound the wrong root.
+    // `spawnDetachedDaemon` also invokes `serve mcp --path <root>`; that path must
+    // stick. Legacy `serve --mcp` stays supported.
+    program
+        .command('serve', { hidden: true })
+        .description('Start HomeGraph protocol servers for AI assistants')
+        .argument('[mode]', 'Run as MCP server (stdio transport)', undefined)
+        .option('-p, --path <path>', 'Project path (optional for MCP mode, uses rootUri from client)')
+        .option('--mcp', 'Legacy alias for `serve mcp` (stdio MCP server)')
+        .option('--no-watch', 'Disable the file watcher (no auto-sync; useful on slow filesystems like WSL2 /mnt drives)')
+        .option('--sources <mode>', 'Graph sources for MCP queries: both|project|sdk|none (default both; env HOMEGRAPH_SOURCES)')
+        .action(async (mode, options) => {
+        try {
+            if (mode === 'mcp' || options.mcp) {
+                await runServeMcp(options);
+            }
+            else {
+                printServeUsage();
             }
         }
         catch (err) {
@@ -2301,7 +2290,7 @@ function main() {
                 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}`);
+                        console.log(`  ${chalk.yellow(commit.hash.slice(0, 7))} ${commit.message.split('\n', 1)[0] ?? ''}`);
                         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}]`));
@@ -2971,45 +2960,10 @@ function main() {
             catch { /* best effort */ }
         }
     });
-    /**
-     * homegraph telemetry [on|off|status]
-     */
-    program
-        .command('telemetry [action]')
-        .description('Show or change anonymous usage telemetry (status, on, off)')
-        .action((action) => {
-        const t = (0, telemetry_1.getTelemetry)();
-        if (action === 'on' || action === 'off') {
-            t.setEnabled(action === 'on', 'cli');
-            if (action === 'on') {
-                success('Telemetry enabled — anonymous usage stats only (no code, paths, or names).');
-            }
-            else {
-                success('Telemetry disabled. Buffered, unsent data was deleted.');
-            }
-            const effective = t.getStatus();
-            if (effective.decidedBy === 'DO_NOT_TRACK' || effective.decidedBy === 'HOMEGRAPH_TELEMETRY') {
-                warn(`The ${effective.decidedBy} environment variable overrides this choice — ` +
-                    `effective state right now: ${effective.enabled ? 'enabled' : 'disabled'}.`);
-            }
-            return;
-        }
-        if (action !== undefined && action !== 'status') {
-            error(`Unknown action: ${action} (expected status, on, or off)`);
-            process.exit(1);
-        }
-        const s = t.getStatus();
-        const decidedBy = {
-            DO_NOT_TRACK: 'DO_NOT_TRACK environment variable',
-            HOMEGRAPH_TELEMETRY: 'HOMEGRAPH_TELEMETRY environment variable',
-            config: 'your saved choice',
-            default: 'default',
-        };
-        console.log(`\nTelemetry: ${s.enabled ? chalk.green('enabled') : chalk.yellow('disabled')} ${chalk.dim(`(${decidedBy[s.decidedBy]})`)}`);
-        console.log(`Machine ID: ${s.machineId ?? chalk.dim('(random UUID, created on first use)')}`);
-        console.log(`Config:     ${s.configPath}`);
-        console.log(chalk.dim(`\nExactly what is collected (and never collected): ${telemetry_1.TELEMETRY_DOCS}\n`));
-    });
+    // =============================================================================
+    // Addon commands (HomeGraph addon management)
+    // =============================================================================
+    (0, addon_commands_1.registerAddonCommands)(program, { success, info, warn, error });
     /**
      * homegraph index-api <input> [version]
      * Build a standalone OHOS API database from command-line-tools SDK.
@@ -3070,9 +3024,9 @@ function main() {
     /**
      * homegraph upgrade [version]
      *
-     * Self-update, however HomeGraph was installed (bundle via install.sh/.ps1,
-     * npm-global, npx, or a source checkout). See ../upgrade for the detection and
-     * per-method upgrade logic.
+     * Self-update for npm-global / npx / source installs. A leftover standalone
+     * bundle install is detected and refused (guide the user to `npm i -g`).
+     * See ../upgrade for detection and per-method upgrade logic.
      */
     program
         .command('upgrade [version]')