graph-indexer 1.2.0 → 2.0.0

package/SECURITY.md

@@ -0,0 +1,68 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+We take the security and privacy of this project seriously. If you discover a
+security vulnerability, please do **not** open a public issue. Instead, report it
+privately by emailing the maintainer at **nicolopezdelerma@gmail.com**.
+
+Please include:
+
+- A description of the vulnerability and its impact.
+- Steps to reproduce (a minimal proof of concept if possible).
+- The affected version (`graph-indexer --version` or the `version` field in `package.json`).
+
+You can expect an initial acknowledgement within **5 business days**. Coordinated
+disclosure is appreciated — we will work with you on a fix and credit before any
+public discussion.
+
+## Supported versions
+
+Security fixes are applied to the latest published `2.x` release. Older versions
+are not maintained; please upgrade to the latest version.
+
+## Security posture
+
+graph-indexer is designed to run locally as a developer tool. Its threat model is
+shaped by a few deliberate choices:
+
+- **Air-gapped by default.** In normal operation the only outbound network call is to
+  a *local* Ollama endpoint (`OLLAMA_HOST`, default `http://localhost:11434`) for
+  embeddings. With `INDEXER_EMBEDDINGS=off`, even that call is skipped and the tool is
+  fully offline. There are no analytics, telemetry, crash reporters, or third-party API
+  calls. **One exception:** the optional in-process embedding provider
+  (`embedProvider: "local"`, or `"auto"` when no Ollama is found) downloads its model
+  weights from the Hugging Face CDN **once** on first index, then runs fully offline
+  from the local cache. Your source code is never sent anywhere — only model weights
+  are fetched. For strictly air-gapped installs, set `embedProvider` to `"ollama"` or
+  `"off"`, or pre-populate the model cache on a connected machine.
+- **No code execution.** Source files are parsed into ASTs with Tree-sitter. The
+  indexer never imports, evaluates, or runs the code it indexes. The one subprocess
+  it spawns is a local, read-only `git log` (see "git signals" below) — never the
+  indexed code.
+- **Local git signals.** At index time the indexer optionally reads the repository's
+  *local* commit log (`git log` on `MCP_PROJECT_ROOT`) to derive churn / recency /
+  co-change ranking hints. No remote is contacted and no source content leaves the
+  machine — only commit metadata (paths, timestamps) is read locally. Disable it
+  entirely with `INDEXER_GIT_SIGNALS=off`, `--no-git-signals`, or
+  `"gitSignals": false`.
+- **Path-traversal guard.** The `get_file_skeleton` MCP tool resolves and normalizes
+  the requested path and rejects anything outside `MCP_PROJECT_ROOT`. Beyond the
+  textual check it also resolves symlinks with `realpath` on both the root and the
+  target and re-verifies containment, so a symlink *inside* the project that points
+  outside it cannot be used to read arbitrary files on the host.
+- **Local artifacts only.** The index (`code-index.json`) and embeddings
+  (`code-index.embeddings.bin`) are written inside the project and are git-ignored by
+  `init`. They contain snippets of your source code — treat them with the same
+  sensitivity as the repository itself and do not commit or share them.
+- **MCP transport.** The server communicates over stdio with the local MCP client
+  (your IDE/agent). It does not open a network socket.
+
+## Operational guidance
+
+- Point `MCP_PROJECT_ROOT` only at repositories you trust and intend to index.
+- If you set `OLLAMA_HOST` to a remote host, that host will receive code snippets as
+  embedding input — only do so on a network and host you control.
+- The background watch daemon respects `.gitignore` and skips `node_modules`, build
+  output, and dot-directories, so secrets in ignored paths are not indexed. Keep
+  sensitive files git-ignored.

package/TRADEMARK.md

