@wei840222/qmd 2026.8.23

package/dist/maintenance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Maintenance - Database cleanup operations for QMD.
+ *
+ * Wraps low-level store operations that the CLI needs for housekeeping.
+ * Takes an internal Store in the constructor — allowed to access DB directly.
+ */
+import type { Store } from "./store.js";
+import { type CleanupStats } from "./store.js";
+export declare class Maintenance {
+    private store;
+    constructor(store: Store);
+    /** Run VACUUM on the SQLite database to reclaim space */
+    vacuum(): void;
+    /** Remove content rows that are no longer referenced by any document */
+    cleanupOrphanedContent(): number;
+    /** Remove vector embeddings for content that no longer exists */
+    cleanupOrphanedVectors(): number;
+    /** Clear the LLM response cache (query expansion, reranking) */
+    clearLLMCache(): number;
+    /** Delete documents marked as inactive (removed from filesystem) */
+    deleteInactiveDocs(): number;
+    /** Clear all vector embeddings (forces re-embedding) */
+    clearEmbeddings(): void;
+    /** Compact FTS5 so deleted rows leave documents_fts_data (#550). */
+    optimizeFts(): void;
+    /** Preview what {@link run} would remove, without writing. */
+    preview(): CleanupStats;
+    /**
+     * Full cleanup: cache, orphaned vectors, inactive docs, orphaned content,
+     * FTS optimize, vacuum. Same sequence as `qmd cleanup`.
+     */
+    run(): CleanupStats;
+}

package/dist/maintenance.js

@@ -0,0 +1,52 @@
+/**
+ * Maintenance - Database cleanup operations for QMD.
+ *
+ * Wraps low-level store operations that the CLI needs for housekeeping.
+ * Takes an internal Store in the constructor — allowed to access DB directly.
+ */
+import { vacuumDatabase, cleanupOrphanedContent, cleanupOrphanedVectors, deleteLLMCache, deleteInactiveDocuments, clearAllEmbeddings, optimizeDocumentsFts, previewCleanup, runCleanup, } from "./store.js";
+export class Maintenance {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** Run VACUUM on the SQLite database to reclaim space */
+    vacuum() {
+        vacuumDatabase(this.store.db);
+    }
+    /** Remove content rows that are no longer referenced by any document */
+    cleanupOrphanedContent() {
+        return cleanupOrphanedContent(this.store.db);
+    }
+    /** Remove vector embeddings for content that no longer exists */
+    cleanupOrphanedVectors() {
+        return cleanupOrphanedVectors(this.store.db);
+    }
+    /** Clear the LLM response cache (query expansion, reranking) */
+    clearLLMCache() {
+        return deleteLLMCache(this.store.db);
+    }
+    /** Delete documents marked as inactive (removed from filesystem) */
+    deleteInactiveDocs() {
+        return deleteInactiveDocuments(this.store.db);
+    }
+    /** Clear all vector embeddings (forces re-embedding) */
+    clearEmbeddings() {
+        clearAllEmbeddings(this.store.db);
+    }
+    /** Compact FTS5 so deleted rows leave documents_fts_data (#550). */
+    optimizeFts() {
+        optimizeDocumentsFts(this.store.db);
+    }
+    /** Preview what {@link run} would remove, without writing. */
+    preview() {
+        return previewCleanup(this.store.db);
+    }
+    /**
+     * Full cleanup: cache, orphaned vectors, inactive docs, orphaned content,
+     * FTS optimize, vacuum. Same sequence as `qmd cleanup`.
+     */
+    run() {
+        return runCleanup(this.store.db);
+    }
+}

package/dist/mcp/origin-guard.d.ts

