md-semantic-search 1.0.2 → 1.0.3

package/dist/watcher.d.ts

@@ -8,4 +8,20 @@ export interface FileWatcher {
     close: () => void;
     isNative: boolean;
 }
+export type FsErrorClass = 'transient' | 'vanished' | 'permanent';
+/** Bucket a filesystem failure so callers can retry, skip, or warn. */
+export declare function classifyFsError(err: unknown): FsErrorClass;
+/** Retry `fn` while its failures classify as transient; capped exponential backoff. */
+export declare function readWithRetry<T>(fn: () => T, opts?: {
+    attempts?: number;
+    baseDelayMs?: number;
+    onRetry?: (attempt: number, err: unknown) => void;
+}): Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    err: unknown;
+    cls: FsErrorClass;
+}>;
 export declare function createFileWatcher(dbPath: string, onChange: () => void | Promise<void>, options?: WatcherOptions): FileWatcher;

package/dist/watcher.js

@@ -7,6 +7,47 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { globToRegExp } from './core.js';
+// ---------------------------------------------------------------------------
+// FS error classification + bounded retry (issue #116): Windows AV / OneDrive
+// / atomic-save editors produce EBUSY/EPERM bursts that previously became
+// silent 'unreadable' fingerprints and missed updates.
+// ---------------------------------------------------------------------------
+const TRANSIENT_CODES = new Set(['EBUSY', 'EPERM', 'EACCES', 'EMFILE', 'ENFILE', 'EAGAIN']);
+/** Bucket a filesystem failure so callers can retry, skip, or warn. */
+export function classifyFsError(err) {
+    const e = err;
+    if (!e)
+        return 'permanent';
+    if (e.code === 'ENOENT')
+        return 'vanished';
+    if (e.code && TRANSIENT_CODES.has(e.code))
+        return 'transient';
+    if (/temporarily unavailable|being written|locked by another process/i.test(String(e.message || ''))) {
+        return 'transient';
+    }
+    return 'permanent';
+}
+/** Retry `fn` while its failures classify as transient; capped exponential backoff. */
+export async function readWithRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? 3;
+    const baseDelayMs = opts.baseDelayMs ?? 200;
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return { ok: true, value: fn() };
+        }
+        catch (err) {
+            lastErr = err;
+            const cls = classifyFsError(err);
+            if (cls !== 'transient' || attempt === attempts) {
+                return { ok: false, err, cls };
+            }
+            opts.onRetry?.(attempt, err);
+            await new Promise((r) => setTimeout(r, baseDelayMs * attempt)); // 200ms, 400ms — capped
+        }
+    }
+    return { ok: false, err: lastErr, cls: classifyFsError(lastErr) };
+}
 export function createFileWatcher(dbPath, onChange, options = {}) {
     const { debounceMs = 250, ignore = [], log = () => { }, fallbackIntervalMs = 50, } = options;
     let closed = false;

package/dist/webui.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Built-in web UI assets for `mdss serve` (issue #111).
+ *
+ * Zero dependencies, zero build step: plain HTML + CSS + JS shipped as
+ * compiled-in strings (`files` already includes src/ -> dist/). Split into
+ * THREE assets so the CSP can stay strict (no inline script/style):
+ *   GET /      -> WEBUI_HTML  (shell, references ./ui.js + ./ui.css)
+ *   GET /ui.js -> WEBUI_JS    (all behaviour; addEventListener only, no eval)
+ *   GET /ui.css-> WEBUI_CSS    (dark/light via prefers-color-scheme + override)
+ */
+export declare const WEBUI_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>mdss \u2014 semantic search</title>\n<link rel=\"stylesheet\" href=\"./ui.css\">\n<script src=\"./ui.js\" defer></script>\n</head>\n<body>\n<header>\n  <div class=\"brand\">mdss<span id=\"health\" title=\"loading\u2026\"></span></div>\n  <button id=\"theme\" type=\"button\" aria-label=\"toggle theme\">\u25D0</button>\n</header>\n<main>\n  <div id=\"authbar\" hidden>\n    <input id=\"key\" type=\"password\" autocomplete=\"off\" placeholder=\"API key (Bearer)\">\n    <button id=\"keysafe\" type=\"button\">Save</button>\n    <span id=\"authmsg\"></span>\n  </div>\n  <searchbox>\n    <input id=\"q\" type=\"search\" autofocus\n      placeholder='Search by meaning \u2014 press \"/\" to focus' autocomplete=\"off\">\n  </searchbox>\n  <filters>\n    <input id=\"f-tag\"   placeholder=\"tag\">\n    <input id=\"f-type\"   placeholder=\"type\">\n    <input id=\"f-status\" placeholder=\"status\">\n    <input id=\"f-limit\"  type=\"number\" min=\"1\" max=\"50\" placeholder=\"max/file\">\n  </filters>\n  <div id=\"meta\"></div>\n  <ol id=\"results\"></ol>\n</main>\n<footer><code>POST /search</code> \u00B7 <a href=\"/help\">api</a> \u00B7 mdss web ui</footer>\n</body>\n</html>";
+export declare const WEBUI_CSS = "/* mdss web ui (issue #111) \u2014 dark/light via prefers-color-scheme */\n:root { color-scheme: light dark;\n  --bg:#fbfbfd; --fg:#1c1e21; --mut:#6b7280; --acc:#2563eb; --line:#e5e7eb;\n  --card:#ffffff; --mark:#fef08a; --bar:#dbeafe;\n}\n@media (prefers-color-scheme: dark) { :root {\n  --bg:#0f1115; --fg:#e6e6e6; --mut:#9aa0aa; --acc:#60a5fa; --line:#262b33;\n  --card:#161a21; --mark:#854d0e; --bar:#1e3a8a;\n}}\n:root[data-theme=\"dark\"] { --bg:#0f1115; --fg:#e6e6e6; --mut:#9aa0aa; --acc:#60a5fa; --line:#262b33; --card:#161a21; --mark:#854d0e; --bar:#1e3a8a }\n:root[data-theme=\"light\"] { --bg:#fbfbfd; --fg:#1c1e21; --mut:#6b7280; --acc:#2563eb; --line:#e5e7eb; --card:#fff; --mark:#fef08a; --bar:#dbeafe }\n\n* { box-sizing:border-box }\nbody { margin:0 auto; max-width:56rem; padding:0 1rem 3rem; background:var(--bg); color:var(--fg);\n  font:15px/1.55 system-ui,-apple-system,\"Segoe UI\",sans-serif }\nheader { display:flex; justify-content:space-between; align-items:center; padding:.9rem 0 }\n.brand { font-weight:700; letter-spacing:.02em }\n.brand span { margin-left:.6rem; font-weight:400; font-size:.8rem; color:var(--mut) }\n#theme { background:none; border:1px solid var(--line); border-radius:.5rem; color:var(--fg);\n  cursor:pointer; font-size:1rem; line-height:1; padding:.35rem .6rem }\n#q { width:100%; font-size:1.05rem; padding:.75rem 1rem; border:1px solid var(--line);\n  border-radius:.7rem; background:var(--card); color:var(--fg) }\n#q:focus { outline:2px solid var(--acc); outline-offset:1px }\nfilters { display:flex; gap:.5rem; margin-top:.6rem; flex-wrap:wrap }\nfilters input { flex:1 1 7rem; min-width:0; padding:.4rem .6rem; border:1px solid var(--line);\n  border-radius:.5rem; background:var(--card); color:var(--fg); font-size:.85rem }\n#meta { color:var(--mut); font-size:.85rem; margin:.7rem 0 .2rem }\n#results { list-style:none; margin:0; padding:0 }\n#results li { border:1px solid var(--line); background:var(--card); border-radius:.7rem;\n  padding:.7rem .9rem; margin-top:.6rem; cursor:pointer }\n#results li.active { outline:2px solid var(--acc) }\n.hit-head { display:flex; gap:.6rem; align-items:baseline }\n.hit-title { font-weight:600 }\n.hit-file { color:var(--acc); font-size:.82rem; white-space:nowrap }\n.hit-path { color:var(--mut); font-size:.82rem }\nmark { background:var(--mark); color:inherit; border-radius:.2rem; padding:0 .1em }\n.bar { height:4px; background:var(--bar); border-radius:2px; margin:.45rem 0 .2rem; overflow:hidden }\n.bar i { display:block; height:100%; background:var(--acc) }\n.snippet { overflow:hidden; max-height:3.2em; transition:max-height .15s ease }\nli.open .snippet { max-height:none }\n.score { margin-left:auto; color:var(--mut); font-size:.78rem }\n#authbar { display:flex; gap:.5rem; align-items:center; margin-bottom:.6rem;\n  padding:.5rem .7rem; border:1px dashed var(--line); border-radius:.6rem }\n#authbar[hidden] { display:none }\nfooter { margin-top:2rem; color:var(--mut); font-size:.8rem }\n";
+export declare const WEBUI_JS = "/* mdss web ui behaviour (issue #111) \u2014 no frameworks, no eval */\n(function () {\n  'use strict';\n  var q = document.getElementById('q');\n  var resultsEl = document.getElementById('results');\n  var meta = document.getElementById('meta');\n  var healthEl = document.getElementById('health');\n  var authbar = document.getElementById('authbar');\n  var keyInput = document.getElementById('key');\n\n  var KEY_STORE = 'mdss_key';\n  var key = sessionStorage.getItem(KEY_STORE) || '';\n  var activeIdx = -1;\n\n  function headers() {\n    var h = { 'Content-Type': 'application/json' };\n    if (key) h['Authorization'] = 'Bearer ' + key;\n    return h;\n  }\n  function esc(s) {\n    return String(s).replace(/[&<>\"']/g, function (c) {\n      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;', \"'\": '&#39;' }[c];\n    });\n  }\n  function highlight(text, terms) {\n    var safe = esc(text == null ? '' : text);\n    if (!terms || !terms.length) return safe;\n    var re = new RegExp('(' + terms.map(esc).join('|') + ')', 'gi');\n    return safe.replace(re, '<mark>$1</mark>');\n  }\n  function askKey(msg) {\n    authbar.hidden = false;\n    document.getElementById('authmsg').textContent = msg || '';\n    keyInput.focus();\n  }\n  document.getElementById('keysafe').addEventListener('click', function () {\n    key = keyInput.value.trim();\n    sessionStorage.setItem(KEY_STORE, key);\n    authbar.hidden = true;\n    run();\n  });\n\n  function api(path, opts) {\n    opts = opts || {};\n    opts.headers = headers();\n    return fetch(path, opts).then(function (res) {\n      if (res.status === 401) { askKey('401 \u2014 this daemon requires an API key'); }\n      if (!res.ok) throw new Error('HTTP ' + res.status);\n      return res.json();\n    });\n  }\n\n  function render(data, terms) {\n    var rs = data.results || [];\n    meta.textContent = rs.length ? (data.count + ' hit(s) for \u201C' + data.query + '\u201D') : 'No matches.';\n    activeIdx = -1;\n    resultsEl.innerHTML = '';\n    rs.forEach(function (r, i) {\n      var li = document.createElement('li');\n      var pct = Math.max(2, Math.min(100, Math.round((r.cosine || 0) * 100)));\n      var headPath = (r.headingPath || []).slice(0, -1).join(' \u203A ');\n      li.innerHTML =\n        '<div class=\"hit-head\"><span class=\"hit-title\">' + highlight(r.title, terms) + '</span>' +\n        '<span class=\"score\">' + Number(r.cosine || 0).toFixed(3) + '</span></div>' +\n        ((r.heading && r.heading !== r.title) ? '<div class=\"hit-path\">' + highlight(headPath || r.heading, terms) + '</div>' : '') +\n        '<div class=\"bar\"><i style=\"width:' + pct + '%\"></i></div>' +\n        '<div class=\"snippet\">' + highlight(r.snippet, terms) + '</div>' +\n        '<div class=\"hit-file\">' + esc(r.file) + (r.startLine != null ? ':' + r.startLine : '') + '</div>';\n      li.addEventListener('click', function () { li.classList.toggle('open'); });\n      resultsEl.appendChild(li);\n    });\n  }\n\n  var timer = null;\n  function run() {\n    var query = q.value.trim();\n    if (!query) { resultsEl.innerHTML = ''; meta.textContent = ''; return; }\n    var filters = {};\n    ['f-tag', 'f-type', 'f-status'].forEach(function (id) {\n      var v = document.getElementById(id).value.trim();\n      if (v) filters[id.slice(2)] = v;           // f-tag -> tag \u2026\n    });\n    var lim = parseInt(document.getElementById('f-limit').value, 10);\n    if (lim > 0) filters.maxPerFile = lim;\n\n    api('/search', { method: 'POST', body: JSON.stringify(Object.assign({ query: query, k: 20 }, filters)) })\n      .then(function (data) {\n        var lastTerms = (data.results || []).length\n          ? (data.results[0].matches || []) : [];\n        render(data, lastTerms);\n      })\n      .catch(function (e) { if (String(e.message) !== 'HTTP 401') meta.textContent = 'error: ' + e.message; });\n  }\n  q.addEventListener('input', function () {\n    clearTimeout(timer);\n    timer = setTimeout(run, 250);\n  });\n  document.querySelectorAll('filters input').forEach(function (el) {\n    el.addEventListener('input', function () { clearTimeout(timer); timer = setTimeout(run, 350); });\n  });\n\n  // keyboard-first: \"/\" focuses, arrows navigate, Enter toggles\n  document.addEventListener('keydown', function (ev) {\n    if (ev.key === '/' && document.activeElement !== q) { ev.preventDefault(); q.focus(); q.select(); return; }\n    if (ev.key === 'Escape') { q.blur(); return; }\n    var items = resultsEl.children;\n    if (!items.length) return;\n    if (ev.key === 'ArrowDown') { ev.preventDefault(); setActive(Math.min(items.length - 1, activeIdx + 1)); }\n    else if (ev.key === 'ArrowUp') { ev.preventDefault(); setActive(Math.max(0, activeIdx - 1)); }\n    else if (ev.key === 'Enter' && activeIdx >= 0) { items[activeIdx].classList.toggle('open'); }\n  });\n  function setActive(i) {\n    var items = resultsEl.children;\n    if (activeIdx >= 0 && items[activeIdx]) items[activeIdx].classList.remove('active');\n    activeIdx = i;\n    if (items[i]) {\n      items[i].classList.add('active');\n      items[i].scrollIntoView({ block: 'nearest' });\n    }\n  }\n\n  // theme: follow system until user overrides (persisted)\n  var root = document.documentElement;\n  var saved = null;\n  try { saved = localStorage.getItem('mdss_theme'); } catch (e) {}\n  if (saved) root.dataset.theme = saved;\n  document.getElementById('theme').addEventListener('click', function () {\n    var sysDark = window.matchMedia('(prefers-color-scheme: dark)').matches;\n    var cur = root.dataset.theme || (sysDark ? 'dark' : 'light');\n    var next = cur === 'dark' ? 'light' : 'dark';\n    root.dataset.theme = next;\n    try { localStorage.setItem('mdss_theme', next); } catch (e) {}\n  });\n\n  api('/health').then(function (h) {\n    healthEl.textContent = h.chunks + ' chunks \u00B7 ' + h.model;\n  }).catch(function () { healthEl.textContent = ''; });\n})();\n";

package/dist/webui.js

@@ -0,0 +1,231 @@
+/**
+ * Built-in web UI assets for `mdss serve` (issue #111).
+ *
+ * Zero dependencies, zero build step: plain HTML + CSS + JS shipped as
+ * compiled-in strings (`files` already includes src/ -> dist/). Split into
+ * THREE assets so the CSP can stay strict (no inline script/style):
+ *   GET /      -> WEBUI_HTML  (shell, references ./ui.js + ./ui.css)
+ *   GET /ui.js -> WEBUI_JS    (all behaviour; addEventListener only, no eval)
+ *   GET /ui.css-> WEBUI_CSS    (dark/light via prefers-color-scheme + override)
+ */
+export const WEBUI_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>mdss — semantic search</title>
+<link rel="stylesheet" href="./ui.css">
+<script src="./ui.js" defer></script>
+</head>
+<body>
+<header>
+  <div class="brand">mdss<span id="health" title="loading…"></span></div>
+  <button id="theme" type="button" aria-label="toggle theme">◐</button>
+</header>
+<main>
+  <div id="authbar" hidden>
+    <input id="key" type="password" autocomplete="off" placeholder="API key (Bearer)">
+    <button id="keysafe" type="button">Save</button>
+    <span id="authmsg"></span>
+  </div>
+  <searchbox>
+    <input id="q" type="search" autofocus
+      placeholder='Search by meaning — press "/" to focus' autocomplete="off">
+  </searchbox>
+  <filters>
+    <input id="f-tag"   placeholder="tag">
+    <input id="f-type"   placeholder="type">
+    <input id="f-status" placeholder="status">
+    <input id="f-limit"  type="number" min="1" max="50" placeholder="max/file">
+  </filters>
+  <div id="meta"></div>
+  <ol id="results"></ol>
+</main>
+<footer><code>POST /search</code> · <a href="/help">api</a> · mdss web ui</footer>
+</body>
+</html>`;
+export const WEBUI_CSS = `/* mdss web ui (issue #111) — dark/light via prefers-color-scheme */
+:root { color-scheme: light dark;
+  --bg:#fbfbfd; --fg:#1c1e21; --mut:#6b7280; --acc:#2563eb; --line:#e5e7eb;
+  --card:#ffffff; --mark:#fef08a; --bar:#dbeafe;
+}
+@media (prefers-color-scheme: dark) { :root {
+  --bg:#0f1115; --fg:#e6e6e6; --mut:#9aa0aa; --acc:#60a5fa; --line:#262b33;
+  --card:#161a21; --mark:#854d0e; --bar:#1e3a8a;
+}}
+:root[data-theme="dark"] { --bg:#0f1115; --fg:#e6e6e6; --mut:#9aa0aa; --acc:#60a5fa; --line:#262b33; --card:#161a21; --mark:#854d0e; --bar:#1e3a8a }
+:root[data-theme="light"] { --bg:#fbfbfd; --fg:#1c1e21; --mut:#6b7280; --acc:#2563eb; --line:#e5e7eb; --card:#fff; --mark:#fef08a; --bar:#dbeafe }
+
+* { box-sizing:border-box }
+body { margin:0 auto; max-width:56rem; padding:0 1rem 3rem; background:var(--bg); color:var(--fg);
+  font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif }
+header { display:flex; justify-content:space-between; align-items:center; padding:.9rem 0 }
+.brand { font-weight:700; letter-spacing:.02em }
+.brand span { margin-left:.6rem; font-weight:400; font-size:.8rem; color:var(--mut) }
+#theme { background:none; border:1px solid var(--line); border-radius:.5rem; color:var(--fg);
+  cursor:pointer; font-size:1rem; line-height:1; padding:.35rem .6rem }
+#q { width:100%; font-size:1.05rem; padding:.75rem 1rem; border:1px solid var(--line);
+  border-radius:.7rem; background:var(--card); color:var(--fg) }
+#q:focus { outline:2px solid var(--acc); outline-offset:1px }
+filters { display:flex; gap:.5rem; margin-top:.6rem; flex-wrap:wrap }
+filters input { flex:1 1 7rem; min-width:0; padding:.4rem .6rem; border:1px solid var(--line);
+  border-radius:.5rem; background:var(--card); color:var(--fg); font-size:.85rem }
+#meta { color:var(--mut); font-size:.85rem; margin:.7rem 0 .2rem }
+#results { list-style:none; margin:0; padding:0 }
+#results li { border:1px solid var(--line); background:var(--card); border-radius:.7rem;
+  padding:.7rem .9rem; margin-top:.6rem; cursor:pointer }
+#results li.active { outline:2px solid var(--acc) }
+.hit-head { display:flex; gap:.6rem; align-items:baseline }
+.hit-title { font-weight:600 }
+.hit-file { color:var(--acc); font-size:.82rem; white-space:nowrap }
+.hit-path { color:var(--mut); font-size:.82rem }
+mark { background:var(--mark); color:inherit; border-radius:.2rem; padding:0 .1em }
+.bar { height:4px; background:var(--bar); border-radius:2px; margin:.45rem 0 .2rem; overflow:hidden }
+.bar i { display:block; height:100%; background:var(--acc) }
+.snippet { overflow:hidden; max-height:3.2em; transition:max-height .15s ease }
+li.open .snippet { max-height:none }
+.score { margin-left:auto; color:var(--mut); font-size:.78rem }
+#authbar { display:flex; gap:.5rem; align-items:center; margin-bottom:.6rem;
+  padding:.5rem .7rem; border:1px dashed var(--line); border-radius:.6rem }
+#authbar[hidden] { display:none }
+footer { margin-top:2rem; color:var(--mut); font-size:.8rem }
+`;
+export const WEBUI_JS = `/* mdss web ui behaviour (issue #111) — no frameworks, no eval */
+(function () {
+  'use strict';
+  var q = document.getElementById('q');
+  var resultsEl = document.getElementById('results');
+  var meta = document.getElementById('meta');
+  var healthEl = document.getElementById('health');
+  var authbar = document.getElementById('authbar');
+  var keyInput = document.getElementById('key');
+
+  var KEY_STORE = 'mdss_key';
+  var key = sessionStorage.getItem(KEY_STORE) || '';
+  var activeIdx = -1;
+
+  function headers() {
+    var h = { 'Content-Type': 'application/json' };
+    if (key) h['Authorization'] = 'Bearer ' + key;
+    return h;
+  }
+  function esc(s) {
+    return String(s).replace(/[&<>"']/g, function (c) {
+      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+    });
+  }
+  function highlight(text, terms) {
+    var safe = esc(text == null ? '' : text);
+    if (!terms || !terms.length) return safe;
+    var re = new RegExp('(' + terms.map(esc).join('|') + ')', 'gi');
+    return safe.replace(re, '<mark>$1</mark>');
+  }
+  function askKey(msg) {
+    authbar.hidden = false;
+    document.getElementById('authmsg').textContent = msg || '';
+    keyInput.focus();
+  }
+  document.getElementById('keysafe').addEventListener('click', function () {
+    key = keyInput.value.trim();
+    sessionStorage.setItem(KEY_STORE, key);
+    authbar.hidden = true;
+    run();
+  });
+
+  function api(path, opts) {
+    opts = opts || {};
+    opts.headers = headers();
+    return fetch(path, opts).then(function (res) {
+      if (res.status === 401) { askKey('401 — this daemon requires an API key'); }
+      if (!res.ok) throw new Error('HTTP ' + res.status);
+      return res.json();
+    });
+  }
+
+  function render(data, terms) {
+    var rs = data.results || [];
+    meta.textContent = rs.length ? (data.count + ' hit(s) for “' + data.query + '”') : 'No matches.';
+    activeIdx = -1;
+    resultsEl.innerHTML = '';
+    rs.forEach(function (r, i) {
+      var li = document.createElement('li');
+      var pct = Math.max(2, Math.min(100, Math.round((r.cosine || 0) * 100)));
+      var headPath = (r.headingPath || []).slice(0, -1).join(' › ');
+      li.innerHTML =
+        '<div class="hit-head"><span class="hit-title">' + highlight(r.title, terms) + '</span>' +
+        '<span class="score">' + Number(r.cosine || 0).toFixed(3) + '</span></div>' +
+        ((r.heading && r.heading !== r.title) ? '<div class="hit-path">' + highlight(headPath || r.heading, terms) + '</div>' : '') +
+        '<div class="bar"><i style="width:' + pct + '%"></i></div>' +
+        '<div class="snippet">' + highlight(r.snippet, terms) + '</div>' +
+        '<div class="hit-file">' + esc(r.file) + (r.startLine != null ? ':' + r.startLine : '') + '</div>';
+      li.addEventListener('click', function () { li.classList.toggle('open'); });
+      resultsEl.appendChild(li);
+    });
+  }
+
+  var timer = null;
+  function run() {
+    var query = q.value.trim();
+    if (!query) { resultsEl.innerHTML = ''; meta.textContent = ''; return; }
+    var filters = {};
+    ['f-tag', 'f-type', 'f-status'].forEach(function (id) {
+      var v = document.getElementById(id).value.trim();
+      if (v) filters[id.slice(2)] = v;           // f-tag -> tag …
+    });
+    var lim = parseInt(document.getElementById('f-limit').value, 10);
+    if (lim > 0) filters.maxPerFile = lim;
+
+    api('/search', { method: 'POST', body: JSON.stringify(Object.assign({ query: query, k: 20 }, filters)) })
+      .then(function (data) {
+        var lastTerms = (data.results || []).length
+          ? (data.results[0].matches || []) : [];
+        render(data, lastTerms);
+      })
+      .catch(function (e) { if (String(e.message) !== 'HTTP 401') meta.textContent = 'error: ' + e.message; });
+  }
+  q.addEventListener('input', function () {
+    clearTimeout(timer);
+    timer = setTimeout(run, 250);
+  });
+  document.querySelectorAll('filters input').forEach(function (el) {
+    el.addEventListener('input', function () { clearTimeout(timer); timer = setTimeout(run, 350); });
+  });
+
+  // keyboard-first: "/" focuses, arrows navigate, Enter toggles
+  document.addEventListener('keydown', function (ev) {
+    if (ev.key === '/' && document.activeElement !== q) { ev.preventDefault(); q.focus(); q.select(); return; }
+    if (ev.key === 'Escape') { q.blur(); return; }
+    var items = resultsEl.children;
+    if (!items.length) return;
+    if (ev.key === 'ArrowDown') { ev.preventDefault(); setActive(Math.min(items.length - 1, activeIdx + 1)); }
+    else if (ev.key === 'ArrowUp') { ev.preventDefault(); setActive(Math.max(0, activeIdx - 1)); }
+    else if (ev.key === 'Enter' && activeIdx >= 0) { items[activeIdx].classList.toggle('open'); }
+  });
+  function setActive(i) {
+    var items = resultsEl.children;
+    if (activeIdx >= 0 && items[activeIdx]) items[activeIdx].classList.remove('active');
+    activeIdx = i;
+    if (items[i]) {
+      items[i].classList.add('active');
+      items[i].scrollIntoView({ block: 'nearest' });
+    }
+  }
+
+  // theme: follow system until user overrides (persisted)
+  var root = document.documentElement;
+  var saved = null;
+  try { saved = localStorage.getItem('mdss_theme'); } catch (e) {}
+  if (saved) root.dataset.theme = saved;
+  document.getElementById('theme').addEventListener('click', function () {
+    var sysDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    var cur = root.dataset.theme || (sysDark ? 'dark' : 'light');
+    var next = cur === 'dark' ? 'light' : 'dark';
+    root.dataset.theme = next;
+    try { localStorage.setItem('mdss_theme', next); } catch (e) {}
+  });
+
+  api('/health').then(function (h) {
+    healthEl.textContent = h.chunks + ' chunks · ' + h.model;
+  }).catch(function () { healthEl.textContent = ''; });
+})();
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-semantic-search",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Local, private semantic (vector) search over any folder of Markdown files. Finds passages by meaning — cross-lingual — using transformers.js. No API keys, no cloud, no vector database.",
   "type": "module",
   "main": "./dist/index.js",

