md-semantic-search 0.4.0 → 1.0.1

package/bin/cli.mjs

@@ -14,12 +14,14 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import fs from 'node:fs';
 import os from 'node:os';
-import { buildIndex } from '../src/indexer.mjs';
-import { search } from '../src/search.mjs';
-import { createServe, DEFAULT_PORT, DEFAULT_HOST } from '../src/serve.mjs';
-import { MODELS, DEFAULT_MODEL, resolveModel } from '../src/models.mjs';
-import { decodeVec, walkMarkdown, SCHEMA_VERSION } from '../src/core.mjs';
-import { inspectIndexSchema, validateCurrentChunk, validateIndexEnvelope, validateNumericVector } from '../src/index-format.mjs';
+import crypto from 'node:crypto';
+import { buildIndex } from '../dist/indexer.js';
+import { search } from '../dist/search.js';
+import { searchFederated } from '../dist/federation.js';
+import { createServe, DEFAULT_PORT, DEFAULT_HOST } from '../dist/serve.js';
+import { MODELS, DEFAULT_MODEL, resolveModel } from '../dist/models.js';
+import { decodeVec, walkMarkdown, SCHEMA_VERSION, assertSafePath } from '../dist/core.js';
+import { inspectIndexSchema, validateCurrentChunk, validateIndexEnvelope, validateNumericVector } from '../dist/index-format.js';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(HERE, '..');
@@ -40,7 +42,7 @@ function defaultCacheDir() {
 }
 
 function parseArgs(argv) {
-  const opts = { _: [], ignore: [], path: [] };
+  const opts = { _: [], ignore: [], path: [], vaults: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--json') opts.json = true;
@@ -49,9 +51,17 @@ function parseArgs(argv) {
     else if (a === '--watch') opts.watch = true;
     else if (a === '--rerank') opts.rerank = true;
     else if (a === '--explain') opts.explain = true;
+    else if (a === '--interactive' || a === '-i') opts.interactive = true;
+    else if (a === '--list-tools') opts.listTools = true;
     else if (a === '--version') opts.version = true;
     else if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--workers') opts.workers = nextInt(argv, ++i, a);
+    else if (a === '--config') opts.config = nextValue(argv, ++i, a);
+    else if (a === '--format') opts.format = nextValue(argv, ++i, a);
+    else if (a === '--no-vectors' || a === '--no-vector') opts.noVectors = true;
+    else if (a === '--output' || a === '-o') opts.output = nextValue(argv, ++i, a);
     else if (a === '--db') opts.db = nextValue(argv, ++i, a);
+    else if (a === '--vault') opts.vaults.push(nextValue(argv, ++i, a));
     else if (a === '--index-dir') opts.indexDir = nextValue(argv, ++i, a);
     else if (a === '--cache-dir') opts.cacheDir = nextValue(argv, ++i, a);
     else if (a === '--model') opts.model = nextValue(argv, ++i, a);
@@ -61,6 +71,8 @@ function parseArgs(argv) {
     else if (a === '--target-tokens') opts.targetTokens = nextInt(argv, ++i, a);
     else if (a === '--port') opts.port = nextInt(argv, ++i, a);
     else if (a === '--host') opts.host = nextValue(argv, ++i, a);
+    else if (a === '--api-key') opts.apiKey = nextValue(argv, ++i, a);
+    else if (a === '--health-public') opts.healthPublic = true;
     else if (a === '--watch-delay') opts.watchDelay = nextInt(argv, ++i, a);
     else if (a === '--watch-interval') opts.watchInterval = nextInt(argv, ++i, a);
     else if (a === '--since') opts.since = nextValue(argv, ++i, a);
@@ -70,10 +82,21 @@ function parseArgs(argv) {
       const v = nextValue(argv, ++i, a);
       opts.tag = opts.tag ? (Array.isArray(opts.tag) ? [...opts.tag, v] : [opts.tag, v]) : v;
     }
+    else if (a === '--ann') opts.ann = true;
+    else if (a === '--nprobe') opts.nprobe = nextInt(argv, ++i, a);
     else if (a === '--project') opts.project = nextValue(argv, ++i, a);
     else if (a === '--type') opts.type = nextValue(argv, ++i, a);
     else if (a === '--status') opts.status = nextValue(argv, ++i, a);
     else if (a === '--canonical') opts.canonical = true;
+    else if (a === '--graph-boost') opts.graphBoost = nextFloat(argv, ++i, a);
+    else if (a === '--filter') opts.filter = nextValue(argv, ++i, a);
+    else if (a === '--quantize') opts.quantize = nextValue(argv, ++i, a);
+    else if (a === '--rag') opts.rag = true;
+    else if (a === '--auto-tag') opts.autoTag = true;
+    else if (a === '--auto-summarize') opts.autoSummarize = true;
+    else if (a === '--llm-endpoint') opts.llmEndpoint = nextValue(argv, ++i, a);
+    else if (a === '--llm-model') opts.llmModel = nextValue(argv, ++i, a);
+    else if (a === '--system-prompt') opts.systemPrompt = nextValue(argv, ++i, a);
     else if (a.startsWith('-')) die(`unknown option: ${a}. Try \`mdss --help\`.`);
     else opts._.push(a);
   }
@@ -95,6 +118,96 @@ function nextInt(argv, i, flag) {
   return k;
 }
 
+/** Like nextValue but requires a non-negative float. */
+function nextFloat(argv, i, flag) {
+  const v = nextValue(argv, i, flag);
+  const f = Number.parseFloat(v);
+  if (!Number.isFinite(f) || f < 0) die(`${flag} must be a non-negative number, got "${v}"`);
+  return f;
+}
+
+const KNOWN_CONFIG_KEYS = new Set([
+  'db', 'model', 'indexDir', 'index-dir', 'cacheDir', 'cache-dir',
+  'ignore', 'path', 'k', 'maxPerFile', 'max-per-file', 'maxPerDoc', 'max-per-doc',
+  'targetTokens', 'target-tokens', 'port', 'host', 'apiKey', 'api-key',
+  'healthPublic', 'health-public', 'watch', 'watchInterval', 'watch-interval',
+  'watchDelay', 'watch-delay', 'offline', 'rerank', 'semantic', 'tag', 'project', 'type', 'status', 'canonical',
+  'format', 'noVectors', 'no-vectors', 'output', 'workers', 'ann', 'nprobe', 'graphBoost', 'graph-boost', 'filter', 'quantize',
+  'vault', 'vaults', 'rag', 'autoTag', 'auto-tag', 'autoSummarize', 'auto-summarize',
+  'llmEndpoint', 'llm-endpoint', 'llmModel', 'llm-model', 'systemPrompt', 'system-prompt'
+]);
+
+function findConfigFile(explicitPath) {
+  if (explicitPath) {
+    const abs = path.resolve(explicitPath);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) die(`config file not found: ${abs}`);
+    return abs;
+  }
+  if (process.env.MDSS_CONFIG) {
+    const abs = path.resolve(process.env.MDSS_CONFIG);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) die(`config file from MDSS_CONFIG not found: ${abs}`);
+    return abs;
+  }
+  const configNames = ['.mdssrc.json', 'mdss.config.json', '.mdssrc'];
+  let curr = process.cwd();
+  while (true) {
+    for (const name of configNames) {
+      const candidate = path.join(curr, name);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    }
+    const parent = path.dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+  try {
+    const home = os.homedir();
+    if (home) {
+      for (const name of ['.mdssrc.json', '.mdssrc']) {
+        const candidate = path.join(home, name);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+          return candidate;
+        }
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function loadConfigFile(configPath) {
+  if (!configPath) return { config: {}, path: null, unknownKeys: [], error: null };
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { config: {}, path: configPath, unknownKeys: [], error: `Config at ${configPath} must be a JSON object` };
+    }
+    const unknownKeys = Object.keys(parsed).filter(k => !KNOWN_CONFIG_KEYS.has(k));
+    const normalized = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      const camel = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      normalized[camel] = v;
+    }
+    return { config: normalized, path: configPath, unknownKeys, error: null };
+  } catch (e) {
+    return { config: {}, path: configPath, unknownKeys: [], error: `Failed to parse config at ${configPath}: ${e.message}` };
+  }
+}
+
+function applyConfigDefaults(opts, config) {
+  for (const [k, v] of Object.entries(config)) {
+    if (k === 'ignore' || k === 'path') {
+      if ((!opts[k] || opts[k].length === 0) && v !== undefined) {
+        opts[k] = Array.isArray(v) ? [...v] : [v];
+      }
+    } else if (opts[k] === undefined && v !== undefined) {
+      opts[k] = v;
+    }
+  }
+  return opts;
+}
+
 function resolveDb(opts) {
   const db = opts.db || process.env.MDSS_DB;
   if (!db) die('Missing --db <dir> (or set MDSS_DB). Path to your .md folder.');
@@ -102,13 +215,23 @@ function resolveDb(opts) {
   if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
     die(`--db is not a directory: ${abs}`);
   }
-  return abs;
+  let safeDb;
+  try {
+    safeDb = assertSafePath(abs);
+  } catch (e) {
+    die(e.message);
+  }
+  return safeDb;
 }
 
 function resolveIndexDir(opts, db) {
   // Default: <db>/.mdss. Override with --index-dir or MDSS_INDEX_DIR.
   const dir = opts.indexDir || process.env.MDSS_INDEX_DIR || path.join(db, '.mdss');
-  return path.resolve(dir);
+  try {
+    return assertSafePath(dir);
+  } catch (e) {
+    die(e.message);
+  }
 }
 
 const resolveCache = (opts) =>
@@ -127,15 +250,22 @@ Usage:
   mdss index  --db <dir> [options]            Build/refresh the index
   mdss stats  --db <dir> [--json]             Index stats without loading the model
   mdss check  --db <dir> [--json]             Diagnose index/db/model cache (alias: doctor)
+  mdss export --db <dir> [options]            Export index to JSONL / CSV / Parquet
   mdss search --db <dir> [options] "query"    Search by meaning
   mdss serve  --db <dir> [--port <n>] [--host <ip>] [--watch]  Daemon: warm model + index
+  mdss mcp    --db <dir> [--list-tools]       Start MCP server over stdio for LLM agents / IDEs
   mdss models                                  List available models
 
 Options:
+  --config <file>     Path to config file (default: .mdssrc.json / mdss.config.json).
   --db <dir>          Folder of .md files (or env MDSS_DB). Can be anywhere.
   --index-dir <dir>   Where to store the index (default: <db>/.mdss).
   --cache-dir <dir>   Model cache dir (default: ~/.cache/mdss, or MDSS_CACHE_DIR).
   --model <name|id>   Embedding model (default: ${DEFAULT_MODEL}). See \`mdss models\`.
+  --workers <n>       Number of parallel batch workers for indexing (default: 1).
+  --format <fmt>      Export format: jsonl (default), csv, parquet (export).
+  --no-vectors        Omit vector embeddings from export (export).
+  --output <file>     Output file path (export, default: stdout).
   --ignore <glob>     Skip files/paths (repeatable). e.g. --ignore "log.md".
   --path <glob>       Search only files matching glob (repeatable). e.g. --path "docs/**".
   --since <date>      Search only files modified at/after date (YYYY-MM-DD or ISO).
@@ -143,6 +273,10 @@ Options:
   --json              Machine-readable output (index, stats, search).
   --semantic          Pure vector ranking, skip lexical/RRF fusion (search).
   --rerank            Re-rank candidates with a cross-encoder (search; ~280MB model).
+  --graph-boost <n>   Boost weight for graph PageRank / Obsidian wikilinks (search, default: 0).
+  --filter <expr>     Rich boolean filter across frontmatter tags and properties (search).
+  --ann               Approximate nearest neighbor search via IVF (search).
+  --nprobe <n>        Number of centroids to probe for ANN (search, default: 8).
   --port <n>          HTTP port for serve (default: ${DEFAULT_PORT}).
   --host <ip>         Bind address for serve (default: ${DEFAULT_HOST} — loopback
                       only; use 0.0.0.0 to expose on the LAN, env MDSS_HOST).
@@ -164,11 +298,41 @@ Examples:
   curl -X POST localhost:8747/search -d '{"query":"rotate api token","k":5}'
 `;
 
+function formatDuration(sec) {
+  const s = Math.max(0, Math.floor(sec));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const remainingS = s % 60;
+  return `${h}:${String(m).padStart(2, '0')}:${String(remainingS).padStart(2, '0')}`;
+}
+
 async function cmdIndex(opts) {
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
   const t0 = Date.now();
+  let lastProgressUpdate = 0;
+
+  const onProgress = (done, total, chunksPerSec) => {
+    if (!process.stderr.isTTY || opts.json || total <= 100) return;
+    const now = Date.now();
+    if (now - lastProgressUpdate < 500 && done < total) return;
+    lastProgressUpdate = now;
+    const percent = Math.floor((done / total) * 100);
+    const barWidth = 10;
+    const filled = Math.min(barWidth, Math.max(0, Math.round((done / total) * barWidth)));
+    const bar = '[' + '#'.repeat(filled) + '-'.repeat(barWidth - filled) + ']';
+    const remaining = total - done;
+    const etaSec = chunksPerSec > 0 ? remaining / chunksPerSec : 0;
+    const etaStr = formatDuration(etaSec);
+    const speedStr = `${chunksPerSec.toFixed(1)} chunks/s`;
+    const line = `${bar} ${percent}% │ ${done}/${total} chunks │ ${speedStr} │ ETA ${etaStr}`;
+    process.stderr.write(`\r${line}`);
+    if (done >= total) {
+      process.stderr.write('\n');
+    }
+  };
+
   let r;
   try {
     r = await buildIndex({
@@ -176,7 +340,14 @@ async function cmdIndex(opts) {
       modelName: opts.model || DEFAULT_MODEL,
       ignore: opts.ignore,
       offline: resolveOffline(opts),
-      log: s => process.stderr.write(s + '\n'),
+      workers: opts.workers,
+      ann: opts.ann,
+      quantize: opts.quantize,
+      log: s => {
+        if (process.stderr.isTTY && !opts.json && /^\s+\d+\/\d+$/.test(s)) return;
+        process.stderr.write(s + '\n');
+      },
+      onProgress,
     });
   } catch (e) {
     // A held index lock (issue #37) is an EXPECTED operational state (a second
@@ -234,7 +405,7 @@ function cmdStats(opts) {
   // File count = keys of .hashes.json (per-file md5 map written by buildIndex).
   // Fall back to unique chunk file paths when the hashes file is missing (a
   // legacy/corrupt index) rather than dying.
-  let files = 0;
+  let files;
   try {
     const hashes = JSON.parse(fs.readFileSync(hashesPath, 'utf8'));
     files = Object.keys(hashes).length;
@@ -288,6 +459,119 @@ function cmdStats(opts) {
   );
 }
 
+/**
+ * `mdss export` — export the index as JSONL / CSV / Parquet for downstream pipelines (issue #77).
+ */
+async function cmdExport(opts) {
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const vectorsPath = path.join(indexDir, 'vectors.json');
+  if (!fs.existsSync(vectorsPath)) {
+    die(`No index at ${vectorsPath}. Run \`mdss index\` first.`);
+  }
+
+  let index;
+  try {
+    index = JSON.parse(fs.readFileSync(vectorsPath, 'utf8'));
+  } catch (e) {
+    die(`${vectorsPath} is not valid JSON (${e.message}); run \`mdss index\` to rebuild.`);
+  }
+
+  const format = (opts.format || 'jsonl').toLowerCase();
+  const noVectors = !!opts.noVectors;
+  const outStream = opts.output ? fs.createWriteStream(path.resolve(opts.output), 'utf8') : process.stdout;
+
+  const chunks = Array.isArray(index.chunks) ? index.chunks : [];
+  const dim = index.dim;
+
+  if (format === 'jsonl') {
+    for (const c of chunks) {
+      let vec = undefined;
+      if (!noVectors && c.vec !== undefined) {
+        if (typeof c.vec === 'string') {
+          try {
+            vec = Array.from(decodeVec(c.vec, dim));
+          } catch {
+            vec = null;
+          }
+        } else if (Array.isArray(c.vec) || ArrayBuffer.isView(c.vec)) {
+          vec = Array.from(c.vec);
+        }
+      }
+      const record = {
+        file: c.file,
+        title: c.title,
+        heading: c.heading,
+        headingPath: c.headingPath,
+        text: c.text,
+        ...(noVectors ? {} : { vec }),
+        ...(c.chunkHash ? { chunkHash: c.chunkHash } : {}),
+        ...(c.startLine !== undefined ? { startLine: c.startLine } : {}),
+        ...(c.endLine !== undefined ? { endLine: c.endLine } : {}),
+        ...(c.meta ? { meta: c.meta } : {}),
+      };
+      outStream.write(JSON.stringify(record) + '\n');
+    }
+    if (opts.output) {
+      await new Promise((resolve) => outStream.end(resolve));
+    }
+  } else if (format === 'csv') {
+    const escapeCsv = (val) => {
+      const str = String(val ?? '');
+      if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+        return '"' + str.replace(/"/g, '""') + '"';
+      }
+      return str;
+    };
+    outStream.write('file,title,heading,headingPath,text\n');
+    for (const c of chunks) {
+      const pathStr = Array.isArray(c.headingPath) ? c.headingPath.join(' > ') : (c.heading || '');
+      const row = [
+        escapeCsv(c.file),
+        escapeCsv(c.title),
+        escapeCsv(c.heading),
+        escapeCsv(pathStr),
+        escapeCsv(c.text),
+      ].join(',');
+      outStream.write(row + '\n');
+    }
+    if (opts.output) {
+      await new Promise((resolve) => outStream.end(resolve));
+    }
+  } else if (format === 'parquet') {
+    let parquet;
+    try {
+      // @ts-ignore
+      parquet = await import('parquetjs-lite');
+    } catch {
+      die('Parquet export requires optional dependency "parquetjs-lite". Install with: npm install parquetjs-lite');
+    }
+    if (!opts.output) {
+      die('Parquet export requires an output file via --output <file.parquet>');
+    }
+    const schemaFields = {
+      file: { type: 'UTF8' },
+      title: { type: 'UTF8' },
+      heading: { type: 'UTF8' },
+      text: { type: 'UTF8' },
+    };
+    const schema = new parquet.ParquetSchema(schemaFields);
+    const outFile = path.resolve(opts.output);
+    const writer = await parquet.ParquetWriter.openFile(schema, outFile);
+    for (const c of chunks) {
+      await writer.appendRow({
+        file: c.file || '',
+        title: c.title || '',
+        heading: c.heading || '',
+        text: c.text || '',
+      });
+    }
+    await writer.close();
+  } else {
+    die(`unknown export format: "${format}". Supported formats: jsonl, csv, parquet.`);
+  }
+}
+
 /**
  * Offline diagnostics for the index/db/model-cache trio (issue #43) — the
  * `mdss check` / `mdss doctor` backend. Pure read-only: parses vectors.json +
@@ -295,7 +579,7 @@ function cmdStats(opts) {
  * validator the loader uses), walks the db for staleness, and checks the
  * transformers.js cache layout for the index's model. NEVER loads the
  * embedding model and NEVER touches the network.
- * @param {{db:string, indexDir:string, cacheDir:string, requireOffline?:boolean}} paths
+ * @param {{db:string, indexDir:string, cacheDir:string, requireOffline?:boolean, config?:any}} paths
  * @returns {CheckReport}
  */
 
@@ -312,7 +596,7 @@ function cmdStats(opts) {
  * @property {{exists:boolean, stale:boolean, error:(string|null)}} db
  * @property {{id:(string|null), cached:boolean, cachePath:(string|null), error:(string|null)}} model
  */
-export function checkHealth({ db, indexDir, cacheDir, requireOffline = false }) {
+function checkHealth({ db, indexDir, cacheDir, requireOffline = false, config = null }) {
   const report = {
     healthy: true,
     index: { exists: false, parses: false, schemaVersion: null, format: null, recognized: true, error: null },
@@ -320,7 +604,21 @@ export function checkHealth({ db, indexDir, cacheDir, requireOffline = false })
     chunks: { total: 0, valid: 0, invalid: [] },
     db: { exists: true, stale: false, error: null },
     model: { id: null, cached: false, cachePath: null, error: null },
+    config: null,
   };
+
+  // --- config file: exists, valid JSON, schema / unknown keys (issue #68) ---
+  if (config && config.path) {
+    report.config = {
+      path: config.path,
+      valid: !config.error && (!config.unknownKeys || config.unknownKeys.length === 0),
+      unknownKeys: config.unknownKeys || [],
+      error: config.error || (config.unknownKeys && config.unknownKeys.length > 0 ? `unknown config keys: ${config.unknownKeys.join(', ')}` : null),
+    };
+    if (!report.config.valid) {
+      report.healthy = false;
+    }
+  }
   const vectorsPath = path.join(indexDir, 'vectors.json');
   const hashesPath = path.join(indexDir, '.hashes.json');
 
@@ -332,8 +630,22 @@ export function checkHealth({ db, indexDir, cacheDir, requireOffline = false })
   }
   report.index.exists = true;
   let index;
+  const raw = fs.readFileSync(vectorsPath, 'utf8');
+  const shaPath = path.join(indexDir, 'vectors.json.sha256');
+  if (fs.existsSync(shaPath)) {
+    try {
+      const shaContent = fs.readFileSync(shaPath, 'utf8').trim();
+      const expectedHash = shaContent.split(/\s+/)[0];
+      const actualHash = crypto.createHash('sha256').update(raw).digest('hex');
+      if (expectedHash && actualHash !== expectedHash) {
+        report.index.error = `vectors.json integrity check failed (SHA-256 mismatch) — run \`mdss index\` to rebuild`;
+        report.healthy = false;
+        return report;
+      }
+    } catch { /* ignore unreadable sha file */ }
+  }
   try {
-    index = JSON.parse(fs.readFileSync(vectorsPath, 'utf8'));
+    index = JSON.parse(raw);
     report.index.parses = true;
   } catch (e) {
     report.index.error = `${vectorsPath} is not valid JSON (${e.message}); run \`mdss index\` to rebuild`;
@@ -469,7 +781,11 @@ function cmdCheck(opts) {
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
-  const report = checkHealth({ db, indexDir, cacheDir, requireOffline: resolveOffline(opts) });
+  const report = checkHealth({
+    db, indexDir, cacheDir,
+    requireOffline: resolveOffline(opts),
+    config: opts._config,
+  });
 
   if (opts.json) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -543,6 +859,14 @@ function cmdCheck(opts) {
     out += warn('model: index has no model field (legacy index)');
   }
 
+  if (report.config) {
+    if (report.config.valid) {
+      out += ok(`config: ${report.config.path}`);
+    } else {
+      out += fail(`config: ${report.config.path} (${report.config.error})`);
+    }
+  }
+
   out += report.healthy
     ? 'check: healthy (exit 0)\n'
     : 'check: 1+ problem(s) found (exit 1)\n';
@@ -550,29 +874,116 @@ function cmdCheck(opts) {
   process.exitCode = report.healthy ? 0 : 1;
 }
 
-async function cmdSearch(opts) {
+async function cmdTui(opts) {
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
   const query = opts._.join(' ').trim();
-  if (!query) die('Missing query text. e.g. mdss search --db ./docs "your question"');
-
-  const results = await search({
-    indexDir, cacheDir, query,
-    k: opts.k || 6,
+  const { runTui } = await import('../dist/tui.js');
+  await runTui({
+    db, indexDir, cacheDir, query,
+    k: opts.k || 20,
     semanticOnly: !!opts.semantic,
     offline: resolveOffline(opts),
     path: opts.path.length > 0 ? opts.path : undefined,
-    since: opts.since,
     rerank: !!opts.rerank,
-    tag: opts.tag,
-    project: opts.project,
-    type: opts.type,
-    status: opts.status,
-    canonicalOnly: opts.canonical,
-    explain: !!opts.explain,
-    maxPerFile: opts.maxPerFile || opts.maxPerDoc,
+    rag: !!opts.rag,
   });
+}
+
+async function cmdAsk(opts) {
+  const query = opts._.join(' ').trim();
+  if (!query) die('missing question to ask. Usage: mdss ask [--db <dir>] "question"');
+
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const cacheDir = resolveCache(opts);
+  const k = opts.k || 5;
+
+  const { askQuestion } = await import('../dist/rag.js');
+  const result = await askQuestion({
+    query,
+    indexDir,
+    cacheDir,
+    k,
+    llmEndpoint: opts.llmEndpoint,
+    llmModel: opts.llmModel,
+    systemPrompt: opts.systemPrompt,
+  });
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(`\n${result.answer}\n\n`);
+  if (result.citations && result.citations.length > 0) {
+    process.stdout.write('Sources:\n');
+    for (const c of result.citations) {
+      const heading = c.heading ? ` › ${c.heading}` : '';
+      process.stdout.write(`  - ${c.file}${heading} [score: ${c.score.toFixed(3)}]\n`);
+    }
+    process.stdout.write('\n');
+  }
+}
+
+async function cmdSearch(opts) {
+  if (opts.interactive) return cmdTui(opts);
+  const cacheDir = resolveCache(opts);
+  const query = opts._.join(' ').trim();
+  if (!query) die('Missing query text. e.g. mdss search --db ./docs "your question"');
+
+  let results;
+  const isFederated = Array.isArray(opts.vaults) && opts.vaults.length > 0;
+
+  if (isFederated) {
+    results = await searchFederated({
+      vaults: opts.vaults,
+      cacheDir,
+      query,
+      k: opts.k || 6,
+      semanticOnly: !!opts.semantic,
+      offline: resolveOffline(opts),
+      path: opts.path.length > 0 ? opts.path : undefined,
+      since: opts.since,
+      rerank: !!opts.rerank,
+      tag: opts.tag,
+      project: opts.project,
+      type: opts.type,
+      status: opts.status,
+      canonicalOnly: opts.canonical,
+      explain: !!opts.explain,
+      maxPerFile: opts.maxPerFile || opts.maxPerDoc,
+      ann: opts.ann,
+      nprobe: opts.nprobe,
+      graphBoost: opts.graphBoost,
+      filter: opts.filter,
+    });
+  } else {
+    const db = resolveDb(opts);
+    const indexDir = resolveIndexDir(opts, db);
+
+    results = await search({
+      indexDir, cacheDir, query,
+      k: opts.k || 6,
+      semanticOnly: !!opts.semantic,
+      offline: resolveOffline(opts),
+      path: opts.path.length > 0 ? opts.path : undefined,
+      since: opts.since,
+      rerank: !!opts.rerank,
+      tag: opts.tag,
+      project: opts.project,
+      type: opts.type,
+      status: opts.status,
+      canonicalOnly: opts.canonical,
+      explain: !!opts.explain,
+      maxPerFile: opts.maxPerFile || opts.maxPerDoc,
+      ann: opts.ann,
+      nprobe: opts.nprobe,
+      graphBoost: opts.graphBoost,
+      filter: opts.filter,
+    });
+  }
 
   if (opts.json) { process.stdout.write(JSON.stringify(results, null, 2) + '\n'); return; }
   if (results.length === 0) { process.stdout.write('No matches.\n'); return; }
@@ -582,13 +993,14 @@ async function cmdSearch(opts) {
   // Group by file (issue #13): each file becomes a header with its hits below.
   const byFile = new Map();
   for (const r of results) {
-    if (!byFile.has(r.file)) byFile.set(r.file, []);
-    byFile.get(r.file).push(r);
+    const fileKey = r.vault ? `[${r.vault}] ${r.file}` : r.file;
+    if (!byFile.has(fileKey)) byFile.set(fileKey, []);
+    byFile.get(fileKey).push(r);
   }
   const color = !!process.stdout.isTTY; // bold matched terms only on a real terminal
   let rank = 0;
-  for (const [file, hits] of byFile) {
-    process.stdout.write(`${file}\n`);
+  for (const [fileHeader, hits] of byFile) {
+    process.stdout.write(`${fileHeader}\n`);
     for (const r of hits) {
       rank++;
       let snippet = r.snippet;
@@ -648,6 +1060,8 @@ async function cmdServe(opts) {
     watch: !!opts.watch,
     watchInterval: opts.watchInterval,
     watchDelay: opts.watchDelay,
+    apiKey: opts.apiKey || process.env.MDSS_API_KEY,
+    healthPublic: !!opts.healthPublic || process.env.MDSS_HEALTH_PUBLIC === 'true',
     log,
   });
 
@@ -671,9 +1085,37 @@ async function cmdServe(opts) {
   process.on('SIGTERM', () => stop('SIGTERM'));
 }
 
+async function cmdMcp(opts) {
+  if (opts.listTools) {
+    const { MCP_TOOLS } = await import('../dist/mcp.js');
+    process.stdout.write(JSON.stringify(MCP_TOOLS, null, 2) + '\n');
+    return;
+  }
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const cacheDir = resolveCache(opts);
+  const log = s => process.stderr.write(s + '\n');
+  const { startMcpServer } = await import('../dist/mcp.js');
+  await startMcpServer({
+    db, indexDir, cacheDir,
+    modelName: opts.model || DEFAULT_MODEL,
+    ignore: opts.ignore,
+    offline: resolveOffline(opts),
+    log,
+  });
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const opts = parseArgs(argv);
+  const configPath = findConfigFile(opts.config);
+  const loadedConfig = loadConfigFile(configPath);
+  if (loadedConfig.error && opts.config) {
+    die(loadedConfig.error);
+  }
+  opts._config = loadedConfig;
+  applyConfigDefaults(opts, loadedConfig.config);
+
   const cmd = opts._.shift();
 
   if (opts.version) { process.stdout.write(`${VERSION}\n`); return; }
@@ -683,8 +1125,12 @@ async function main() {
     case 'stats': return cmdStats(opts);
     case 'check':
     case 'doctor': return cmdCheck(opts);
+    case 'export': return cmdExport(opts);
     case 'search': return cmdSearch(opts);
+    case 'ask': return cmdAsk(opts);
+    case 'tui': return cmdTui(opts);
     case 'serve': return cmdServe(opts);
+    case 'mcp': return cmdMcp(opts);
     case 'models': return cmdModels();
     default: die(`unknown command: ${cmd}. Try \`mdss --help\`.`);
   }
@@ -700,7 +1146,9 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 // functions are unit-tested directly; die() is asserted via a mocked
 // process.exit so a bad flag cannot kill the test runner.
 export {
-  parseArgs, nextInt, nextValue,
+  parseArgs, nextInt, nextFloat, nextValue,
   resolveDb, resolveIndexDir, resolveCache, resolveOffline,
+  findConfigFile, loadConfigFile, applyConfigDefaults, KNOWN_CONFIG_KEYS,
+  checkHealth, cmdExport,
   die, main, HELP, VERSION,
 };