@@ -0,0 +1,67 @@
+/**
+ * origin-guard.ts — DNS-rebinding protection for the HTTP MCP transport.
+ *
+ * Binding to localhost keeps *remote* clients out, but it does not keep a web
+ * page out. A page served from `attacker.example` can re-point that hostname at
+ * `127.0.0.1` after load (DNS rebinding); the browser then treats
+ * `http://attacker.example:8181` as same-origin with the page and hands the
+ * response body to attacker JavaScript. The only server-side signal that
+ * distinguishes such a request from a legitimate local client is the `Origin`
+ * and `Host` headers, so the MCP spec requires local HTTP servers to validate
+ * them.
+ *
+ * The predicates here are pure so they can be unit-tested without a socket;
+ * `startMcpHttpServer` applies them to every request before routing.
+ */
+/**
+ * Hostnames that resolve to this machine's loopback interface.
+ *
+ * `0.0.0.0` is deliberately excluded: browsers happily route it to loopback on
+ * Linux and macOS, which makes it a rebinding-free path to local servers, so an
+ * `Origin: http://0.0.0.0:8181` is treated as untrusted like any other.
+ */
+export declare function isLoopbackHostname(hostname: string): boolean;
+export type OriginGuard = {
+    /** All checks disabled (`QMD_ALLOWED_ORIGINS=*`). */
+    disabled: boolean;
+    /** Extra origins accepted beyond the loopback defaults, normalized. */
+    allowedOrigins: string[];
+    /** Extra `Host` values accepted beyond the loopback defaults, lowercased. */
+    allowedHosts: string[];
+    /** Whether the `Host` header is checked at all — see `resolveOriginGuard`. */
+    enforceHost: boolean;
+};
+/**
+ * Build the guard for a server bound to `host`.
+ *
+ * `Host` validation is enforced whenever the bind address names a concrete
+ * interface, since the legitimate `Host` header is then known (loopback, or the
+ * bind address itself). For a wildcard bind — `--host 0.0.0.0`, e.g. Docker —
+ * any of the container's names may legitimately appear, so the check is only
+ * enforced when the operator supplies an explicit allowlist. `Origin`
+ * validation always applies; browsers are the threat, and they always send it.
+ */
+export declare function resolveOriginGuard(options: {
+    host: string;
+    allowedOrigins?: string[];
+    allowedHosts?: string[];
+    env?: NodeJS.ProcessEnv;
+}): OriginGuard;
+export type GuardVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate a request's `Origin` and `Host` headers against the guard.
+ *
+ * A missing `Origin` is allowed: non-browser clients (curl, the MCP SDK's HTTP
+ * client, editors) omit it, and browsers cannot. The header is the signal that
+ * a request came from page JavaScript, so its *absence* is not suspicious while
+ * a foreign *value* is conclusive.
+ */
+export declare function checkRequestOrigin(headers: {
+    origin?: string | undefined;
+    host?: string | undefined;
+}, guard: OriginGuard): GuardVerdict;

package/dist/mcp/origin-guard.js

