@wei840222/qmd 2026.8.23

package/dist/cli/formatter.js

@@ -0,0 +1,355 @@
+/**
+ * formatter.ts - Output formatting utilities for QMD
+ *
+ * Provides methods to format search results and documents into various output formats:
+ * JSON, CSV, XML, Markdown, files list, and CLI (colored terminal output).
+ */
+import { extractSnippet } from "../store.js";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ * @param text The text to add line numbers to
+ * @param startLine Optional starting line number (default: 1)
+ */
+export function addLineNumbers(text, startLine = 1) {
+    const lines = text.split('\n');
+    return lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
+}
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export function getDocid(hash) {
+    return hash.slice(0, 6);
+}
+// =============================================================================
+// Escape Helpers
+// =============================================================================
+export function escapeCSV(value) {
+    if (value === null || value === undefined)
+        return "";
+    const str = String(value);
+    if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+        return `"${str.replace(/"/g, '""')}"`;
+    }
+    return str;
+}
+export function escapeXml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+// =============================================================================
+// Search Results Formatters
+// =============================================================================
+/**
+ * Format search results as JSON
+ */
+export function searchResultsToJson(results, opts = {}) {
+    const query = opts.query || "";
+    const output = results.map(row => {
+        const bodyStr = row.body || "";
+        const snippetInfo = bodyStr
+            ? extractSnippet(bodyStr, query, 300, row.chunkPos, undefined, opts.intent)
+            : undefined;
+        let body = opts.full ? bodyStr : undefined;
+        let snippet = !opts.full ? snippetInfo?.snippet : undefined;
+        if (opts.lineNumbers) {
+            if (body)
+                body = addLineNumbers(body);
+            if (snippet)
+                snippet = addLineNumbers(snippet);
+        }
+        return {
+            docid: `#${row.docid}`,
+            score: Math.round(row.score * 100) / 100,
+            file: row.displayPath,
+            ...(snippetInfo && { line: snippetInfo.line }),
+            title: row.title,
+            ...(row.context && { context: row.context }),
+            ...(body && { body }),
+            ...(snippet && { snippet }),
+        };
+    });
+    return JSON.stringify(output, null, 2);
+}
+/**
+ * Format search results as CSV
+ */
+export function searchResultsToCsv(results, opts = {}) {
+    const query = opts.query || "";
+    const header = "docid,score,file,title,context,line,snippet";
+    const rows = results.map(row => {
+        const bodyStr = row.body || "";
+        const { line, snippet } = extractSnippet(bodyStr, query, 500, row.chunkPos, undefined, opts.intent);
+        let content = opts.full ? bodyStr : snippet;
+        if (opts.lineNumbers && content) {
+            content = addLineNumbers(content);
+        }
+        return [
+            `#${row.docid}`,
+            row.score.toFixed(4),
+            escapeCSV(row.displayPath),
+            escapeCSV(row.title),
+            escapeCSV(row.context || ""),
+            line,
+            escapeCSV(content),
+        ].join(",");
+    });
+    return [header, ...rows].join("\n");
+}
+/**
+ * Format search results as simple files list (docid,score,filepath,context)
+ */
+export function searchResultsToFiles(results) {
+    return results.map(row => {
+        const ctx = row.context ? `,"${row.context.replace(/"/g, '""')}"` : "";
+        return `#${row.docid},${row.score.toFixed(2)},${row.displayPath}${ctx}`;
+    }).join("\n");
+}
+/**
+ * Format search results as Markdown
+ */
+export function searchResultsToMarkdown(results, opts = {}) {
+    const query = opts.query || "";
+    return results.map(row => {
+        const heading = row.title || row.displayPath;
+        const bodyStr = row.body || "";
+        let content;
+        if (opts.full) {
+            content = bodyStr;
+        }
+        else {
+            content = extractSnippet(bodyStr, query, 500, row.chunkPos, undefined, opts.intent).snippet;
+        }
+        if (opts.lineNumbers) {
+            content = addLineNumbers(content);
+        }
+        const fileLine = `**file:** \`${row.displayPath}\`\n`;
+        const contextLine = row.context ? `**context:** ${row.context}\n` : "";
+        return `---\n# ${heading}\n\n${fileLine}**docid:** \`#${row.docid}\`\n${contextLine}\n${content}\n`;
+    }).join("\n");
+}
+/**
+ * Format search results as XML
+ */
+export function searchResultsToXml(results, opts = {}) {
+    const query = opts.query || "";
+    const items = results.map(row => {
+        const titleAttr = row.title ? ` title="${escapeXml(row.title)}"` : "";
+        const bodyStr = row.body || "";
+        let content = opts.full ? bodyStr : extractSnippet(bodyStr, query, 500, row.chunkPos, undefined, opts.intent).snippet;
+        if (opts.lineNumbers) {
+            content = addLineNumbers(content);
+        }
+        const contextAttr = row.context ? ` context="${escapeXml(row.context)}"` : "";
+        return `<file docid="#${row.docid}" name="${escapeXml(row.displayPath)}"${titleAttr}${contextAttr}>\n${escapeXml(content)}\n</file>`;
+    });
+    return items.join("\n\n");
+}
+/**
+ * Format search results for MCP (simpler CSV format with pre-extracted snippets)
+ */
+export function searchResultsToMcpCsv(results) {
+    const header = "docid,file,title,score,context,snippet";
+    const rows = results.map(r => [`#${r.docid}`, r.file, r.title, r.score, r.context || "", r.snippet].map(escapeCSV).join(","));
+    return [header, ...rows].join("\n");
+}
+// =============================================================================
+// Document Formatters (for multi-get using MultiGetFile from store)
+// =============================================================================
+/**
+ * Format documents as JSON
+ */
+export function documentsToJson(results) {
+    const output = results.map(r => ({
+        file: r.displayPath,
+        title: r.title,
+        ...(r.context && { context: r.context }),
+        ...(r.skipped ? { skipped: true, reason: r.skipReason } : { body: r.body }),
+    }));
+    return JSON.stringify(output, null, 2);
+}
+/**
+ * Format documents as CSV
+ */
+export function documentsToCsv(results) {
+    const header = "file,title,context,skipped,body";
+    const rows = results.map(r => [
+        r.displayPath,
+        r.title,
+        r.context || "",
+        r.skipped ? "true" : "false",
+        r.skipped ? (r.skipReason || "") : r.body
+    ].map(escapeCSV).join(","));
+    return [header, ...rows].join("\n");
+}
+/**
+ * Format documents as files list
+ */
+export function documentsToFiles(results) {
+    return results.map(r => {
+        const ctx = r.context ? `,"${r.context.replace(/"/g, '""')}"` : "";
+        const status = r.skipped ? ",[SKIPPED]" : "";
+        return `${r.displayPath}${ctx}${status}`;
+    }).join("\n");
+}
+/**
+ * Format documents as Markdown
+ */
+export function documentsToMarkdown(results) {
+    return results.map(r => {
+        let md = `## ${r.displayPath}\n\n`;
+        if (r.title && r.title !== r.displayPath)
+            md += `**Title:** ${r.title}\n\n`;
+        if (r.context)
+            md += `**Context:** ${r.context}\n\n`;
+        if (r.skipped) {
+            md += `> ${r.skipReason}\n`;
+        }
+        else {
+            md += "```\n" + r.body + "\n```\n";
+        }
+        return md;
+    }).join("\n");
+}
+/**
+ * Format documents as XML
+ */
+export function documentsToXml(results) {
+    const items = results.map(r => {
+        let xml = "  <document>\n";
+        xml += `    <file>${escapeXml(r.displayPath)}</file>\n`;
+        xml += `    <title>${escapeXml(r.title)}</title>\n`;
+        if (r.context)
+            xml += `    <context>${escapeXml(r.context)}</context>\n`;
+        if (r.skipped) {
+            xml += `    <skipped>true</skipped>\n`;
+            xml += `    <reason>${escapeXml(r.skipReason || "")}</reason>\n`;
+        }
+        else {
+            xml += `    <body>${escapeXml(r.body)}</body>\n`;
+        }
+        xml += "  </document>";
+        return xml;
+    });
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<documents>\n${items.join("\n")}\n</documents>`;
+}
+// =============================================================================
+// Single Document Formatters
+// =============================================================================
+/**
+ * Format a single DocumentResult as JSON
+ */
+export function documentToJson(doc) {
+    return JSON.stringify({
+        file: doc.displayPath,
+        title: doc.title,
+        ...(doc.context && { context: doc.context }),
+        hash: doc.hash,
+        modifiedAt: doc.modifiedAt,
+        bodyLength: doc.bodyLength,
+        ...(doc.body !== undefined && { body: doc.body }),
+    }, null, 2);
+}
+/**
+ * Format a single DocumentResult as Markdown
+ */
+export function documentToMarkdown(doc) {
+    let md = `# ${doc.title || doc.displayPath}\n\n`;
+    if (doc.context)
+        md += `**Context:** ${doc.context}\n\n`;
+    md += `**File:** ${doc.displayPath}\n`;
+    md += `**Modified:** ${doc.modifiedAt}\n\n`;
+    if (doc.body !== undefined) {
+        md += "---\n\n" + doc.body + "\n";
+    }
+    return md;
+}
+/**
+ * Format a single DocumentResult as XML
+ */
+export function documentToXml(doc) {
+    let xml = `<?xml version="1.0" encoding="UTF-8"?>\n<document>\n`;
+    xml += `  <file>${escapeXml(doc.displayPath)}</file>\n`;
+    xml += `  <title>${escapeXml(doc.title)}</title>\n`;
+    if (doc.context)
+        xml += `  <context>${escapeXml(doc.context)}</context>\n`;
+    xml += `  <hash>${escapeXml(doc.hash)}</hash>\n`;
+    xml += `  <modifiedAt>${escapeXml(doc.modifiedAt)}</modifiedAt>\n`;
+    xml += `  <bodyLength>${doc.bodyLength}</bodyLength>\n`;
+    if (doc.body !== undefined) {
+        xml += `  <body>${escapeXml(doc.body)}</body>\n`;
+    }
+    xml += `</document>`;
+    return xml;
+}
+/**
+ * Format a single document to the specified format
+ */
+export function formatDocument(doc, format) {
+    switch (format) {
+        case "json":
+            return documentToJson(doc);
+        case "md":
+            return documentToMarkdown(doc);
+        case "xml":
+            return documentToXml(doc);
+        default:
+            // Default to markdown for CLI and other formats
+            return documentToMarkdown(doc);
+    }
+}
+// =============================================================================
+// Universal Format Function
+// =============================================================================
+/**
+ * Format search results to the specified output format
+ */
+export function formatSearchResults(results, format, opts = {}) {
+    switch (format) {
+        case "json":
+            return searchResultsToJson(results, opts);
+        case "csv":
+            return searchResultsToCsv(results, opts);
+        case "files":
+            return searchResultsToFiles(results);
+        case "md":
+            return searchResultsToMarkdown(results, opts);
+        case "xml":
+            return searchResultsToXml(results, opts);
+        case "cli":
+            // CLI format should be handled separately with colors
+            // Return a simple text version as fallback
+            return searchResultsToMarkdown(results, opts);
+        default:
+            return searchResultsToJson(results, opts);
+    }
+}
+/**
+ * Format documents to the specified output format
+ */
+export function formatDocuments(results, format) {
+    switch (format) {
+        case "json":
+            return documentsToJson(results);
+        case "csv":
+            return documentsToCsv(results);
+        case "files":
+            return documentsToFiles(results);
+        case "md":
+            return documentsToMarkdown(results);
+        case "xml":
+            return documentsToXml(results);
+        case "cli":
+            // CLI format should be handled separately with colors
+            return documentsToMarkdown(results);
+        default:
+            return documentsToJson(results);
+    }
+}

