ko-qmd 2.8.3-ko.10

package/dist/cli/formatter.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 type { SearchResult, MultiGetResult, DocumentResult } from "../store.js";
+export type { SearchResult, MultiGetResult, DocumentResult };
+export type MultiGetFile = {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    context?: string | null;
+    skipped: false;
+} | {
+    filepath: string;
+    displayPath: string;
+    title: string;
+    body: string;
+    context?: string | null;
+    skipped: true;
+    skipReason: string;
+};
+export type OutputFormat = "cli" | "csv" | "md" | "xml" | "files" | "json";
+export type FormatOptions = {
+    full?: boolean;
+    query?: string;
+    useColor?: boolean;
+    lineNumbers?: boolean;
+    intent?: string;
+};
+/**
+ * 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 declare function addLineNumbers(text: string, startLine?: number): string;
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export declare function getDocid(hash: string): string;
+export declare function escapeCSV(value: string | null | number): string;
+export declare function escapeXml(str: string): string;
+/**
+ * Format search results as JSON
+ */
+export declare function searchResultsToJson(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as CSV
+ */
+export declare function searchResultsToCsv(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as simple files list (docid,score,filepath,context)
+ */
+export declare function searchResultsToFiles(results: SearchResult[]): string;
+/**
+ * Format search results as Markdown
+ */
+export declare function searchResultsToMarkdown(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results as XML
+ */
+export declare function searchResultsToXml(results: SearchResult[], opts?: FormatOptions): string;
+/**
+ * Format search results for MCP (simpler CSV format with pre-extracted snippets)
+ */
+export declare function searchResultsToMcpCsv(results: {
+    docid: string;
+    file: string;
+    title: string;
+    score: number;
+    context: string | null;
+    snippet: string;
+}[]): string;
+/**
+ * Format documents as JSON
+ */
+export declare function documentsToJson(results: MultiGetFile[]): string;
+/**
+ * Format documents as CSV
+ */
+export declare function documentsToCsv(results: MultiGetFile[]): string;
+/**
+ * Format documents as files list
+ */
+export declare function documentsToFiles(results: MultiGetFile[]): string;
+/**
+ * Format documents as Markdown
+ */
+export declare function documentsToMarkdown(results: MultiGetFile[]): string;
+/**
+ * Format documents as XML
+ */
+export declare function documentsToXml(results: MultiGetFile[]): string;
+/**
+ * Format a single DocumentResult as JSON
+ */
+export declare function documentToJson(doc: DocumentResult): string;
+/**
+ * Format a single DocumentResult as Markdown
+ */
+export declare function documentToMarkdown(doc: DocumentResult): string;
+/**
+ * Format a single DocumentResult as XML
+ */
+export declare function documentToXml(doc: DocumentResult): string;
+/**
+ * Format a single document to the specified format
+ */
+export declare function formatDocument(doc: DocumentResult, format: OutputFormat): string;
+/**
+ * Format search results to the specified output format
+ */
+export declare function formatSearchResults(results: SearchResult[], format: OutputFormat, opts?: FormatOptions): string;
+/**
+ * Format documents to the specified output format
+ */
+export declare function formatDocuments(results: MultiGetFile[], format: OutputFormat): string;

package/dist/cli/formatter.js

@@ -0,0 +1,60 @@
+var g=Object.defineProperty;var c=(t,n)=>g(t,"name",{value:n,configurable:!0});import{extractSnippet as x}from"../store.js";function p(t,n=1){return t.split(`
+`).map((i,o)=>`${n+o}: ${i}`).join(`
+`)}c(p,"addLineNumbers");function F(t){return t.slice(0,6)}c(F,"getDocid");function r(t){if(t==null)return"";const n=String(t);return n.includes(",")||n.includes('"')||n.includes(`
+`)?`"${n.replace(/"/g,'""')}"`:n}c(r,"escapeCSV");function u(t){return t.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&apos;")}c(u,"escapeXml");function m(t,n={}){const e=n.query||"",i=t.map(o=>{const s=o.body||"",d=s?x(s,e,300,o.chunkPos,void 0,n.intent):void 0;let l=n.full?s:void 0,a=n.full?void 0:d?.snippet;return n.lineNumbers&&(l&&(l=p(l)),a&&(a=p(a))),{docid:`#${o.docid}`,score:Math.round(o.score*100)/100,file:o.displayPath,...d&&{line:d.line},title:o.title,...o.context&&{context:o.context},...l&&{body:l},...a&&{snippet:a}}});return JSON.stringify(i,null,2)}c(m,"searchResultsToJson");function P(t,n={}){const e=n.query||"",i="docid,score,file,title,context,line,snippet",o=t.map(s=>{const d=s.body||"",{line:l,snippet:a}=x(d,e,500,s.chunkPos,void 0,n.intent);let f=n.full?d:a;return n.lineNumbers&&f&&(f=p(f)),[`#${s.docid}`,s.score.toFixed(4),r(s.displayPath),r(s.title),r(s.context||""),l,r(f)].join(",")});return[i,...o].join(`
+`)}c(P,"searchResultsToCsv");function k(t){return t.map(n=>{const e=n.context?`,"${n.context.replace(/"/g,'""')}"`:"";return`#${n.docid},${n.score.toFixed(2)},${n.displayPath}${e}`}).join(`
+`)}c(k,"searchResultsToFiles");function y(t,n={}){const e=n.query||"";return t.map(i=>{const o=i.title||i.displayPath,s=i.body||"";let d;n.full?d=s:d=x(s,e,500,i.chunkPos,void 0,n.intent).snippet,n.lineNumbers&&(d=p(d));const l=`**file:** \`${i.displayPath}\`
+`,a=i.context?`**context:** ${i.context}
+`:"";return`---
+# ${o}
+
+${l}**docid:** \`#${i.docid}\`
+${a}
+${d}
+`}).join(`
+`)}c(y,"searchResultsToMarkdown");function T(t,n={}){const e=n.query||"";return t.map(o=>{const s=o.title?` title="${u(o.title)}"`:"",d=o.body||"";let l=n.full?d:x(d,e,500,o.chunkPos,void 0,n.intent).snippet;n.lineNumbers&&(l=p(l));const a=o.context?` context="${u(o.context)}"`:"";return`<file docid="#${o.docid}" name="${u(o.displayPath)}"${s}${a}>
+${u(l)}
+</file>`}).join(`
+
+`)}c(T,"searchResultsToXml");function C(t){const n="docid,file,title,score,context,snippet",e=t.map(i=>[`#${i.docid}`,i.file,i.title,i.score,i.context||"",i.snippet].map(r).join(","));return[n,...e].join(`
+`)}c(C,"searchResultsToMcpCsv");function h(t){const n=t.map(e=>({file:e.displayPath,title:e.title,...e.context&&{context:e.context},...e.skipped?{skipped:!0,reason:e.skipReason}:{body:e.body}}));return JSON.stringify(n,null,2)}c(h,"documentsToJson");function j(t){const n="file,title,context,skipped,body",e=t.map(i=>[i.displayPath,i.title,i.context||"",i.skipped?"true":"false",i.skipped?i.skipReason||"":i.body].map(r).join(","));return[n,...e].join(`
+`)}c(j,"documentsToCsv");function S(t){return t.map(n=>{const e=n.context?`,"${n.context.replace(/"/g,'""')}"`:"",i=n.skipped?",[SKIPPED]":"";return`${n.displayPath}${e}${i}`}).join(`
+`)}c(S,"documentsToFiles");function $(t){return t.map(n=>{let e=`## ${n.displayPath}
+
+`;return n.title&&n.title!==n.displayPath&&(e+=`**Title:** ${n.title}
+
+`),n.context&&(e+=`**Context:** ${n.context}
+
+`),n.skipped?e+=`> ${n.skipReason}
+`:e+="```\n"+n.body+"\n```\n",e}).join(`
+`)}c($,"documentsToMarkdown");function R(t){return`<?xml version="1.0" encoding="UTF-8"?>
+<documents>
+${t.map(e=>{let i=`  <document>
+`;return i+=`    <file>${u(e.displayPath)}</file>
+`,i+=`    <title>${u(e.title)}</title>
+`,e.context&&(i+=`    <context>${u(e.context)}</context>
+`),e.skipped?(i+=`    <skipped>true</skipped>
+`,i+=`    <reason>${u(e.skipReason||"")}</reason>
+`):i+=`    <body>${u(e.body)}</body>
+`,i+="  </document>",i}).join(`
+`)}
+</documents>`}c(R,"documentsToXml");function q(t){return JSON.stringify({file:t.displayPath,title:t.title,...t.context&&{context:t.context},hash:t.hash,modifiedAt:t.modifiedAt,bodyLength:t.bodyLength,...t.body!==void 0&&{body:t.body}},null,2)}c(q,"documentToJson");function b(t){let n=`# ${t.title||t.displayPath}
+
+`;return t.context&&(n+=`**Context:** ${t.context}
+
+`),n+=`**File:** ${t.displayPath}
+`,n+=`**Modified:** ${t.modifiedAt}
+
+`,t.body!==void 0&&(n+=`---
+
+`+t.body+`
+`),n}c(b,"documentToMarkdown");function A(t){let n=`<?xml version="1.0" encoding="UTF-8"?>
+<document>
+`;return n+=`  <file>${u(t.displayPath)}</file>
+`,n+=`  <title>${u(t.title)}</title>
+`,t.context&&(n+=`  <context>${u(t.context)}</context>
+`),n+=`  <hash>${u(t.hash)}</hash>
+`,n+=`  <modifiedAt>${u(t.modifiedAt)}</modifiedAt>
+`,n+=`  <bodyLength>${t.bodyLength}</bodyLength>
+`,t.body!==void 0&&(n+=`  <body>${u(t.body)}</body>
+`),n+="</document>",n}c(A,"documentToXml");function J(t,n){switch(n){case"json":return q(t);case"md":return b(t);case"xml":return A(t);default:return b(t)}}c(J,"formatDocument");function M(t,n,e={}){switch(n){case"json":return m(t,e);case"csv":return P(t,e);case"files":return k(t);case"md":return y(t,e);case"xml":return T(t,e);case"cli":return y(t,e);default:return m(t,e)}}c(M,"formatSearchResults");function v(t,n){switch(n){case"json":return h(t);case"csv":return j(t);case"files":return S(t);case"md":return $(t);case"xml":return R(t);case"cli":return $(t);default:return h(t)}}c(v,"formatDocuments");export{p as addLineNumbers,q as documentToJson,b as documentToMarkdown,A as documentToXml,j as documentsToCsv,S as documentsToFiles,h as documentsToJson,$ as documentsToMarkdown,R as documentsToXml,r as escapeCSV,u as escapeXml,J as formatDocument,v as formatDocuments,M as formatSearchResults,F as getDocid,P as searchResultsToCsv,k as searchResultsToFiles,m as searchResultsToJson,y as searchResultsToMarkdown,C as searchResultsToMcpCsv,T as searchResultsToXml};

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