package/src/completions.ts

@@ -0,0 +1,250 @@
+/**
+ * Shell completions generator (issue #107).
+ *
+ * Single source of truth: the FLAGS table below drives every shell script AND
+ * the drift-guard test (test/completions.test.mjs) that diffs it against the
+ * flags actually parsed in bin/cli.mjs. Adding a flag in parseArgs without
+ * updating this table fails the test — and vice versa.
+ *
+ * Static generation only: no runtime dependency, `mdss completions <shell>`
+ * prints a self-contained script to stdout.
+ */
+
+export type FlagKind = 'flag' | 'value' | 'file' | 'dir' | 'number';
+
+export interface FlagSpec {
+  /** Primary long form, e.g. "--index-dir". */
+  name: string;
+  alias?: string;
+  kind: FlagKind;
+}
+
+/** Every option bin/cli.mjs parseArgs understands (issue #107 drift guard). */
+export const FLAGS: FlagSpec[] = [
+  // boolean switches
+  { name: '--json', kind: 'flag' },
+  { name: '--semantic', kind: 'flag' },
+  { name: '--offline', kind: 'flag' },
+  { name: '--watch', kind: 'flag' },
+  { name: '--watch-debug', kind: 'flag' },
+  { name: '--no-ui', kind: 'flag' },
+  { name: '--mcp', kind: 'flag' },
+  { name: '--rerank', kind: 'flag' },
+  { name: '--explain', kind: 'flag' },
+  { name: '--interactive', alias: '-i', kind: 'flag' },
+  { name: '--list-tools', kind: 'flag' },
+  { name: '--no-vectors', alias: '--no-vector', kind: 'flag' },
+  { name: '--no-query-cache', kind: 'flag' },
+  { name: '--recency', kind: 'number' },
+  { name: '--embedder', kind: 'value' },
+  { name: '--embedder-model', kind: 'value' },
+  { name: '--embedder-base-url', kind: 'value' },
+  { name: '--embedder-key-file', kind: 'file' },
+  { name: '--expand', kind: 'value' },
+  { name: '--expand-passages', kind: 'number' },
+  { name: '--health-public', kind: 'flag' },
+  { name: '--allow-unsecured', kind: 'flag' },
+  { name: '--ann', kind: 'flag' },
+  { name: '--canonical', kind: 'flag' },
+  { name: '--rag', kind: 'flag' },
+  { name: '--auto-tag', kind: 'flag' },
+  { name: '--auto-summarize', kind: 'flag' },
+  { name: '--help', alias: '-h', kind: 'flag' },
+  { name: '--version', kind: 'flag' },
+  { name: '--open', kind: 'flag' }, // optional N consumed by parseArgs itself
+  { name: '--fix', kind: 'flag' },
+  { name: '--dry-run', kind: 'flag' },
+  // values
+  { name: '--workers', kind: 'number' },
+  { name: '--config', kind: 'file' },
+  { name: '--format', kind: 'value' },
+  { name: '--output', alias: '-o', kind: 'file' },
+  { name: '--db', kind: 'dir' },
+  { name: '--vault', kind: 'dir' },
+  { name: '--index-dir', kind: 'dir' },
+  { name: '--cache-dir', kind: 'dir' },
+  { name: '--model', kind: 'value' },
+  { name: '--k', kind: 'number' },
+  { name: '--max-per-file', kind: 'number' },
+  { name: '--max-per-doc', kind: 'number' },
+  { name: '--target-tokens', kind: 'number' },
+  { name: '--port', kind: 'number' },
+  { name: '--host', kind: 'value' },
+  { name: '--api-key', kind: 'value' },
+  { name: '--api-key-file', kind: 'file' },
+  { name: '--allowed-host', kind: 'value' },
+  { name: '--cors-origin', kind: 'value' },
+  { name: '--watch-delay', kind: 'number' },
+  { name: '--watch-interval', kind: 'number' },
+  { name: '--rate-limit', kind: 'number' },
+  { name: '--max-concurrency', kind: 'number' },
+  { name: '--since', kind: 'value' },
+  { name: '--path', kind: 'value' },
+  { name: '--ignore', kind: 'value' },
+  { name: '--tag', kind: 'value' },
+  { name: '--nprobe', kind: 'number' },
+  { name: '--project', kind: 'value' },
+  { name: '--type', kind: 'value' },
+  { name: '--status', kind: 'value' },
+  { name: '--graph-boost', kind: 'number' },
+  { name: '--filter', kind: 'value' },
+  { name: '--quantize', kind: 'value' },
+  { name: '--llm-endpoint', kind: 'value' },
+  { name: '--llm-model', kind: 'value' },
+  { name: '--system-prompt', kind: 'value' },
+];
+
+export const COMMANDS = [
+  'index', 'stats', 'check', 'doctor', 'export', 'search',
+  'ask', 'tui', 'serve', 'mcp', 'models', 'completions',
+];
+
+export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish', 'powershell'] as const;
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+
+const DIR_FLAGS = [...new Set(FLAGS.filter((f) => f.kind === 'dir').flatMap((f) => [f.name, ...(f.alias && !f.alias.startsWith('--') ? [f.alias] : [])]))];
+const FILE_FLAGS = [...new Set(FLAGS.filter((f) => f.kind === 'file').flatMap((f) => [f.name, ...(f.alias && !f.alias.startsWith('--') ? [f.alias] : [])]))];
+const ALL_FLAG_WORDS = FLAGS.flatMap((f) => [f.name, ...(f.alias && f.alias.startsWith('--') ? [f.alias] : [])]);
+
+function bash(): string {
+  const dirCase = DIR_FLAGS.join('|');
+  const fileCase = FILE_FLAGS.join('|');
+  return `# bash completion for mdss (md-semantic-search)
+# Generated by \`mdss completions bash\` (issue #107).
+# Install: eval "$(mdss completions bash)"
+_mdss_completion() {
+  local cur prev commands flags
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  commands="${COMMANDS.join(' ')}"
+  flags="${ALL_FLAG_WORDS.join(' ')}"
+
+  case "$prev" in
+    ${dirCase})
+      mapfile -t COMPREPLY < <(compgen -d -- "$cur"); return 0 ;;
+    ${fileCase})
+      mapfile -t COMPREPLY < <(compgen -f -- "$cur"); return 0 ;;
+  esac
+
+  if [[ "$cur" == -* ]]; then
+    mapfile -t COMPREPLY < <(compgen -W "$flags" -- "$cur")
+    return 0
+  fi
+
+  if (( COMP_CWORD <= 2 )); then
+    mapfile -t COMPREPLY < <(compgen -W "$commands" -- "$cur")
+  fi
+}
+complete -o default -F _mdss_completion mdss md-semantic-search
+`;
+}
+
+function zsh(): string {
+  const cmdDescs = COMMANDS.map((c) => `'${c}'`).join(' ');
+  return `#compdef mdss
+# zsh completion for mdss — generated by \`mdss completions zsh\` (issue #107).
+# Install: mkdir -p ~/.zfunc && mdss completions zsh > ~/.zfunc/_mdss
+# (ensure ~/.zfunc is in fpath BEFORE compinit)
+local -a commands options dir_flags file_flags
+commands=(${cmdDescs})
+options=(${ALL_FLAG_WORDS.map((f) => `'${f}'`).join(' ')})
+dir_flags=(${DIR_FLAGS.map((f) => `'${f}'`).join(' ')})
+file_flags=(${FILE_FLAGS.map((f) => `'${f}'`).join(' ')})
+
+_mdss() {
+  local cur prev
+  cur="\${words[CURRENT]}"
+  prev="\${words[CURRENT-1]}"
+  if (( CURRENT == 2 )) && [[ "$cur" != -* ]]; then
+    _describe -t commands 'mdss command' commands
+    return
+  fi
+  if (( \${dir_flags[(Ie)$prev]} )); then
+    _directories
+    return
+  fi
+  if (( \${file_flags[(Ie)$prev]} )); then
+    _files
+    return
+  fi
+  if [[ "$cur" == -* ]]; then
+    _describe -t options 'mdss option' options
+    return
+  fi
+}
+compdef _mdss mdss md-semantic-search
+`;
+}
+
+function fish(): string {
+  const lines: string[] = [
+    '# fish completion for mdss — generated by `mdss completions fish` (issue #107).',
+    '# Install: mdss completions fish > ~/.config/fish/completions/mdss.fish',
+    '',
+    `complete -c mdss -n '__fish_is_first_arg' -a '${COMMANDS.join(' ')}'`,
+    '',
+  ];
+  const seenShorts = new Set<string>();
+  for (const f of FLAGS) {
+    const parts = ['complete -c mdss'];
+    if (f.alias && !f.alias.startsWith('--') && !seenShorts.has(f.alias)) {
+      parts.push(`-s ${f.alias.slice(1)}`);
+      seenShorts.add(f.alias);
+    }
+    parts.push(`-l ${f.name.slice(2)}`);
+    if (f.kind !== 'flag') parts.push('-r');
+    if (f.kind === 'file') parts.push('-F');
+    if (f.kind === 'dir') parts.push('-a "(__fish_complete_directories)"');
+    lines.push(parts.join(' '));
+  }
+  return lines.join('\n') + '\n';
+}
+
+function powershell(): string {
+  return `# PowerShell completion for mdss — generated by \`mdss completions powershell\` (issue #107).
+# Install: paste into your $PROFILE (or dot-source it from there).
+Register-ArgumentCompleter -CommandName 'mdss','md-semantic-search' -Native -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $commands = @('${COMMANDS.join("','")}')
+  $dirFlags = @('${DIR_FLAGS.join("','")}')
+  $fileFlags = @('${FILE_FLAGS.join("','")}')
+  $flags = @('${ALL_FLAG_WORDS.join("','")}')
+
+  $elements = @($commandAst.CommandElements)
+  if ($elements.Count -le 1) {
+    $commands | Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'Command', $_) }
+    return
+  }
+
+  $prev = ''
+  if ($elements.Count -ge 2) { $prev = $elements[$elements.Count - 2].ToString() }
+
+  if (($dirFlags -contains $prev) -or ($fileFlags -contains $prev)) {
+    return # defer path completion to PowerShell's native provider
+  }
+
+  if ("$wordToComplete".StartsWith('-')) {
+    $flags | Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterName', $_) }
+    return
+  }
+
+  if ($elements.Count -eq 2) {
+    $commands | Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'Command', $_) }
+  }
+}
+`;
+}
+
+const GENERATORS: Record<CompletionShell, () => string> = { bash, zsh, fish, powershell };
+
+/** Generate a self-contained completion script; throws on an unknown shell. */
+export function generateCompletion(shell: string): string {
+  const gen = GENERATORS[shell as CompletionShell];
+  if (!gen) {
+    throw new Error(`unknown shell "${shell}" — use one of: ${COMPLETION_SHELLS.join('|')}`);
+  }
+  return gen();
+}

