md-semantic-search 1.0.2 → 1.0.3

package/dist/completions.js

@@ -0,0 +1,233 @@
+/**
+ * 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.
+ */
+/** Every option bin/cli.mjs parseArgs understands (issue #107 drift guard). */
+export const FLAGS = [
+    // 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'];
+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() {
+    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() {
+    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() {
+    const lines = [
+        '# 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();
+    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() {
+    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 = { bash, zsh, fish, powershell };
+/** Generate a self-contained completion script; throws on an unknown shell. */
+export function generateCompletion(shell) {
+    const gen = GENERATORS[shell];
+    if (!gen) {
+        throw new Error(`unknown shell "${shell}" — use one of: ${COMPLETION_SHELLS.join('|')}`);
+    }
+    return gen();
+}

package/dist/core.d.ts

@@ -4,6 +4,11 @@ import { parseFrontmatter, DocumentMetadata } from './frontmatter.js';
 import { asymmetricCosineInt8 } from './quantization.js';
 export { PARSER_VERSION, parseFrontmatter, resolveModel, DocumentMetadata, ModelAdapter, Pooling, DType, asymmetricCosineInt8 };
 export declare const LOCK_FILENAME = ".mdss.lock";
+export type DownloadProgressListener = (e: import('./download-progress.js').DownloadProgressEvent) => void;
+/** Observe model-file download events from every pipeline load (issue #108). Pass null to detach. */
+export declare function setDownloadProgressListener(cb: DownloadProgressListener | null): void;
+/** Low-level emit used by the loaders; exported so tests/tools can simulate events. */
+export declare function emitDownloadEvent(e: import('./download-progress.js').DownloadProgressEvent): void;
 export declare function pidAlive(pid: number | null): boolean;
 export interface LockInfo {
     pid: number;

package/dist/core.js

@@ -13,6 +13,22 @@ export { PARSER_VERSION, parseFrontmatter, resolveModel, asymmetricCosineInt8 };
 const _extractors = new Map();
 export const LOCK_FILENAME = '.mdss.lock';
 const LOCK_STALE_MS = 10 * 60 * 1000;
+let downloadListener = null;
+/** Observe model-file download events from every pipeline load (issue #108). Pass null to detach. */
+export function setDownloadProgressListener(cb) {
+    downloadListener = typeof cb === 'function' ? cb : null;
+}
+/** Low-level emit used by the loaders; exported so tests/tools can simulate events. */
+export function emitDownloadEvent(e) {
+    if (!downloadListener)
+        return;
+    try {
+        downloadListener(e);
+    }
+    catch {
+        // a broken UI listener must never abort an in-flight model download
+    }
+}
 export function pidAlive(pid) {
     if (!Number.isInteger(pid) || pid === null || pid <= 0)
         return false;
@@ -217,6 +233,7 @@ export async function getExtractor(model, cacheDir, offline = false, retryOpts =
         const pipeOpts = {
             revision,
             dtype: model.dtype || 'q8',
+            progress_callback: emitDownloadEvent,
             ...(sessionOptions ? { session_options: sessionOptions } : {}),
         };
         const ext = await pipeline('feature-extraction', source, pipeOpts);

package/dist/download-progress.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Aggregated model-download progress (issue #108).
+ *
+ * transformers.js emits per-file events (`initiate`/`download`/`progress`/`done`)
+ * while a model directory streams in. A model is many files, so a per-file bar
+ * flickers uselessly — this aggregator folds them into ONE view: percent across
+ * every tracked file, smoothed MB/s, and an ETA over the bytes still missing.
+ *
+ * The "sawPartial" gate implements the warm-cache acceptance criterion: cached
+ * loads surface only instant complete-file events, so unless a real partial
+ * transfer was observed the aggregator stays silent.
+ */
+export interface DownloadProgressEvent {
+    status?: string;
+    name?: string;
+    file?: string;
+    loaded?: number;
+    total?: number;
+    progress?: number;
+}
+export interface DownloadSnapshot {
+    /** True once a partial transfer was observed — gates ALL output. */
+    reportable: boolean;
+    /** True when every file with a known total has fully arrived. */
+    complete: boolean;
+    doneFiles: number;
+    activeFiles: number;
+    loadedBytes: number;
+    totalBytes: number;
+    /** 0..100 across files with known totals; null while no total is known yet. */
+    percent: number | null;
+    mbps: number | null;
+    etaSec: number | null;
+    currentFile: string | null;
+}
+export declare class DownloadProgressAggregator {
+    private files;
+    private sawPartial;
+    private lastSampleAt;
+    private lastSampleBytes;
+    private mbpsEma;
+    private lastRenderAt;
+    update(e: DownloadProgressEvent, nowMs?: number): void;
+    private sumLoaded;
+    snapshot(): DownloadSnapshot;
+    /**
+     * Render throttle for live views: pass through at most one line per
+     * interval, plus ALWAYS the transition into `complete`.
+     */
+    shouldRender(nowMs: number, minIntervalMs?: number): boolean;
+    private renderedComplete;
+}

package/dist/download-progress.js

@@ -0,0 +1,112 @@
+/**
+ * Aggregated model-download progress (issue #108).
+ *
+ * transformers.js emits per-file events (`initiate`/`download`/`progress`/`done`)
+ * while a model directory streams in. A model is many files, so a per-file bar
+ * flickers uselessly — this aggregator folds them into ONE view: percent across
+ * every tracked file, smoothed MB/s, and an ETA over the bytes still missing.
+ *
+ * The "sawPartial" gate implements the warm-cache acceptance criterion: cached
+ * loads surface only instant complete-file events, so unless a real partial
+ * transfer was observed the aggregator stays silent.
+ */
+const SPEED_SMOOTHING = 0.3; // EMA weight of the newest instantaneous sample
+export class DownloadProgressAggregator {
+    files = new Map();
+    sawPartial = false;
+    lastSampleAt = 0;
+    lastSampleBytes = 0;
+    mbpsEma = null;
+    lastRenderAt = 0;
+    update(e, nowMs = Date.now()) {
+        if (!e || typeof e.file !== 'string' || e.file.length === 0)
+            return;
+        let f = this.files.get(e.file);
+        if (!f) {
+            f = { loaded: 0, total: 0 };
+            this.files.set(e.file, f);
+        }
+        if (typeof e.total === 'number' && Number.isFinite(e.total) && e.total > f.total) {
+            f.total = e.total;
+        }
+        if (typeof e.loaded === 'number' && Number.isFinite(e.loaded) && e.loaded >= 0) {
+            // clamp against the known total so a stray event can't overshoot to >100%
+            f.loaded = f.total > 0 ? Math.min(e.loaded, f.total) : e.loaded;
+        }
+        const midTransfer = (e.status === 'download' || e.status === 'progress') && f.total > 0 && f.loaded < f.total;
+        if (midTransfer)
+            this.sawPartial = true;
+        // speed sampling on cumulative byte growth
+        const sum = this.sumLoaded();
+        if (this.lastSampleAt === 0) {
+            this.lastSampleAt = nowMs;
+            this.lastSampleBytes = sum;
+        }
+        else if (sum > this.lastSampleBytes) {
+            const dtSec = (nowMs - this.lastSampleAt) / 1000;
+            if (dtSec > 0.05) {
+                const inst = (sum - this.lastSampleBytes) / dtSec / (1024 * 1024);
+                this.mbpsEma = this.mbpsEma === null ? inst : this.mbpsEma * (1 - SPEED_SMOOTHING) + inst * SPEED_SMOOTHING;
+                this.lastSampleAt = nowMs;
+                this.lastSampleBytes = sum;
+            }
+        }
+    }
+    sumLoaded() {
+        let sum = 0;
+        for (const f of this.files.values())
+            sum += f.loaded;
+        return sum;
+    }
+    snapshot() {
+        let loadedBytes = 0;
+        let totalBytes = 0;
+        let doneFiles = 0;
+        let activeFiles = 0;
+        for (const f of this.files.values()) {
+            loadedBytes += f.loaded;
+            if (f.total > 0) {
+                totalBytes += f.total;
+                if (f.loaded >= f.total)
+                    doneFiles += 1;
+                else
+                    activeFiles += 1;
+            }
+        }
+        const percent = totalBytes > 0 ? Math.min(100, (loadedBytes / totalBytes) * 100) : null;
+        const remaining = totalBytes - loadedBytes;
+        const etaSec = this.mbpsEma !== null && this.mbpsEma > 0 && remaining > 0 ? remaining / (1024 * 1024) / this.mbpsEma : null;
+        return {
+            reportable: this.sawPartial,
+            complete: totalBytes > 0 && activeFiles === 0,
+            doneFiles,
+            activeFiles,
+            loadedBytes,
+            totalBytes,
+            percent,
+            mbps: this.sawPartial ? this.mbpsEma : null,
+            etaSec: this.sawPartial ? etaSec : null,
+            currentFile: [...this.files.entries()].find(([, f]) => f.total === 0 || f.loaded < f.total)?.[0] ?? null,
+        };
+    }
+    /**
+     * Render throttle for live views: pass through at most one line per
+     * interval, plus ALWAYS the transition into `complete`.
+     */
+    shouldRender(nowMs, minIntervalMs = 400) {
+        if (!this.sawPartial)
+            return false;
+        const justCompleted = this.snapshot().complete && !this.renderedComplete;
+        if (justCompleted) {
+            this.renderedComplete = true;
+            this.lastRenderAt = nowMs;
+            return true;
+        }
+        if (nowMs - this.lastRenderAt >= minIntervalMs) {
+            this.lastRenderAt = nowMs;
+            return true;
+        }
+        return false;
+    }
+    renderedComplete = false;
+}

package/dist/index.d.ts

@@ -35,3 +35,5 @@ export { createFileWatcher, FileWatcher, WatcherOptions, } from './watcher.js';
 export { askQuestion, synthesizeAnswer, extractAnswerFallback, AskOptions, SynthesisResult, Citation, DEFAULT_RAG_SYSTEM_PROMPT, } from './rag.js';
 export { extractKeyphraseTags, summarizePassage, analyzeNote, NoteAnalysis, } from './summarize.js';
 export { runTui, TuiOptions } from './tui.js';
+export { generateCompletion, FLAGS, COMMANDS, COMPLETION_SHELLS, } from './completions.js';
+export type { FlagSpec, CompletionShell } from './completions.js';

package/dist/index.js

@@ -35,3 +35,4 @@ export { createFileWatcher, } from './watcher.js';
 export { askQuestion, synthesizeAnswer, extractAnswerFallback, DEFAULT_RAG_SYSTEM_PROMPT, } from './rag.js';
 export { extractKeyphraseTags, summarizePassage, analyzeNote, } from './summarize.js';
 export { runTui } from './tui.js';
+export { generateCompletion, FLAGS, COMMANDS, COMPLETION_SHELLS, } from './completions.js';

package/dist/mcp.js

@@ -11,6 +11,11 @@ import { loadIndex, searchIndex } from './search.js';
 import { searchFederated } from './federation.js';
 import { askQuestion } from './rag.js';
 import { globToRegExp } from './core.js';
+/**
+ * Package version reported via MCP initialize → serverInfo.
+ * Single source of truth: package.json (resolved relative to dist/mcp.js).
+ */
+const MCP_VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 export const MCP_TOOLS = [
     {
         name: 'search_markdown',
@@ -90,7 +95,7 @@ export async function handleMcpRequest(req, state) {
                 },
                 serverInfo: {
                     name: 'md-semantic-search',
-                    version: '1.0.0',
+                    version: MCP_VERSION,
                 },
             },
         };

package/dist/open.d.ts

@@ -0,0 +1,43 @@
+export interface OpenTarget {
+    file: string;
+    line?: number;
+}
+export interface OpenCommand {
+    command: string;
+    args: string[];
+    /** Human-readable source of the decision, e.g. "$EDITOR=vim" or "GUI opener". */
+    via: string;
+}
+export interface ResolveOptions {
+    /** $MDSS_EDITOR / $VISUAL / $EDITOR value, if any. */
+    editor?: string | null;
+    platform?: NodeJS.Platform;
+}
+export interface RunOptions extends ResolveOptions {
+    runner?: OpenRunner;
+}
+export type OpenRunner = (command: string, args: string[], opts: {
+    detached: boolean;
+    stdio: 'ignore';
+}) => unknown;
+/**
+ * Decide HOW to open `target`.
+ * - editor given: first token is the binary, remaining tokens are forwarded
+ *   verbatim. VS Code family gets `--goto file:line`, plus-line editors get
+ *   `+<line> file`, anything else just gets the file.
+ * - No editor configured → platform GUI opener (win32 `cmd /c start ""`,
+ *   darwin `open`, else `xdg-open`); a line cannot be passed there.
+ * Returns null only on an unsupported platform without an editor.
+ */
+export declare function resolveOpenCommand(target: OpenTarget, opts?: ResolveOptions): OpenCommand | null;
+/** Launch via the default detached spawn; inject a fake in tests. */
+export declare function defaultOpenRunner(command: string, args: string[], opts: {
+    detached: boolean;
+    stdio: 'ignore';
+}): void;
+/**
+ * Resolve + run. Returns the OpenCommand used (or null when nothing could be
+ * resolved). Throws when the runner reports a launch failure — callers turn
+ * that into a friendly die().
+ */
+export declare function openHit(target: OpenTarget, opts?: RunOptions): OpenCommand | null;

package/dist/open.js

@@ -0,0 +1,84 @@
+/**
+ * Editor jump for search hits (issue #110): open a hit's file at its exact
+ * `startLine` in $MDSS_EDITOR / $VISUAL / $EDITOR, with smart argument styles
+ * for known editor families and a platform GUI opener as the last resort.
+ *
+ * Resolution is PURE (unit-testable); launching goes through an injected
+ * runner so tests never spawn real processes.
+ */
+import { spawn } from 'node:child_process';
+const VSCODE_FAMILY = /^(code|code-insiders|codium|cursor|windsurf)$/i;
+/** Terminal editors taking a "+<line>" positional before the file. */
+const PLUS_LINE_EDITORS = /^(vim|vi|nvim|nano|ne|emacs|emacsclient|micro|hx)$/i;
+function baseName(cmd) {
+    // handle BOTH separators so a Windows full path resolves its family even
+    // when mdss runs on POSIX CI (issue #110)
+    const last = cmd.split(/[\\/]/).pop() ?? cmd;
+    return last.replace(/\.(exe|cmd|bat)$/i, '');
+}
+function splitEditorCommand(editor) {
+    // A value containing a path separator is ONE binary path (Windows installs
+    // live under "C:\Program Files\..."); only bare names may carry extra flags.
+    if (/[/\\]/.test(editor))
+        return [editor];
+    return editor.trim().split(/\s+/);
+}
+/**
+ * Decide HOW to open `target`.
+ * - editor given: first token is the binary, remaining tokens are forwarded
+ *   verbatim. VS Code family gets `--goto file:line`, plus-line editors get
+ *   `+<line> file`, anything else just gets the file.
+ * - No editor configured → platform GUI opener (win32 `cmd /c start ""`,
+ *   darwin `open`, else `xdg-open`); a line cannot be passed there.
+ * Returns null only on an unsupported platform without an editor.
+ */
+export function resolveOpenCommand(target, opts = {}) {
+    const { editor, platform = process.platform } = opts;
+    const line = Number.isInteger(target.line) && target.line > 0 ? target.line : undefined;
+    if (editor && editor.trim()) {
+        const parts = splitEditorCommand(editor.trim());
+        const command = parts[0];
+        const extra = parts.slice(1);
+        const name = baseName(command);
+        if (VSCODE_FAMILY.test(name)) {
+            return {
+                command,
+                args: [...extra, '--goto', `${target.file}${line ? `:${line}` : ''}`],
+                via: `$EDITOR=${editor}`,
+            };
+        }
+        if (PLUS_LINE_EDITORS.test(name)) {
+            return { command, args: [...extra, ...(line ? [`+${line}`] : []), target.file], via: `$EDITOR=${editor}` };
+        }
+        return { command, args: [...extra, target.file], via: `$EDITOR=${editor}` };
+    }
+    if (platform === 'win32') {
+        // empty title arg prevents `start` from mangling quoted paths
+        return { command: 'cmd', args: ['/c', 'start', '', target.file], via: 'GUI opener' };
+    }
+    if (platform === 'darwin') {
+        return { command: 'open', args: [target.file], via: 'GUI opener' };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        return { command: 'xdg-open', args: [target.file], via: 'GUI opener' };
+    }
+    return null;
+}
+/** Launch via the default detached spawn; inject a fake in tests. */
+export function defaultOpenRunner(command, args, opts) {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+/**
+ * Resolve + run. Returns the OpenCommand used (or null when nothing could be
+ * resolved). Throws when the runner reports a launch failure — callers turn
+ * that into a friendly die().
+ */
+export function openHit(target, opts = {}) {
+    const { runner = defaultOpenRunner, ...resolveOpts } = opts;
+    const resolved = resolveOpenCommand(target, resolveOpts);
+    if (!resolved)
+        return null;
+    runner(resolved.command, resolved.args, { detached: true, stdio: 'ignore' });
+    return resolved;
+}

package/dist/providers.d.ts

@@ -0,0 +1,21 @@
+import { ModelAdapter } from './models.js';
+export type EmbedderRole = 'query' | 'passage';
+export type ExternalEmbedFn = (texts: string[], role: EmbedderRole, model: ModelAdapter, cacheDir: string, offline: boolean) => Promise<number[][]>;
+export interface ProviderConfig {
+    embedder: 'ollama' | 'openai';
+    /** Provider-side model name, e.g. `nomic-embed-text` or `text-embedding-3-small`. */
+    model: string;
+    baseUrl?: string;
+    keyFile?: string;
+    /** Injected fetch for tests; defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface ResolvedEmbedder {
+    id: string;
+    model: string;
+    embedFn: ExternalEmbedFn;
+    /** Synthetic adapter (probes the endpoint once for dim). Await before indexing. */
+    descriptor(): Promise<ModelAdapter>;
+}
+/** Build an external embedder; dim is probed once on first use and cached. */
+export declare function resolveExternalEmbedder(cfg: ProviderConfig): ResolvedEmbedder;