@@ -0,0 +1,33 @@
+/**
+ * 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;
+};
+/**
+ * Open (truncate-or-create) the daemon mcp.log with owner-only permissions.
+ * The daemon log carries query text, so it mirrors the 0600 convention of
+ * the opt-in query log (appendFile mode 0o600). The explicit open mode
+ * covers creation; fchmod covers truncation of a pre-existing file, where
+ * the open mode is ignored.
+ */
+export declare function openDaemonLogFile(logPath: string): number;
+/** 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 @@
+var c=Object.defineProperty;var r=(t,e)=>c(t,"name",{value:e,configurable:!0});import{existsSync as s,fchmodSync as m,openSync as l,readFileSync as u}from"node:fs";import{execFileSync as i}from"node:child_process";function y(t="index"){const e=!t||t==="index"?"":`-${t}`;return{pidFile:`mcp${e}.pid`,logFile:`mcp${e}.log`}}r(y,"mcpDaemonStateFiles");function x(t){const e=l(t,"w",384);return m(e,384),e}r(x,"openDaemonLogFile");function f(t){const e=t.trim();return e?/(?:^|[\s/\\])qmd(?:\.(?:ts|js))?(?:[\s]|$)/i.test(e):!1}r(f,"looksLikeQmdMcpCommand");function p(t){if(!Number.isInteger(t)||t<=0)return null;const e=`/proc/${t}/cmdline`;if(s(e))try{const o=u(e,"utf-8").replace(/\0/g," ").trim();if(o)return o}catch{}try{let n="";try{n=i("ps",["-p",String(t),"-o","args="],{encoding:"utf-8",timeout:2e3,stdio:["ignore","pipe","ignore"]})}catch{n=i("ps",["-p",String(t),"-o","command="],{encoding:"utf-8",timeout:2e3,stdio:["ignore","pipe","ignore"]})}return n.trim()||null}catch{return null}}r(p,"readProcessCmdline");function S(t){if(!Number.isInteger(t)||t<=0)return!1;try{process.kill(t,0)}catch{return!1}const e=p(t);return e?f(e):!1}r(S,"isQmdMcpPid");export{S as isQmdMcpPid,f as looksLikeQmdMcpCommand,y as mcpDaemonStateFiles,x as openDaemonLogFile,p as readProcessCmdline};

package/dist/cli/qmd.d.ts

@@ -0,0 +1,101 @@
+import { spawn as nodeSpawn } from "child_process";
+import { type RRFContributionTrace, generateEmbeddings, type ChunkStrategy } from "../store.js";
+import { type OutputFormat } from "./formatter.js";
+export declare const DEFAULT_MCP_PORT = 8181;
+export declare function resolveMcpPort(raw: unknown): number;
+/**
+ * Wait until a freshly spawned `--daemon` child reports listening in its log
+ * file, or fail. The daemon branch must not print `Started` before this
+ * resolves: a bind failure (e.g. an occupied port) would otherwise exit 0
+ * while the child dies and its exit handler removes the pidfile, leaving
+ * `stop` reporting Not running. On failure no pidfile is written, so
+ * `stop`/`status` keep their missing-pidfile behavior.
+ */
+export declare function waitForDaemonListening(child: ReturnType<typeof nodeSpawn>, logPath: string, timeoutMs?: number): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}>;
+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>;
+/**
+ * Render an absolute filesystem path for human display under --full-path.
+ *
+ * If the path is the current working directory or a subpath of it, return a
+ * "./"-prefixed relative path so it is unambiguously a filesystem path (not a
+ * bare collection-relative string that could be confused for a `qmd://`
+ * fragment). Otherwise return the absolute realpath so symlinks resolve
+ * consistently. Returns `null` if the path could not be normalized (deleted
+ * between the caller's existsSync check and now) — callers fall back to
+ * whatever they had before plus the stale-index stderr warning.
+ */
+export declare function renderFullPath(absolutePath: string, cwd?: string): string | null;
+export declare function parseEmbedBatchMbOption(value: unknown): number | undefined;
+export declare function resolveEmbedModelForCli(): string;
+export declare function resolveGenerateModelForCli(): string;
+export declare function resolveRerankModelForCli(): string;
+export declare function vectorIndex(model?: string, force?: boolean, batchOptions?: {
+    maxDocsPerBatch?: number;
+    maxBatchBytes?: number;
+    chunkStrategy?: ChunkStrategy;
+    collection?: string;
+    maxDurationMs?: number;
+}, deps?: {
+    runEmbeddings?: typeof generateEmbeddings;
+}): Promise<void>;
+/**
+ * Which sub-query found this document, and where did it place in that sub-query's own list?
+ *
+ * Expansion turns one query into a dozen, fuses their lists and reports one number. A single
+ * fused rank cannot say whether a result placed first in the hyde list and nowhere else, or
+ * middling everywhere — and those call for different fixes. Each expansion gets a line, with
+ * the sub-query text it ran, so the fused score can be read back to the query that earned it.
+ */
+export declare function explainGroupLines(contributions: readonly RRFContributionTrace[]): string[];
+export declare function formatScore(score: number): 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;
+/**
+ * Resolve the effective MCP HTTP bind host (single source of truth).
+ * Same precedence the daemon child uses in startMcpHttpServer:
+ * `--host` flag ?? QMD_HOST env ?? "localhost". The daemon parent uses
+ * this for both the Started announcement and the explicit --host passed
+ * to the child, so the announced URL always matches the actual bind.
+ */
+export declare function resolveDaemonHost(flagHost: string | undefined): string;
+export {};