package/src/core.ts

@@ -18,6 +18,31 @@ const _extractors = new Map<string, any>();
 export const LOCK_FILENAME = '.mdss.lock';
 const LOCK_STALE_MS = 10 * 60 * 1000;
 
+// ---------------------------------------------------------------------------
+// Model-download progress hook (issue #108): transformers.js fires per-file
+// events while a model streams in; loaders below forward them to ONE process-
+// wide listener so the CLI can render a single aggregated bar.
+// ---------------------------------------------------------------------------
+
+export type DownloadProgressListener = (e: import('./download-progress.js').DownloadProgressEvent) => void;
+
+let downloadListener: DownloadProgressListener | null = null;
+
+/** Observe model-file download events from every pipeline load (issue #108). Pass null to detach. */
+export function setDownloadProgressListener(cb: DownloadProgressListener | null): void {
+  downloadListener = typeof cb === 'function' ? cb : null;
+}
+
+/** Low-level emit used by the loaders; exported so tests/tools can simulate events. */
+export function emitDownloadEvent(e: import('./download-progress.js').DownloadProgressEvent): void {
+  if (!downloadListener) return;
+  try {
+    downloadListener(e);
+  } catch {
+    // a broken UI listener must never abort an in-flight model download
+  }
+}
+
 export function pidAlive(pid: number | null): boolean {
   if (!Number.isInteger(pid) || pid === null || pid <= 0) return false;
   try {
@@ -240,6 +265,7 @@ export async function getExtractor(
     const pipeOpts: any = {
       revision,
       dtype: model.dtype || 'q8',
+      progress_callback: emitDownloadEvent,
       ...(sessionOptions ? { session_options: sessionOptions } : {}),
     };
     const ext = await pipeline('feature-extraction', source, pipeOpts);