@@ -0,0 +1,137 @@
+/**
+ * origin-guard.ts — DNS-rebinding protection for the HTTP MCP transport.
+ *
+ * Binding to localhost keeps *remote* clients out, but it does not keep a web
+ * page out. A page served from `attacker.example` can re-point that hostname at
+ * `127.0.0.1` after load (DNS rebinding); the browser then treats
+ * `http://attacker.example:8181` as same-origin with the page and hands the
+ * response body to attacker JavaScript. The only server-side signal that
+ * distinguishes such a request from a legitimate local client is the `Origin`
+ * and `Host` headers, so the MCP spec requires local HTTP servers to validate
+ * them.
+ *
+ * The predicates here are pure so they can be unit-tested without a socket;
+ * `startMcpHttpServer` applies them to every request before routing.
+ */
+/** Wildcard bind addresses — the request's legitimate `Host` is unknowable. */
+const WILDCARD_BIND_HOSTS = new Set(["", "0.0.0.0", "::", "[::]", "*"]);
+/**
+ * Hostnames that resolve to this machine's loopback interface.
+ *
+ * `0.0.0.0` is deliberately excluded: browsers happily route it to loopback on
+ * Linux and macOS, which makes it a rebinding-free path to local servers, so an
+ * `Origin: http://0.0.0.0:8181` is treated as untrusted like any other.
+ */
+export function isLoopbackHostname(hostname) {
+    const h = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    if (h === "localhost" || h.endsWith(".localhost"))
+        return true;
+    if (h === "::1" || h === "0:0:0:0:0:0:0:1")
+        return true;
+    // IPv4-mapped IPv6 (::ffff:127.0.0.1) and the whole 127.0.0.0/8 range.
+    const v4 = h.startsWith("::ffff:") ? h.slice(7) : h;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(v4);
+}
+/** Parse an `Origin` header into its hostname, or undefined if unusable. */
+function originHostname(origin) {
+    try {
+        const url = new URL(origin.trim());
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        return url.hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Normalize an origin for comparison against the allowlist. */
+function normalizeOrigin(origin) {
+    try {
+        return new URL(origin.trim()).origin.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a `Host` header (`name`, `name:port`, `[::1]:port`) into a hostname. */
+function hostHeaderHostname(host) {
+    try {
+        return new URL(`http://${host.trim()}`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function splitList(value) {
+    if (!value)
+        return [];
+    return value.split(",").map(v => v.trim()).filter(v => v.length > 0);
+}
+/**
+ * Build the guard for a server bound to `host`.
+ *
+ * `Host` validation is enforced whenever the bind address names a concrete
+ * interface, since the legitimate `Host` header is then known (loopback, or the
+ * bind address itself). For a wildcard bind — `--host 0.0.0.0`, e.g. Docker —
+ * any of the container's names may legitimately appear, so the check is only
+ * enforced when the operator supplies an explicit allowlist. `Origin`
+ * validation always applies; browsers are the threat, and they always send it.
+ */
+export function resolveOriginGuard(options) {
+    const env = options.env ?? process.env;
+    const rawOrigins = options.allowedOrigins ?? splitList(env.QMD_ALLOWED_ORIGINS);
+    const rawHosts = options.allowedHosts ?? splitList(env.QMD_ALLOWED_HOSTS);
+    if (rawOrigins.includes("*")) {
+        return { disabled: true, allowedOrigins: [], allowedHosts: [], enforceHost: false };
+    }
+    const allowedOrigins = rawOrigins
+        .map(o => normalizeOrigin(o))
+        .filter((o) => o !== undefined);
+    const allowedHosts = rawHosts.map(h => h.toLowerCase());
+    const bindHost = options.host.trim().toLowerCase();
+    const isWildcardBind = WILDCARD_BIND_HOSTS.has(bindHost);
+    if (!isWildcardBind && !isLoopbackHostname(bindHost)) {
+        // Explicit non-loopback interface: its own address is a legitimate Host.
+        allowedHosts.push(bindHost);
+    }
+    return {
+        disabled: false,
+        allowedOrigins,
+        allowedHosts,
+        enforceHost: !isWildcardBind || allowedHosts.length > 0,
+    };
+}
+/**
+ * Validate a request's `Origin` and `Host` headers against the guard.
+ *
+ * A missing `Origin` is allowed: non-browser clients (curl, the MCP SDK's HTTP
+ * client, editors) omit it, and browsers cannot. The header is the signal that
+ * a request came from page JavaScript, so its *absence* is not suspicious while
+ * a foreign *value* is conclusive.
+ */
+export function checkRequestOrigin(headers, guard) {
+    if (guard.disabled)
+        return { ok: true };
+    const origin = headers.origin?.trim();
+    if (origin) {
+        const normalized = normalizeOrigin(origin);
+        const hostname = originHostname(origin);
+        const allowed = (hostname !== undefined && isLoopbackHostname(hostname)) ||
+            (normalized !== undefined && guard.allowedOrigins.includes(normalized));
+        if (!allowed) {
+            return { ok: false, reason: `Origin not allowed: ${origin}` };
+        }
+    }
+    const host = headers.host?.trim();
+    if (guard.enforceHost && host) {
+        const lowered = host.toLowerCase();
+        const hostname = hostHeaderHostname(host);
+        const allowed = (hostname !== undefined && isLoopbackHostname(hostname)) ||
+            guard.allowedHosts.includes(lowered) ||
+            (hostname !== undefined && guard.allowedHosts.includes(hostname.toLowerCase()));
+        if (!allowed) {
+            return { ok: false, reason: `Host not allowed: ${host}` };
+        }
+    }
+    return { ok: true };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,116 @@
+/**
+ * QMD MCP Server - Model Context Protocol server for QMD
+ *
+ * Exposes QMD search and document retrieval as MCP tools and resources.
+ * Documents are accessible via qmd:// URIs.
+ *
+ * Speaks MCP spec 2026-07-28 (stateless, no initialize handshake) and dual-speaks
+ * 2025-era clients via the official SDK entries (`serveStdio` / `createMcpHandler`).
+ */
+export type McpStartupOptions = {
+    dbPath?: string;
+};
+/**
+ * Counts running request handlers so shutdown can wait for them to settle
+ * before tearing down their llm/store dependencies. The SDK aborts in-flight
+ * request controllers on close, but qmd's handlers finish their current
+ * store/llm work rather than observing the signal mid-operation.
+ */
+export type InflightGate = {
+    /** Wraps a handler so the gate counts it while it runs. */
+    track<T extends (...args: never[]) => unknown>(fn: T): T;
+    /** Resolves once no tracked handler runs, or after timeoutMs. Returns whether idle was reached. */
+    waitForIdle(timeoutMs: number): Promise<boolean>;
+};
+export declare function createInflightGate(): InflightGate;
+/** Minimal stdin surface consumed by registerStdioEofShutdown, injectable for tests. */
+export type StdioShutdownStdin = {
+    once(event: "end" | "close", listener: () => void): unknown;
+    off(event: "end" | "close", listener: () => void): unknown;
+    readableEnded?: boolean;
+    destroyed?: boolean;
+};
+export type StdioShutdownOptions = {
+    /** Closes the MCP server and its transport. */
+    closeServer: () => Promise<void>;
+    /** Closes the SQLite store (owns disposing the per-store llama.cpp instance). */
+    closeStore: () => void | Promise<void>;
+    /**
+     * Optional extra llama.cpp teardown, run before closeStore. The MCP store
+     * disposes its own per-store LlamaCpp inside closeStore, so this is left
+     * unset there; it exists for callers that own a separate instance. If
+     * omitted, the step is skipped (do NOT default it to the global
+     * disposeDefaultLlamaCpp — that would tear down an unrelated instance in an
+     * embedded process).
+     */
+    disposeLlm?: () => Promise<void>;
+    /** Waits for in-flight handlers to settle (see InflightGate.waitForIdle). */
+    waitForIdle?: (timeoutMs: number) => Promise<boolean>;
+    /** Deadline for the in-flight wait. Defaults to 5000 ms. */
+    idleTimeoutMs?: number;
+    /** Defaults to process.stdin. */
+    stdin?: StdioShutdownStdin;
+    /** Defaults to assigning process.exitCode. */
+    setExitCode?: (code: number) => void;
+    /** Defaults to reading process.exitCode. */
+    getExitCode?: () => number | undefined;
+    /** Defaults to process.stderr. */
+    stderr?: {
+        write(chunk: string): unknown;
+        on?(event: "error", listener: (err: unknown) => void): unknown;
+    };
+};
+/**
+ * Shut the stdio MCP server down when stdin reaches EOF (#751).
+ *
+ * The SDK's StdioServerTransport subscribes to stdin "data"/"error" only and
+ * never notices "end"/"close". When the parent MCP client dies, nothing tears
+ * the process down: the warm llama.cpp model's native handles keep the event
+ * loop alive, so the server reparents to PID 1, leaks RAM, and keeps the
+ * SQLite index open. stdin EOF means the client is gone, so this treats it as
+ * a disconnect: no new requests are accepted and nobody is left to read a
+ * response — but handlers that are already running get a bounded window to
+ * settle (waitForIdle) before their llm/store dependencies are torn down.
+ *
+ * Teardown order matters. Close the transport first so no further requests
+ * are dispatched, wait for in-flight handlers, then close the store last —
+ * which disposes the store's own llama.cpp instance and then the database, so
+ * the dispose path cannot hit an already-closed DB. (disposeLlm is an optional
+ * extra step for callers that own a separate instance; the MCP store does
+ * not.) Failures are logged best-effort (the parent's death may have closed
+ * stderr too) and do not stop the remaining steps. The function sets process.exitCode
+ * instead of calling process.exit() so `beforeExit` still fires and
+ * node-llama-cpp's auto-dispose runs before libc's static destructors —
+ * process.exit() during native-addon unload has caused exit-time crashes
+ * before (#59, #129; same rationale as finishSuccessfulCliCommand in the CLI).
+ *
+ * Returns the idempotent shutdown function: every invocation (manual, "end",
+ * "close", or already-ended stdin) shares one promise, and the promise never
+ * rejects.
+ */
+export declare function registerStdioEofShutdown(options: StdioShutdownOptions): () => Promise<void>;
+export declare function startMcpServer(options?: McpStartupOptions): Promise<void>;
+export type HttpServerHandle = {
+    httpServer: import("http").Server;
+    port: number;
+    stop: () => Promise<void>;
+};
+/**
+ * Start MCP server over Streamable HTTP (JSON responses by default).
+ * Binds to `options.host` (default "localhost", overridable via the QMD_HOST
+ * env var) — set "0.0.0.0" to accept connections from other hosts, e.g. a
+ * container liveness probe. Returns a handle for shutdown and port discovery.
+ *
+ * HTTP is sessionless (MCP 2026-07-28): there is no `Mcp-Session-Id`, no
+ * initialize handshake, and no idle-session TTL. 2025-era clients are still
+ * served per-request via the SDK's stateless legacy fallback (initialize
+ * works as a standalone call; subsequent 2025 methods need a modern envelope
+ * or a stdio connection). The previous session reaper (#816) is gone because
+ * there are no sessions to reap.
+ */
+export declare function startMcpHttpServer(port: number, options?: ({
+    quiet?: boolean;
+    host?: string;
+    allowedOrigins?: string[];
+    allowedHosts?: string[];
+} & McpStartupOptions)): Promise<HttpServerHandle>;