@@ -0,0 +1,31 @@
+# Trademark Policy
+
+This document outlines the trademark policy for the **graph-indexer** project and the **MaquinaTech** brand.
+
+While the software source code is freely available under the [MIT License](LICENSE), the trademarks, service marks, and logos associated with the project are the intellectual property of MaquinaTech. The open-source license does not grant you the right to use these trademarks in a way that suggests endorsement, affiliation, or origin.
+
+## Our Trademarks
+
+The following are trademarks of MaquinaTech:
+* **graph-indexer™**
+* **Graph Indexer™**
+* **MaquinaTech™**
+
+## Permitted Uses
+
+You may use our trademarks without prior written permission in the following cases:
+* **Descriptive Use:** To truthfully describe the origin of the software. For example, stating "This product uses graph-indexer."
+* **Compatibility:** To indicate compatibility with our project. For example, "Custom tool for graph-indexer," provided it does not confuse users into thinking it is an official tool created by us.
+* **Community Discussion:** In blog posts, tutorials, videos, and discussions about the project, provided the context is accurate and not misleading.
+
+## Restricted Uses
+
+You **may not** use our trademarks without explicit, prior written permission in the following ways:
+* **Product Naming:** You cannot name your product, commercial service, or company "graph-indexer", "Graph Indexer", or anything confusingly similar (e.g., "Graph Indexer Enterprise", "Graph-Indexer Pro", or "graph-indexer-cloud").
+* **Domain Names:** You cannot use our trademarks in a domain name (e.g., `graph-indexer-hosting.com` or `maquinatech-solutions.net`).
+* **False Endorsement:** You cannot use our trademarks in any way that implies an official affiliation, partnership, sponsorship, or endorsement by MaquinaTech.
+* **Modified Versions (Forks):** If you fork the repository and make modifications to the source code to distribute it as your own product, you must rename the project. You cannot distribute your modified version under the name "graph-indexer".
+
+## Contact and Permissions
+
+If you wish to use our trademarks in a way that is not explicitly permitted by this policy, or if you are unsure whether your intended commercial use is permitted, please contact us for written authorization.

package/cli-ui.mjs