package/dist/cli/mcp-pid.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP daemon pidfile identity helpers.
+ *
+ * Pidfiles alone are unsafe after PID reuse (e.g. post-reboot). Callers must
+ * confirm a recorded PID still belongs to a qmd process before signalling it
+ * or treating it as "already running".
+ */
+/**
+ * Pid/log filenames for the MCP HTTP daemon.
+ * The default index keeps `mcp.pid` / `mcp.log` for compatibility; named
+ * indexes are scoped so a named daemon can run alongside the default (#772).
+ */
+export declare function mcpDaemonStateFiles(indexName?: string): {
+    pidFile: string;
+    logFile: string;
+};
+/** True if a process command line looks like a qmd CLI invocation. */
+export declare function looksLikeQmdMcpCommand(cmdline: string): boolean;
+/** Read process cmdline (Linux /proc preferred; ps fallback for macOS). */
+export declare function readProcessCmdline(pid: number): string | null;
+/**
+ * Returns true only if `pid` is alive AND its command line looks like qmd.
+ * If cmdline cannot be read or does not match, returns false (treat as stale).
+ */
+export declare function isQmdMcpPid(pid: number): boolean;

package/dist/cli/mcp-pid.js

@@ -0,0 +1,86 @@
+/**
+ * MCP daemon pidfile identity helpers.
+ *
+ * Pidfiles alone are unsafe after PID reuse (e.g. post-reboot). Callers must
+ * confirm a recorded PID still belongs to a qmd process before signalling it
+ * or treating it as "already running".
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+/**
+ * Pid/log filenames for the MCP HTTP daemon.
+ * The default index keeps `mcp.pid` / `mcp.log` for compatibility; named
+ * indexes are scoped so a named daemon can run alongside the default (#772).
+ */
+export function mcpDaemonStateFiles(indexName = "index") {
+    const suffix = !indexName || indexName === "index" ? "" : `-${indexName}`;
+    return {
+        pidFile: `mcp${suffix}.pid`,
+        logFile: `mcp${suffix}.log`,
+    };
+}
+/** True if a process command line looks like a qmd CLI invocation. */
+export function looksLikeQmdMcpCommand(cmdline) {
+    const s = cmdline.trim();
+    if (!s)
+        return false;
+    // Match bare `qmd`, `qmd.ts`/`qmd.js`, or a path ending in /qmd(.ts|.js)
+    return /(?:^|[\s/\\])qmd(?:\.(?:ts|js))?(?:[\s]|$)/i.test(s);
+}
+/** Read process cmdline (Linux /proc preferred; ps fallback for macOS). */
+export function readProcessCmdline(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const procPath = `/proc/${pid}/cmdline`;
+    if (existsSync(procPath)) {
+        try {
+            const raw = readFileSync(procPath, "utf-8");
+            const cmdline = raw.replace(/\0/g, " ").trim();
+            if (cmdline)
+                return cmdline;
+        }
+        catch {
+            // fall through to ps
+        }
+    }
+    try {
+        let cmdline = "";
+        try {
+            cmdline = execFileSync("ps", ["-p", String(pid), "-o", "args="], {
+                encoding: "utf-8",
+                timeout: 2000,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        catch {
+            cmdline = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+                encoding: "utf-8",
+                timeout: 2000,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        const trimmed = cmdline.trim();
+        return trimmed || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true only if `pid` is alive AND its command line looks like qmd.
+ * If cmdline cannot be read or does not match, returns false (treat as stale).
+ */
+export function isQmdMcpPid(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return false;
+    }
+    const cmdline = readProcessCmdline(pid);
+    if (!cmdline)
+        return false;
+    return looksLikeQmdMcpCommand(cmdline);
+}

package/dist/cli/qmd.d.ts

@@ -0,0 +1,72 @@
+import { type ExpandedQuery } from "../store.js";
+import type { EmbeddingProviderOwner } from "../embedding/provider.js";
+import { type OutputFormat } from "./formatter.js";
+export interface CliResourceCloserOptions {
+    getOwner(): EmbeddingProviderOwner | null;
+    clearOwner(): void;
+    disposeFallback(): Promise<void>;
+    closeStore(): void;
+}
+export declare function createCliResourceCloser(options: CliResourceCloserOptions): () => Promise<void>;
+type CliLifecycleWritable = {
+    write(chunk: string | Uint8Array, callback?: (error?: Error | null) => void): boolean;
+};
+type FinishSuccessfulCliCommandOptions = {
+    command: string;
+    format?: OutputFormat;
+    cleanup?: () => Promise<void>;
+    exit?: (code: number) => void;
+    stdout?: CliLifecycleWritable;
+    stderr?: CliLifecycleWritable;
+};
+/**
+ * Finish a successful CLI command after output has been flushed.
+ *
+ * We deliberately do NOT call `process.exit(0)`. `process.exit()` skips
+ * Node's `beforeExit` event, and node-llama-cpp registers a `beforeExit` hook
+ * that auto-disposes its native handles. On darwin, without that hook firing,
+ * libggml-metal's static `ggml_metal_device` destructor asserts on a
+ * non-empty residency-set collection during `__cxa_finalize_ranges` and
+ * dumps a multi-kB backtrace (upstream ggml-org/llama.cpp#22593, fix open as
+ * PR #22595). Empirically, even with explicit `disposeDefaultLlamaCpp()` the
+ * direct `process.exit(0)` path still trips the assertion — letting the
+ * event loop drain naturally is what actually clears the rsets.
+ *
+ * So: set `process.exitCode = 0` and return. The main module finishes, the
+ * event loop drains, `beforeExit` fires, native resources tear down in
+ * order, and the process exits cleanly. The `GGML_METAL_NO_RESIDENCY=1` env
+ * var that `bin/qmd` exports is a defense-in-depth safety net for paths
+ * that still call `process.exit()` after loading the native binding
+ * (signal handlers, error paths, `bun test`).
+ *
+ * If the caller passes an explicit `exit` for testability, we honor it —
+ * the lifecycle tests verify the legacy flush → cleanup → exit ordering.
+ * Production callers must not pass `exit`.
+ */
+export declare function finishSuccessfulCliCommand(options: FinishSuccessfulCliCommandOptions): Promise<void>;
+export declare function resolveEmbedModelForCli(): string;
+export declare function resolveGenerateModelForCli(): string;
+export declare function resolveRerankModelForCli(): string;
+export declare function buildEditorUri(template: string, absolutePath: string, line: number, col: number): string;
+export declare function termLink(text: string, url: string, isTTY?: boolean): string;
+/**
+ * Parse structured search query syntax.
+ * Lines starting with lex:, vec:, or hyde: are routed directly.
+ * Plain lines without prefix go through query expansion.
+ *
+ * Returns null if this is a plain query (single line, no prefix).
+ * Returns ExpandedQuery[] if structured syntax detected.
+ * Throws if multiple plain lines (ambiguous).
+ *
+ * Examples:
+ *   "CAP theorem"                    -> null (plain query, use expansion)
+ *   "lex: CAP theorem"               -> null (explicit shared-policy skip)
+ *   "lex: CAP\nvec: consistency"     -> [{ type: 'lex', ... }, { type: 'vec', ... }]
+ *   "CAP\nconsistency"               -> throws (multiple plain lines)
+ */
+interface ParsedStructuredQuery {
+    searches: ExpandedQuery[];
+    intent?: string;
+}
+export declare function parseStructuredQuery(query: string): ParsedStructuredQuery | null;
+export {};