@@ -0,0 +1,78 @@
+/**
+ * @file cli-ui.mjs
+ * @description Tiny, dependency-free console styling shared by the `graph-indexer`
+ *              CLIs (init + daemon control). ANSI colour with graceful degradation
+ *              when stdout is not a TTY or NO_COLOR is set, plus a few drawing
+ *              helpers (boxed banner, rules, status glyphs) for a consistent look.
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+
+export const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : `${s}`);
+
+export const c = {
+    bold: paint('1'),
+    dim: paint('2'),
+    red: paint('31'),
+    green: paint('32'),
+    yellow: paint('33'),
+    blue: paint('34'),
+    magenta: paint('35'),
+    cyan: paint('36'),
+};
+
+export const glyph = {
+    ok: c.green('✓'),
+    upd: c.cyan('↻'),
+    keep: c.dim('•'),
+    move: c.yellow('↪'),
+    skip: c.dim('–'),
+    warn: c.yellow('⚠'),
+    err: c.red('✗'),
+    run: c.green('●'),
+    stop: c.dim('○'),
+    arrow: c.cyan('→'),
+};
+
+export const log = (msg = '') => process.stdout.write(msg + '\n');
+
+/** A horizontal rule, capped to the terminal width so it never wraps. */
+export const rule = (width = Math.min(60, (process.stdout.columns || 80))) => c.dim('─'.repeat(Math.max(1, width)));
+
+const visibleLen = (s) => s.replace(/\x1b\[[0-9;]*m/g, '').length;
+
+/** ANSI-aware truncate to `limit` visible columns; closes any open colour + adds an ellipsis. */
+function clipVisible(s, limit) {
+    if (limit < 1) return '';
+    if (visibleLen(s) <= limit) return s;
+    let out = '', w = 0, i = 0, ansi = false;
+    while (i < s.length && w < limit - 1) {
+        if (s[i] === '\x1b') {
+            const m = s.slice(i).match(/^\x1b\[[0-9;]*m/);
+            if (m) { out += m[0]; i += m[0].length; ansi = true; continue; }
+        }
+        out += s[i++]; w++;
+    }
+    return out + (ansi ? '\x1b[0m' : '') + '…';
+}
+
+/**
+ * Draws a bordered box. ANSI escapes are stripped before measuring width so colour
+ * never breaks alignment, and the box (plus each line) is capped to the terminal
+ * width so the border stays intact on narrow terminals instead of wrapping.
+ */
+export function box(lines, { pad = 1, color = c.cyan } = {}) {
+    const maxInner = Math.max(1, (process.stdout.columns || 80) - 2); // 2 border columns
+    const shown = lines.map((line) => clipVisible(line, maxInner - pad * 2));
+    const inner = Math.min(maxInner, Math.max(...shown.map(visibleLen)) + pad * 2);
+    const top = color('╭' + '─'.repeat(inner) + '╮');
+    const bot = color('╰' + '─'.repeat(inner) + '╯');
+    const body = shown.map((line) => {
+        const gap = ' '.repeat(Math.max(0, inner - visibleLen(line) - pad));
+        return color('│') + ' '.repeat(pad) + line + gap + color('│');
+    });
+    return [top, ...body, bot].join('\n');
+}

package/config.mjs

@@ -10,32 +10,75 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { artifactPaths, CONFIG_FILE_NAME, DATA_DIR_NAME } from './layout.mjs';
 
 export const DEFAULTS = Object.freeze({
-    storage: 'memory',                 // 'memory' (default, zero-dependency) | 'sqlite'
-    embedModel: 'nomic-embed-text',
+    // 'auto' keeps the index in memory below AUTO_SQLITE_CHUNK_THRESHOLD chunks and
+    // switches to disk-backed SQLite above it. Force either with --use-sqlite /
+    // INDEXER_STORAGE. (see storage.mjs: resolveBackend / AUTO_SQLITE_CHUNK_THRESHOLD)
+    storage: 'auto',                   // 'auto' (default) | 'memory' | 'sqlite'
+    embeddings: false,                 // OFF by default — lexical + stemming need zero dependencies.
+                                       // Opt in with --embeddings or INDEXER_EMBEDDINGS=on.
+    embedProvider: 'auto',
+    // 'auto'   → Ollama (if running w/ the model) → in-process local → lexical-only
+    // 'ollama' → force Ollama daemon   (requires: ollama serve + pulled model)
+    // 'local'  → in-process Xenova     (requires: npm i @huggingface/transformers)
+    // 'mlx'    → Apple Metal GPU       (requires: npm run embed:setup:mlx; macOS only)
+    // 'off'    → lexical-only, no vectors
+    embedModel: 'nomic-embed-text',    // default Ollama embed model when embeddings are enabled.
+                                       // qwen3-embedding:4b is a documented opt-in upgrade
+                                       // (--embed-model / EMBED_MODEL), never a hardcoded default.
+    localEmbedModel: 'Xenova/all-MiniLM-L6-v2', // in-process model (optional @huggingface/transformers)
+    mlxEmbedModel: 'mlx-community/all-MiniLM-L6-v2-4bit', // MLX embedder model (provider 'mlx').
+                                       // Override with --mlx-embed-model / INDEXER_MLX_EMBED_MODEL;
+                                       // must be an mlx_embeddings-compatible sentence model.
     ollamaHost: 'http://localhost:11434',
+    llmProvider: 'ollama',               // LLM backend for enrichment, reranking, HyDE: 'ollama' | 'mlx'
+                                         // 'mlx' requires mlx_lm.server running (mlx_lm.server --model <name>)
+    mlxLmHost: 'http://localhost:8080',  // mlx_lm.server endpoint (default port 8080)
+    gitSignals: true,                  // collect local git churn/recency/co-change at index time (air-gapped)
+    gitRankBoost: 0,                   // 0..1 opt-in recency/churn weight in search_code (0 = ranking unchanged)
     enrichment: Object.freeze({
         enabled: false,
-        model: 'qwen2.5-coder:1.5b',   // small, code-aware; configurable, opt-in
+        model: 'qwen2.5-coder:1.5b',   // smallest coder model; quality sufficient for summaries.
+                                       // Opt in with --enrichment or ENRICH_MODEL=<model>.
         coreRatio: 1.0,                // 1.0 = all production files (tests/examples always excluded);
                                        // <1 bounds enrichment to the most-central share by PageRank
         maxChunks: 500,                // cap on NEW LLM calls per index run (cache accumulates across runs)
-        concurrency: 12,               // parallel Ollama requests during enrichment
+        concurrency: 4,                // parallel Ollama requests during enrichment; keep low —
+                                       // a single local model serves requests fastest one-at-a-time
+                                       // unless OLLAMA_NUM_PARALLEL + hardware allow more
+
     }),
     rerank: Object.freeze({
-        enabled: false,                // opt-in: one LLM call (~1–2 s) per natural-language query
+        enabled: false,                // opt-in: one LLM call per natural-language query
         model: 'qwen2.5-coder:7b',     // judge quality matters: 7B measured +50% semantic rank-1, 1.5B ~nil
-        topM: 8,                       // fused results shown to the judge (8 measured better than 10)
+        topM: 12,                      // candidates shown to the judge to reorder
+        poolSize: 15,                  // over-fetch depth when reranking, so a correct-but-deep
+                                       // hit can be RESCUED into top_k (then truncated to top_k)
+    }),
+    hyde: Object.freeze({
+        enabled: false,                // opt-in: query-side HyDE — one LLM call per NL query, blended into the query vector
+        model: 'qwen2.5-coder:1.5b',   // local coder model that writes the hypothetical snippet
     }),
 });
 
-/** Reads `.graph-indexer.json` from a directory, tolerating absence/corruption. */
+/**
+ * Reads the project config, tolerating absence/corruption. Looks first inside the
+ * tidy data dir (`.graph-indexer/config.json`), then falls back to the legacy
+ * root file (`.graph-indexer.json`) so pre-v1.4 projects keep working until they
+ * are migrated.
+ */
 export function loadConfigFile(root) {
-    const configPath = path.join(root, '.graph-indexer.json');
-    try {
-        if (fs.existsSync(configPath)) return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    } catch { /* malformed config is ignored — defaults apply */ }
+    const candidates = [
+        path.join(root, DATA_DIR_NAME, CONFIG_FILE_NAME),
+        path.join(root, '.graph-indexer.json'),           // legacy root config (back-compat)
+    ];
+    for (const configPath of candidates) {
+        try {
+            if (fs.existsSync(configPath)) return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        } catch { /* malformed config — try the next candidate, else defaults */ }
+    }
     return {};
 }
 
@@ -63,36 +106,85 @@ export function resolveConfig({ argv = process.argv.slice(2), env = process.env,
     const file = loadConfigFile(projectRoot);
     const fileEnrich = file.enrichment || {};
 
-    // Storage: --use-sqlite flag or "storage" key. The in-memory engine remains
-    // the default so the zero-dependency baseline is never disturbed implicitly.
-    const storage = argv.includes('--use-sqlite') ? 'sqlite'
-        : (file.storage === 'sqlite' ? 'sqlite' : DEFAULTS.storage);
+    // Storage: --use-sqlite forces SQLite; otherwise INDEXER_STORAGE / "storage" key
+    // / default 'auto' (resolved to memory-or-sqlite by chunk count at index time and
+    // by artifact presence at query time — see storage.mjs:resolveBackend).
+    const storageRaw = argv.includes('--use-sqlite') ? 'sqlite'
+        : (env.INDEXER_STORAGE || file.storage || DEFAULTS.storage);
+    const storage = ['memory', 'sqlite', 'auto'].includes(storageRaw) ? storageRaw : DEFAULTS.storage;
 
-    const enrichmentEnabled = argv.includes('--llm-enrichment')
-        || argv.includes('--enrich')
+    // Enrichment is OFF unless explicitly requested: --enrichment flag, ENRICH_MODEL
+    // env (naming a model implies enabling it), or the project config.
+    const enrichModelEnv = env.ENRICH_MODEL || undefined;
+    const enrichmentEnabled = argv.includes('--enrichment')
+        || Boolean(enrichModelEnv)
         || Boolean(fileEnrich.enabled);
 
     const ollamaHost = env.OLLAMA_HOST || file.ollamaHost || DEFAULTS.ollamaHost;
-    const embeddingsEnabled = env.INDEXER_EMBEDDINGS !== 'off';
+
+    // LLM provider for enrichment / reranking / HyDE: env > flag > config > default.
+    // 'mlx' routes generation through a local mlx_lm.server (OpenAI-compatible).
+    const llmProviderRaw = env.INDEXER_LLM_PROVIDER || flagValue(argv, '--llm-provider') || file.llmProvider || DEFAULTS.llmProvider;
+    const llmProvider = ['ollama', 'mlx'].includes(llmProviderRaw) ? llmProviderRaw : DEFAULTS.llmProvider;
+    const mlxLmHost = env.INDEXER_MLX_LM_HOST || flagValue(argv, '--mlx-lm-host') || file.mlxLmHost || DEFAULTS.mlxLmHost;
+
+    // Embeddings are OFF by default (lexical + stemming need zero dependencies).
+    // Enable with --embeddings or INDEXER_EMBEDDINGS=on; INDEXER_EMBEDDINGS=off always wins.
+    const embeddingsEnabled = env.INDEXER_EMBEDDINGS === 'off'
+        ? false
+        : (argv.includes('--embeddings') || env.INDEXER_EMBEDDINGS === 'on' || file.embeddings === true);
+
+    // Embedding provider: env > --embed-provider flag > config > default 'auto'.
+    // 'auto' prefers a running Ollama and falls back to the in-process local model
+    // (optional @huggingface/transformers) so semantic search works with no daemon.
+    const embedProvider = env.INDEXER_EMBED_PROVIDER
+        || flagValue(argv, '--embed-provider')
+        || file.embedProvider || DEFAULTS.embedProvider;
+
+    // Git signals: collection is air-gapped (local `git log` only). Disable with
+    // INDEXER_GIT_SIGNALS=off, --no-git-signals, or "gitSignals": false.
+    const gitSignals = env.INDEXER_GIT_SIGNALS === 'off' || argv.includes('--no-git-signals')
+        ? false
+        : (file.gitSignals === false ? false : DEFAULTS.gitSignals);
+    const gitRankBoostRaw = env.INDEXER_GIT_RANK_BOOST ?? flagValue(argv, '--git-rank-boost')
+        ?? (Number.isFinite(file.gitRankBoost) ? file.gitRankBoost : DEFAULTS.gitRankBoost);
+    const gitRankBoost = Math.min(1, Math.max(0, Number(gitRankBoostRaw) || 0));
+
+    const paths = artifactPaths(projectRoot);
 
     return Object.freeze({
         projectRoot,
         storage,
-        // Index artifact paths — all derive from the same stem next to the project.
-        indexPath: path.join(projectRoot, 'code-index.json'),
-        embeddingPath: path.join(projectRoot, 'code-index.embeddings.bin'),
-        sqlitePath: path.join(projectRoot, 'code-index.db'),
-        enrichmentCachePath: path.join(projectRoot, 'code-index.enrichment.json'),
+        dataDir: paths.dataDir,
+        indexPath: paths.indexPath,
+        embeddingPath: paths.embeddingPath,
+        sqlitePath: paths.sqlitePath,
+        enrichmentCachePath: paths.enrichmentCachePath,
+        gitSignalsPath: paths.gitSignalsPath,
+        pidFile: paths.pidFile,
+        logFile: paths.logFile,
 
         languages: Array.isArray(file.languages) ? file.languages : null, // null = all
 
         ollamaHost,
+        llmProvider,
+        mlxLmHost,
         embeddingsEnabled,
-        embedModel: file.embedModel || DEFAULTS.embedModel,
+        embedProvider,
+        // Embed model: --embed-model flag > EMBED_MODEL env > config > nomic default.
+        // This is the model `auto`/`ollama` providers pull (e.g. qwen3-embedding:4b).
+        embedModel: flagValue(argv, '--embed-model') || env.EMBED_MODEL || file.embedModel || DEFAULTS.embedModel,
+        localEmbedModel: file.localEmbedModel || DEFAULTS.localEmbedModel,
+        // MLX embedder model: --mlx-embed-model flag > INDEXER_MLX_EMBED_MODEL env >
+        // config > pinned MiniLM default. Passed to the Python server + stamped in meta.
+        mlxEmbedModel: flagValue(argv, '--mlx-embed-model') || env.INDEXER_MLX_EMBED_MODEL
+            || file.mlxEmbedModel || DEFAULTS.mlxEmbedModel,
+        gitSignals,
+        gitRankBoost,
 
         enrichment: Object.freeze({
             enabled: enrichmentEnabled,
-            model: flagValue(argv, '--enrich-model') || fileEnrich.model || DEFAULTS.enrichment.model,
+            model: flagValue(argv, '--enrich-model') || enrichModelEnv || fileEnrich.model || DEFAULTS.enrichment.model,
             coreRatio: Number(fileEnrich.coreRatio) > 0 ? Number(fileEnrich.coreRatio) : DEFAULTS.enrichment.coreRatio,
             maxChunks: Number(flagValue(argv, '--enrich-max')) > 0
                 ? Number(flagValue(argv, '--enrich-max'))
@@ -103,16 +195,75 @@ export function resolveConfig({ argv = process.argv.slice(2), env = process.env,
         }),
 
         rerank: Object.freeze({
-            enabled: Boolean((file.rerank || {}).enabled),
-            model: (file.rerank || {}).model || DEFAULTS.rerank.model,
+            // OFF unless requested: --rerank flag, RERANK_MODEL env (naming a model
+            // implies enabling it), or the project config.
+            enabled: argv.includes('--rerank') || Boolean(env.RERANK_MODEL) || Boolean((file.rerank || {}).enabled),
+            model: env.RERANK_MODEL || (file.rerank || {}).model || DEFAULTS.rerank.model,
             topM: Number.isInteger((file.rerank || {}).topM) ? (file.rerank || {}).topM : DEFAULTS.rerank.topM,
+            poolSize: Number.isInteger((file.rerank || {}).poolSize) ? (file.rerank || {}).poolSize : DEFAULTS.rerank.poolSize,
+        }),
+
+        hyde: Object.freeze({
+            enabled: Boolean((file.hyde || {}).enabled),
+            model: (file.hyde || {}).model || DEFAULTS.hyde.model,
         }),
     });
 }
 
-// Memoised singleton for import-time consumers (e.g. parser-utils language loading).
+// Memoised singleton for import-time consumers (e.g. parse/languages.mjs language loading).
 let _cached = null;
 export function getConfig() {
     if (!_cached) _cached = resolveConfig();
     return _cached;
 }
+
+/**
+ * Human-readable lines describing the effective configuration, printed at startup
+ * by the indexer / MCP server / daemon so users can see exactly what is running
+ * (storage backend, model names, which optional features are on).
+ *
+ * @param {object} config  Resolved config from resolveConfig().
+ * @param {object} [opts]
+ * @param {string} [opts.backend]  Concrete backend ('memory'|'sqlite') once 'auto'
+ *                                 has been resolved; defaults to config.storage.
+ * @returns {string[]}
+ */
+export function describeConfig(config, { backend = config.storage } = {}) {
+    // Show the model that the chosen provider actually loads (mlx/local use their own).
+    const provModel = config.embedProvider === 'mlx' ? config.mlxEmbedModel
+        : config.embedProvider === 'local' ? config.localEmbedModel
+            : config.embedModel;
+    const emb = config.embeddingsEnabled
+        ? `on · provider=${config.embedProvider}, model=${provModel}`
+        : 'off (lexical + stemming only)';
+    return [
+        `storage     : ${backend}`,
+        `embeddings  : ${emb}`,
+        `enrichment  : ${config.enrichment.enabled ? `on · model=${config.enrichment.model} · provider=${config.llmProvider}` : 'off'}`,
+        `reranker    : ${config.rerank.enabled ? `on · model=${config.rerank.model} · provider=${config.llmProvider}` : 'off'}`,
+        `git signals : ${config.gitSignals ? 'on' : 'off'}${config.gitRankBoost ? ` · rank boost=${config.gitRankBoost}` : ''}`,
+    ];
+}
+
+/**
+ * Operational warnings for risky / edge configurations. The transition between
+ * default and an opt-in feature must never be silent: callers print these at
+ * startup so a user who enabled enrichment-only or the reranker sees the measured
+ * trade-off before they wonder why precision moved.
+ *
+ * @param {object} config  Resolved config from resolveConfig().
+ * @returns {string[]}
+ */
+export function configNotices(config) {
+    const out = [];
+    if (config.enrichment.enabled && !config.rerank.enabled) {
+        out.push('Enrichment is most effective when paired with --rerank. Running enrichment-only may '
+            + 'regress semantic precision (measured: gin MRR 0.48→0.39 on qwen3 embeddings).');
+    }
+    if (config.rerank.enabled) {
+        out.push('Reranker improves rank-1 for Go/Python repositories (gin: 0.20→0.40) but has shown '
+            + 'regressions on JavaScript repositories (express: 0.43→0.29). Behaviour depends on '
+            + 'repository language. See README for per-language benchmark data.');
+    }
+    return out;
+}

package/daemon-ctl.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * @file daemon-ctl.mjs
+ * @description `idx-daemon` — control the graph-indexer watch daemon from the
+ *              command line (and therefore from npm scripts): start, stop,
+ *              restart, status, logs. Exactly one daemon runs per project; the
+ *              daemon self-guards via an atomic PID lock (daemon-lock.mjs), so
+ *              `start` is safe to call repeatedly and from any launcher.
+ *
+ *                idx-daemon start      Start it (no-op if already running)
+ *                idx-daemon stop       Gracefully stop it
+ *                idx-daemon restart    Stop then start
+ *                idx-daemon status     Show daemon + index state (default)
+ *                idx-daemon logs [-f]  Print recent daemon logs (-f to follow)
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+import { resolveConfig } from './config.mjs';
+import { resolveBackend } from './storage.mjs';
+import { ensureDataDir, migrateLegacyLayout } from './layout.mjs';
+import { daemonStatus, readPid, isAlive } from './daemon-lock.mjs';
+import { c, glyph, log } from './cli-ui.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DAEMON_PATH = path.join(__dirname, 'watch-daemon.mjs');
+
+const config = resolveConfig();
+const ROOT = config.projectRoot;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function relArtifact() {
+    const p = resolveBackend(config) === 'sqlite' ? config.sqlitePath : config.indexPath;
+    return path.relative(ROOT, p) || p;
+}
+
+function freshness(file) {
+    try {
+        const sec = Math.floor((Date.now() - fs.statSync(file).mtimeMs) / 1000);
+        if (sec < 60) return `${sec}s ago`;
+        if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+        if (sec < 86400) return `${Math.floor(sec / 3600)}h ago`;
+        return `${Math.floor(sec / 86400)}d ago`;
+    } catch { return 'never indexed'; }
+}
+
+function spawnDaemon() {
+    ensureDataDir(ROOT);
+    let logFd = null;
+    try { logFd = fs.openSync(config.logFile, 'a'); } catch { }
+    const child = spawn(process.execPath, [DAEMON_PATH], {
+        detached: true,
+        stdio: logFd !== null ? ['ignore', logFd, logFd] : 'ignore',
+        env: { ...process.env, MCP_PROJECT_ROOT: ROOT },
+    });
+    child.unref();
+    if (logFd !== null) fs.closeSync(logFd);
+    return child.pid;
+}
+
+function cmdStatus() {
+    const { running, pid } = daemonStatus(config.pidFile);
+    const backend = resolveBackend(config);
+    const artifact = backend === 'sqlite' ? config.sqlitePath : config.indexPath;
+    log('');
+    log(`  ${c.bold('graph-indexer')} ${c.dim('· daemon status')}`);
+    log(`  ${running ? glyph.run : glyph.stop} Daemon       ${running ? c.green(`running (PID ${pid})`) : c.dim('stopped')}`);
+    log(`  ${glyph.arrow} Project      ${c.dim(ROOT)}`);
+    log(`  ${glyph.arrow} Backend      ${backend === 'sqlite' ? 'SQLite (disk-backed)' : 'in-memory'}${config.storage === 'auto' ? c.dim(' · auto') : ''}`);
+    log(`  ${glyph.arrow} Index        ${c.dim(relArtifact())} ${c.dim('· ' + freshness(artifact))}`);
+    log(`  ${glyph.arrow} Logs         ${c.dim(path.relative(ROOT, config.logFile) || config.logFile)}`);
+    log('');
+    if (!running) log(c.dim(`  Start it with: ${c.cyan('npm run mcp:daemon:start')}\n`));
+    return 0;
+}
+
+function cmdStart() {
+    ensureDataDir(ROOT);
+    migrateLegacyLayout(ROOT);
+    const { running, pid } = daemonStatus(config.pidFile);
+    if (running) {
+        log(`${glyph.keep} Daemon already running ${c.dim(`(PID ${pid})`)} — only one runs per project.`);
+        return 0;
+    }
+    const newPid = spawnDaemon();
+    log(`${glyph.ok} Watch daemon started ${c.dim(`(PID ${newPid})`)}`);
+    log(c.dim(`  Logs: ${path.relative(ROOT, config.logFile) || config.logFile}`));
+    return 0;
+}
+
+async function cmdStop() {
+    const pid = readPid(config.pidFile);
+    if (!isAlive(pid)) {
+        log(`${glyph.keep} No daemon running.`);
+        try { if (pid) fs.unlinkSync(config.pidFile); } catch { }
+        return 0;
+    }
+    try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+    for (let i = 0; i < 50 && isAlive(readPid(config.pidFile) ?? pid); i++) await sleep(100);
+    if (isAlive(pid)) {
+        log(`${glyph.warn} Daemon ${c.dim(`(PID ${pid})`)} did not stop within 5s.`);
+        return 1;
+    }
+    log(`${glyph.ok} Daemon stopped ${c.dim(`(PID ${pid})`)}.`);
+    return 0;
+}
+
+async function cmdRestart() {
+    await cmdStop();
+    await sleep(200);
+    return cmdStart();
+}
+
+function tail(file, n) {
+    try {
+        const size = fs.statSync(file).size;
+        const start = Math.max(0, size - 256 * 1024); // last 256 KB is plenty
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(size - start);
+            fs.readSync(fd, buf, 0, buf.length, start);
+            const lines = buf.toString('utf-8').split('\n');
+            return { lines: lines.slice(-n - 1), size };
+        } finally { fs.closeSync(fd); }
+    } catch { return { lines: [], size: 0 }; }
+}
+
+async function cmdLogs(args) {
+    const follow = args.includes('-f') || args.includes('--follow');
+    const nArg = args.find((a) => /^\d+$/.test(a));
+    const n = nArg ? Number(nArg) : 50;
+    if (!fs.existsSync(config.logFile)) {
+        log(c.dim(`No daemon log yet (${path.relative(ROOT, config.logFile) || config.logFile}).`));
+        return 0;
+    }
+    const { lines, size } = tail(config.logFile, n);
+    process.stdout.write(lines.join('\n'));
+    if (!follow) { log(''); return 0; }
+
+    let pos = size;
+    log(c.dim(`\n— following ${path.relative(ROOT, config.logFile)} (Ctrl-C to stop) —`));
+    fs.watchFile(config.logFile, { interval: 500 }, (cur) => {
+        if (cur.size < pos) { pos = 0; return; } // truncated/rotated
+        if (cur.size === pos) return;
+        const fd = fs.openSync(config.logFile, 'r');
+        try {
+            const buf = Buffer.alloc(cur.size - pos);
+            fs.readSync(fd, buf, 0, buf.length, pos);
+            process.stdout.write(buf.toString('utf-8'));
+            pos = cur.size;
+        } finally { fs.closeSync(fd); }
+    });
+    return new Promise(() => { /* runs until Ctrl-C */ });
+}
+
+const [cmd = 'status', ...rest] = process.argv.slice(2);
+const run = {
+    start: cmdStart,
+    stop: cmdStop,
+    restart: cmdRestart,
+    status: cmdStatus,
+    logs: () => cmdLogs(rest),
+}[cmd];
+
+if (!run) {
+    log(`${glyph.err} Unknown command: ${c.bold(cmd)}`);
+    log(c.dim('  Usage: idx-daemon [start|stop|restart|status|logs]'));
+    process.exit(2);
+}
+
+Promise.resolve(run()).then((code) => process.exit(code ?? 0));