ko-qmd 2.8.3-ko.10

package/dist/metadata-filter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * QMD Metadata Filter - Recursive filter AST, strict runtime validation, and
+ * parameterized SQL compilation.
+ *
+ * The filter has one canonical, `operator`-discriminated recursive shape shared
+ * by every public search surface (CLI, SDK, MCP, HTTP):
+ *
+ *   { "operator": "and", "operands": [ ... ] }
+ *   { "operator": "not", "operand": { ... } }
+ *   { "key": "status", "operator": "eq", "value": "published" }
+ *
+ * Compilation emits correlated EXISTS/NOT EXISTS subqueries over
+ * `document_metadata_values` with every user value bound as a parameter —
+ * metadata keys and values are data, never SQL.
+ */
+import type { MetadataScalar, MetadataScalarArray } from "./metadata.js";
+export type MetadataFilter = MetadataFilterGroup | MetadataFilterNegation | MetadataCondition;
+export interface MetadataFilterGroup {
+    operator: "and" | "or";
+    operands: readonly MetadataFilter[];
+}
+export interface MetadataFilterNegation {
+    operator: "not";
+    operand: MetadataFilter;
+}
+export type MetadataCondition = {
+    key: string;
+    operator: "eq" | "ne";
+    value: MetadataScalar;
+} | {
+    key: string;
+    operator: "gt" | "gte" | "lt" | "lte";
+    value: string | number;
+} | {
+    key: string;
+    operator: "in" | "nin" | "all";
+    value: MetadataScalarArray;
+} | {
+    key: string;
+    operator: "exists";
+    value: boolean;
+};
+export interface CompiledMetadataFilter {
+    sql: string;
+    params: (string | number)[];
+}
+/** Raised by parseMetadataFilter with the JSON path of the failing node. */
+export declare class MetadataFilterError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+/** Defensive limits for recursive filters from untrusted callers. */
+export declare const METADATA_FILTER_LIMITS: {
+    readonly maxDepth: 16;
+    readonly maxNodes: 256;
+    readonly maxGroupOperands: 32;
+    readonly maxMembershipValues: 64;
+    readonly maxKeyBytes: 128;
+    readonly maxStringLength: 1024;
+};
+/**
+ * Strictly validate an untrusted value as a MetadataFilter.
+ * Rejects unknown operators, unknown properties, operator-incompatible values,
+ * and inputs exceeding METADATA_FILTER_LIMITS. Canonicalizes membership value
+ * arrays by de-duplicating while preserving order.
+ */
+export declare function parseMetadataFilter(input: unknown): MetadataFilter;
+/**
+ * Compile a validated filter into one parameterized SQL predicate correlated
+ * against a documents-table alias (e.g. `d`). All keys and values are bound
+ * parameters. The caller is responsible for restricting the surrounding query
+ * to active documents with current, error-free metadata extraction.
+ */
+export declare function compileMetadataFilter(filter: MetadataFilter, documentsAlias: string): CompiledMetadataFilter;

package/dist/metadata-filter.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var a=(e,n)=>h(e,"name",{value:n,configurable:!0});import{METADATA_LIMITS as d}from"./metadata.js";class u extends Error{static{a(this,"MetadataFilterError")}path;constructor(n,r){super(`Invalid metadata filter at ${n}: ${r}`),this.name="MetadataFilterError",this.path=n}}const i={maxDepth:16,maxNodes:256,maxGroupOperands:32,maxMembershipValues:64,maxKeyBytes:d.maxKeyBytes,maxStringLength:d.maxStringLength},x=new Set(["and","or"]),N=new Set(["eq","ne","gt","gte","lt","lte"]),b=new Set(["gt","gte","lt","lte"]),A=new Set(["in","nin","all"]),g=new Set([...N,...A,"exists"]),O=[...x,"not",...g];function R(e){return $(e,"$",1,{nodes:0})}a(R,"parseMetadataFilter");function $(e,n,r,t){if(r>i.maxDepth)throw new u(n,`exceeds maximum nesting depth of ${i.maxDepth}`);if(t.nodes+=1,t.nodes>i.maxNodes)throw new u(n,`exceeds maximum of ${i.maxNodes} nodes`);if(typeof e!="object"||e===null||Array.isArray(e))throw new u(n,"each filter node must be an object");const o=e,s=o.operator;if(typeof s!="string")throw new u(n,"missing 'operator' property");if(x.has(s))return k(o,s,n,r,t);if(s==="not")return D(o,n,r,t);if(g.has(s))return q(o,s,n);throw new u(n,`unknown operator '${s}' \u2014 expected one of: ${O.join(", ")}`)}a($,"parseFilterNode");function k(e,n,r,t,o){w(e,["operator","operands"],r);const s=e.operands;if(!Array.isArray(s))throw new u(r,`'${n}' requires an 'operands' array`);if(s.length===0)throw new u(r,`'${n}' requires a non-empty 'operands' array`);if(s.length>i.maxGroupOperands)throw new u(r,`'${n}' exceeds maximum of ${i.maxGroupOperands} operands`);return{operator:n,operands:s.map((c,p)=>$(c,`${r}.operands[${p}]`,t+1,o))}}a(k,"parseFilterGroup");function D(e,n,r,t){if(w(e,["operator","operand"],n),!("operand"in e))throw new u(n,"'not' requires exactly one 'operand'");return{operator:"not",operand:$(e.operand,`${n}.operand`,r+1,t)}}a(D,"parseFilterNegation");function q(e,n,r){w(e,["key","operator","value"],r);const t=e.key;if(typeof t!="string"||t.length===0)throw new u(r,`'${n}' requires a non-empty string 'key'`);if(Buffer.byteLength(t,"utf-8")>i.maxKeyBytes)throw new u(r,`'key' exceeds ${i.maxKeyBytes} bytes`);if(!("value"in e))throw new u(r,`'${n}' requires a 'value'`);const o=e.value;if(n==="exists"){if(typeof o!="boolean")throw new u(`${r}.value`,"'exists' requires a boolean value");return{key:t,operator:n,value:o}}if(A.has(n))return{key:t,operator:n,value:T(o,n,r)};const s=S(o,`${r}.value`);if(b.has(n)&&typeof s=="boolean")throw new u(`${r}.value`,`'${n}' requires a string or number value`);return{key:t,operator:n,value:s}}a(q,"parseFilterCondition");function T(e,n,r){if(!Array.isArray(e))throw new u(`${r}.value`,`'${n}' requires an array value`);if(e.length===0)throw new u(`${r}.value`,`'${n}' requires a non-empty array value`);if(e.length>i.maxMembershipValues)throw new u(`${r}.value`,`'${n}' exceeds maximum of ${i.maxMembershipValues} values`);const t=e.map((o,s)=>S(o,`${r}.value[${s}]`));if(t.every(o=>typeof o=="string"))return Array.from(new Set(t));if(t.every(o=>typeof o=="number"))return Array.from(new Set(t));if(t.every(o=>typeof o=="boolean"))return Array.from(new Set(t));throw new u(`${r}.value`,`'${n}' requires a homogeneous array of one scalar type`)}a(T,"parseMembershipValues");function S(e,n){if(typeof e=="string"){if(e.length>i.maxStringLength)throw new u(n,`string exceeds ${i.maxStringLength} characters`);return e}if(typeof e=="number"){if(!Number.isFinite(e))throw new u(n,"numbers must be finite");return e}if(typeof e=="boolean")return e;throw new u(n,"expected a string, number, or boolean")}a(S,"parseScalarValue");function w(e,n,r){for(const t of Object.keys(e))if(!n.includes(t))throw new u(r,`unknown property '${t}' \u2014 allowed: ${n.join(", ")}`)}a(w,"rejectUnknownProperties");function M(e,n){const r=[];return{sql:f(e,n,r),params:r}}a(M,"compileMetadataFilter");function f(e,n,r){switch(e.operator){case"and":case"or":{const t=e.operator==="and"?" AND ":" OR ";return`(${e.operands.map(o=>f(o,n,r)).join(t)})`}case"not":return`NOT ${f(e.operand,n,r)}`;case"exists":return r.push(e.key),e.value?m(n,"mv.key = ?"):`NOT ${m(n,"mv.key = ?")}`;case"eq":case"gt":case"gte":case"lt":case"lte":{const t={eq:"=",gt:">",gte:">=",lt:"<",lte:"<="}[e.operator];return r.push(e.key,y(e.value)),m(n,`mv.key = ? AND mv.value_type = '${l(e.value)}' AND mv.${v(e.value)} ${t} ?`)}case"ne":{const t=l(e.value);r.push(e.key);const o=m(n,`mv.key = ? AND mv.value_type = '${t}'`);r.push(e.key,y(e.value));const s=m(n,`mv.key = ? AND mv.value_type = '${t}' AND mv.${v(e.value)} = ?`);return`(${o} AND NOT ${s})`}case"in":case"nin":{const t=l(e.value[0]),o=v(e.value[0]),s=e.value.map(()=>"?").join(", ");if(e.operator==="in")return r.push(e.key,...e.value.map(y)),m(n,`mv.key = ? AND mv.value_type = '${t}' AND mv.${o} IN (${s})`);r.push(e.key);const c=m(n,`mv.key = ? AND mv.value_type = '${t}'`);r.push(e.key,...e.value.map(y));const p=m(n,`mv.key = ? AND mv.value_type = '${t}' AND mv.${o} IN (${s})`);return`(${c} AND NOT ${p})`}case"all":{const t=l(e.value[0]),o=v(e.value[0]);return`(${e.value.map(c=>(r.push(e.key,y(c)),m(n,`mv.key = ? AND mv.value_type = '${t}' AND mv.${o} = ?`))).join(" AND ")})`}}}a(f,"compileFilterNode");function m(e,n){return`EXISTS (SELECT 1 FROM document_metadata_values mv WHERE mv.document_id = ${e}.id AND ${n})`}a(m,"buildValueExistsSql");function l(e){return typeof e}a(l,"valueTypeOf");function v(e){return typeof e=="string"?"text_value":typeof e=="number"?"number_value":"boolean_value"}a(v,"valueColumnOf");function y(e){return typeof e=="boolean"?e?1:0:e}a(y,"bindScalar");export{i as METADATA_FILTER_LIMITS,u as MetadataFilterError,M as compileMetadataFilter,R as parseMetadataFilter};

package/dist/metadata-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * QMD Metadata Store - Schema, persistence, and batch loading for document
+ * metadata.
+ *
+ * Metadata attaches to document identity (`documents.id`), not content
+ * identity: two paths can share one content hash while carrying different
+ * metadata. SQLite stays a derived index — metadata is rebuilt from source
+ * documents on `qmd update`, never mutated in place.
+ *
+ * `document_metadata` records extraction state per document (including
+ * successful-but-empty extraction), so filtered search can distinguish
+ * "extracted with no metadata" from "not yet extracted" and "extraction
+ * failed". `document_metadata_values` holds one indexed row per scalar value
+ * for filtering.
+ */
+import type { Database } from "./db.js";
+import { type DocumentMetadata, type MetadataExtractionResult } from "./metadata.js";
+export declare function initializeMetadataSchema(db: Database): void;
+/**
+ * Extract and persist metadata for one document, replacing any prior rows.
+ *
+ * With `onlyIfStale`, extraction is skipped when the document already has a
+ * current-version extraction row — the cheap path for unchanged documents
+ * during re-index. Returns the extraction result, or null when skipped.
+ */
+export declare function syncDocumentMetadata(db: Database, documentId: number, content: string, path: string, options?: {
+    onlyIfStale?: boolean;
+}): MetadataExtractionResult | null;
+/**
+ * Replace a document's metadata rows atomically. A failed extraction persists
+ * empty metadata plus the error, so stale metadata never survives a bad edit.
+ */
+export declare function replaceDocumentMetadata(db: Database, documentId: number, extraction: MetadataExtractionResult): void;
+/**
+ * Count active documents without a current, error-free metadata extraction.
+ * These documents are excluded from filtered search until `qmd update` runs.
+ */
+export declare function countDocumentsPendingMetadata(db: Database): number;
+/**
+ * Batch-load canonical metadata for a set of result filepaths
+ * (`qmd://collection/path`). One query — never per-result lookups.
+ */
+export declare function getMetadataByFilepath(db: Database, filepaths: readonly string[]): Map<string, DocumentMetadata>;
+/** Parse a stored `metadata_json` column value, tolerating absent rows. */
+export declare function parseMetadataJson(metadataJson: string | null | undefined): DocumentMetadata;

package/dist/metadata-store.js

@@ -0,0 +1,68 @@
+var m=Object.defineProperty;var n=(e,t)=>m(e,"name",{value:t,configurable:!0});import{extractDocumentMetadata as i,METADATA_EXTRACTION_VERSION as _}from"./metadata.js";function v(e){e.exec(`
+    CREATE TABLE IF NOT EXISTS document_metadata (
+      document_id INTEGER PRIMARY KEY,
+      metadata_json TEXT NOT NULL DEFAULT '{}',
+      extraction_version INTEGER NOT NULL,
+      extraction_error TEXT,
+      extracted_at TEXT NOT NULL,
+      FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
+    )
+  `),e.exec(`
+    CREATE TABLE IF NOT EXISTS document_metadata_values (
+      document_id INTEGER NOT NULL,
+      key TEXT NOT NULL,
+      ordinal INTEGER NOT NULL,
+      value_type TEXT NOT NULL,
+      text_value TEXT,
+      number_value REAL,
+      boolean_value INTEGER,
+      PRIMARY KEY (document_id, key, ordinal),
+      FOREIGN KEY (document_id)
+        REFERENCES document_metadata(document_id)
+        ON DELETE CASCADE,
+      CHECK (value_type IN ('string', 'number', 'boolean')),
+      CHECK (
+        (value_type = 'string' AND text_value IS NOT NULL AND number_value IS NULL AND boolean_value IS NULL)
+        OR (value_type = 'number' AND number_value IS NOT NULL AND text_value IS NULL AND boolean_value IS NULL)
+        OR (value_type = 'boolean' AND boolean_value IN (0, 1) AND text_value IS NULL AND number_value IS NULL)
+      )
+    )
+  `),e.exec(`
+    CREATE INDEX IF NOT EXISTS idx_metadata_text_lookup
+    ON document_metadata_values(key, text_value, document_id)
+    WHERE value_type = 'string'
+  `),e.exec(`
+    CREATE INDEX IF NOT EXISTS idx_metadata_number_lookup
+    ON document_metadata_values(key, number_value, document_id)
+    WHERE value_type = 'number'
+  `),e.exec(`
+    CREATE INDEX IF NOT EXISTS idx_metadata_boolean_lookup
+    ON document_metadata_values(key, boolean_value, document_id)
+    WHERE value_type = 'boolean'
+  `)}n(v,"initializeMetadataSchema");function O(e,t,a,d,u){if(u?.onlyIfStale&&N(e,t))return null;const o=i(a,d);return l(e,t,o),o}n(O,"syncDocumentMetadata");function l(e,t,a){e.transaction(()=>{e.prepare(`
+      INSERT INTO document_metadata (document_id, metadata_json, extraction_version, extraction_error, extracted_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(document_id) DO UPDATE SET
+        metadata_json = excluded.metadata_json,
+        extraction_version = excluded.extraction_version,
+        extraction_error = excluded.extraction_error,
+        extracted_at = excluded.extracted_at
+    `).run(t,JSON.stringify(a.metadata),a.extractionVersion,a.error??null,new Date().toISOString()),e.prepare("DELETE FROM document_metadata_values WHERE document_id = ?").run(t);const u=e.prepare(`
+      INSERT INTO document_metadata_values (document_id, key, ordinal, value_type, text_value, number_value, boolean_value)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);for(const[o,E]of Object.entries(a.metadata))(Array.isArray(E)?E:[E]).forEach((r,c)=>{u.run(t,o,c,typeof r,typeof r=="string"?r:null,typeof r=="number"?r:null,typeof r=="boolean"?r?1:0:null)})})()}n(l,"replaceDocumentMetadata");function N(e,t){return e.prepare("SELECT extraction_version FROM document_metadata WHERE document_id = ?").get(t)?.extraction_version===_}n(N,"isDocumentMetadataCurrent");function I(e){return e.prepare(`
+    SELECT COUNT(*) as c FROM documents d
+    WHERE d.active = 1
+      AND NOT EXISTS (
+        SELECT 1 FROM document_metadata dm
+        WHERE dm.document_id = d.id
+          AND dm.extraction_version = ?
+          AND dm.extraction_error IS NULL
+      )
+  `).get(_).c}n(I,"countDocumentsPendingMetadata");function S(e,t){const a=new Map;if(t.length===0)return a;const d=t.map(()=>"?").join(", "),u=e.prepare(`
+    SELECT 'qmd://' || d.collection || '/' || d.path AS filepath, dm.metadata_json
+    FROM documents d
+    JOIN document_metadata dm ON dm.document_id = d.id
+    WHERE d.active = 1
+      AND 'qmd://' || d.collection || '/' || d.path IN (${d})
+  `).all(...t);for(const o of u)a.set(o.filepath,T(o.metadata_json));return a}n(S,"getMetadataByFilepath");function T(e){if(!e)return{};try{return JSON.parse(e)}catch{return{}}}n(T,"parseMetadataJson");export{I as countDocumentsPendingMetadata,S as getMetadataByFilepath,v as initializeMetadataSchema,T as parseMetadataJson,l as replaceDocumentMetadata,O as syncDocumentMetadata};

package/dist/metadata.d.ts

@@ -0,0 +1,61 @@
+/**
+ * QMD Metadata - Public metadata types and frontmatter extraction.
+ *
+ * Documents opt into metadata through a namespaced Markdown frontmatter block:
+ *
+ *   ---
+ *   qmd:
+ *     metadata:
+ *       topics:
+ *         - typescript
+ *         - programming
+ *       status: published
+ *   ---
+ *
+ * Extraction is source-agnostic at the persistence boundary: this module
+ * produces a canonical `MetadataExtractionResult`, and future non-frontmatter
+ * sources can produce the same shape without touching storage or filtering.
+ *
+ * The raw document is never modified — frontmatter stays part of the stored,
+ * indexed, chunked, and embedded content.
+ */
+export type MetadataScalar = string | number | boolean;
+export type MetadataScalarArray = readonly string[] | readonly number[] | readonly boolean[];
+export type MetadataValue = MetadataScalar | MetadataScalarArray;
+export type DocumentMetadata = Record<string, MetadataValue>;
+/**
+ * Result of extracting metadata from one document.
+ *
+ * `error` is set when the document opted into `qmd.metadata` but the value was
+ * invalid — the document still indexes normally, but it is excluded from
+ * filtered search until the metadata is corrected and re-indexed.
+ */
+export interface MetadataExtractionResult {
+    metadata: DocumentMetadata;
+    error?: string;
+    extractionVersion: number;
+}
+/**
+ * Bump when extraction or normalization semantics change so existing rows are
+ * re-extracted on the next `qmd update`.
+ */
+export declare const METADATA_EXTRACTION_VERSION = 1;
+/** Defensive limits for metadata from untrusted repositories. */
+export declare const METADATA_LIMITS: {
+    readonly maxFrontmatterBytes: number;
+    readonly maxKeys: 64;
+    readonly maxKeyBytes: 128;
+    readonly maxStringLength: 1024;
+    readonly maxArrayLength: 128;
+    readonly maxYamlAliasCount: 100;
+    readonly maxErrorLength: 200;
+};
+/**
+ * Extract `qmd.metadata` from a document's leading YAML frontmatter.
+ *
+ * Never throws. A document without frontmatter, without a `qmd` namespace, or
+ * with a non-frontmatter extension yields empty metadata with no error.
+ * Invalid frontmatter or invalid metadata yields empty metadata plus a bounded
+ * extraction error.
+ */
+export declare function extractDocumentMetadata(content: string, path: string): MetadataExtractionResult;

package/dist/metadata.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var a=(t,r)=>h(t,"name",{value:r,configurable:!0});import l from"yaml";const y=1,o={maxFrontmatterBytes:64*1024,maxKeys:64,maxKeyBytes:128,maxStringLength:1024,maxArrayLength:128,maxYamlAliasCount:100,maxErrorLength:200},x=new Set([".md",".markdown",".mdx"]);function S(t,r){const n=a(s=>({metadata:s,extractionVersion:y}),"success"),e=a(s=>({metadata:{},error:L(s),extractionVersion:y}),"failure");if(!g(r))return n({});const m=p(t);if(m===null)return n({});if(Buffer.byteLength(m,"utf-8")>o.maxFrontmatterBytes)return e(`frontmatter exceeds ${o.maxFrontmatterBytes} bytes`);let i;try{i=l.parse(m,{maxAliasCount:o.maxYamlAliasCount})}catch(s){return e(`invalid frontmatter YAML: ${s instanceof Error?s.message:String(s)}`)}if(!u(i))return n({});const f=i.qmd;if(f===void 0)return n({});if(!u(f))return e("frontmatter 'qmd' must be a mapping");const c=f.metadata;if(c===void 0)return n({});if(!u(c))return e("frontmatter 'qmd.metadata' must be a mapping");try{return n(E(c))}catch(s){return e(s instanceof Error?s.message:String(s))}}a(S,"extractDocumentMetadata");function g(t){const r=t.lastIndexOf(".");return r<0?!1:x.has(t.slice(r).toLowerCase())}a(g,"hasFrontmatterFileExtension");function p(t){const r=t.charCodeAt(0)===65279?t.slice(1):t,n=r.match(/^---[ \t]*\r?\n/);if(!n)return null;const e=n[0].length,m=/^(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/m,i=r.slice(e).match(m);return!i||i.index===void 0?null:r.slice(e,e+i.index)}a(p,"getFrontmatterYaml");function E(t){const r=Object.keys(t);if(r.length>o.maxKeys)throw new Error(`metadata has ${r.length} keys (max ${o.maxKeys})`);const n=[];for(const e of r)A(e),n.push([e,b(e,t[e])]);return Object.fromEntries(n)}a(E,"normalizeMetadata");function A(t){if(t.length===0)throw new Error("metadata keys must be non-empty strings");if(Buffer.byteLength(t,"utf-8")>o.maxKeyBytes)throw new Error(`metadata key exceeds ${o.maxKeyBytes} bytes`);if(/[\u0000-\u001f\u007f]/.test(t))throw new Error("metadata keys must not contain control characters")}a(A,"validateMetadataKey");function b(t,r){return Array.isArray(r)?w(t,r):d(t,r)}a(b,"normalizeMetadataValue");function d(t,r){if(typeof r=="string"){if(r.length>o.maxStringLength)throw new Error(`metadata key "${t}": string exceeds ${o.maxStringLength} characters`);return r}if(typeof r=="number"){if(!Number.isFinite(r))throw new Error(`metadata key "${t}": numbers must be finite`);return r}if(typeof r=="boolean")return r;throw r===null?new Error(`metadata key "${t}": null is not supported \u2014 omit the key instead`):new Error(`metadata key "${t}": unsupported value type \u2014 use strings, numbers, booleans, or flat arrays of one of those`)}a(d,"normalizeMetadataScalar");function w(t,r){if(r.length===0)throw new Error(`metadata key "${t}": empty arrays are not supported \u2014 omit the key instead`);if(r.length>o.maxArrayLength)throw new Error(`metadata key "${t}": array exceeds ${o.maxArrayLength} values`);const n=r.map(e=>{if(Array.isArray(e))throw new Error(`metadata key "${t}": nested arrays are not supported`);return d(t,e)});if(n.every(e=>typeof e=="string"))return Array.from(new Set(n));if(n.every(e=>typeof e=="number"))return Array.from(new Set(n));if(n.every(e=>typeof e=="boolean"))return Array.from(new Set(n));throw new Error(`metadata key "${t}": mixed-type arrays are not supported`)}a(w,"normalizeMetadataArray");function u(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}a(u,"isPlainObject");function L(t){const r=t.replace(/\s+/g," ").trim();return r.length<=o.maxErrorLength?r:r.slice(0,o.maxErrorLength-3)+"..."}a(L,"truncateErrorMessage");export{y as METADATA_EXTRACTION_VERSION,o as METADATA_LIMITS,S as extractDocumentMetadata};

package/dist/paths.d.ts

@@ -0,0 +1 @@
+export declare function qmdHomedir(): string;

package/dist/paths.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var o=(r,e)=>m(r,"name",{value:e,configurable:!0});import{homedir as s}from"node:os";function p(){return process.env.HOME||process.env.USERPROFILE||s()||"/tmp"}o(p,"qmdHomedir");export{p as qmdHomedir};

package/dist/query-log.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Daemon query log — an opt-in JSONL record of searches served by the HTTP
+ * daemon: the REST `/query`·`/search` endpoints and the MCP `query` tool, so a
+ * user dogfooding a build can mine their real queries for misses. Only HTTP
+ * traffic is logged; a stdio MCP connection has no request to annotate.
+ *
+ * - Off unless `QMD_QUERY_LOG` is `1`, `true` or `yes` (case-insensitive).
+ *   CLI searches never call this module.
+ * - One file per local month: `$XDG_CACHE_HOME/qmd/queries-YYYY-MM.jsonl`
+ *   (default `~/.cache/qmd`), created 0600. Nothing is ever deleted.
+ * - Rows hold queries, result paths and scores — never snippets or bodies.
+ * - Fail-open: callers do not await and nothing here throws; a failure never
+ *   reaches the search response. The first failure per process prints one
+ *   stderr line; `queryLogStatus()` keeps the latest failure until the next
+ *   successful write.
+ * - Clients annotate rows with `X-QMD-Tag` / `X-QMD-Qid` / `X-QMD-Role`, and
+ *   skip logging with `X-QMD-No-Log: 1`. Header values are untrusted.
+ *
+ * Env and paths are read at call time so tests can redirect XDG_CACHE_HOME.
+ */
+import type { IncomingHttpHeaders } from "node:http";
+import type { IndexStatus } from "./store.js";
+export declare const QUERY_LOG_SCHEMA_VERSION = 1;
+type HeaderSource = Headers | IncomingHttpHeaders;
+type StatusSource = {
+    getStatus(): Promise<IndexStatus>;
+};
+/**
+ * One search hit. `vec_score` / `fts_score` are the raw backend scores the
+ * daemon attaches on `rerank:false` responses; absent when that backend did
+ * not return the hit (absent, never 0).
+ */
+export type QueryLogResult = {
+    file: string;
+    score: number;
+    vec_score?: number;
+    fts_score?: number;
+};
+/**
+ * Milliseconds each stage of one search took. A stage that did not run is
+ * absent, never 0: `refresh` is the pre-query re-index check, `expand` the LLM
+ * query expansion, `fts` the BM25 lookups, `embed` the query embeddings, `vec`
+ * the sqlite-vec lookups, `chunk` splitting candidates to pick each one's best
+ * chunk, `rerank` the LLM reranker, and `serialize` snippet extraction (plus
+ * writing the response on REST). RRF fusion and metadata lookups are not a
+ * stage, so the stages need not sum to `ms`.
+ */
+export type QueryLogTimeout = "expand" | "rerank";
+export type QueryLogStages = {
+    refresh?: number;
+    load?: number;
+    expand?: number;
+    fts?: number;
+    embed?: number;
+    vec?: number;
+    chunk?: number;
+    rerank?: number;
+    serialize?: number;
+};
+export type QueryLogEntry = {
+    via: "rest" | "mcp";
+    tool: string;
+    headers: HeaderSource;
+    searches: {
+        type: string;
+        query: string;
+    }[];
+    collections: string[] | null;
+    limit: number;
+    /** null = the request left reranking to the daemon default */
+    rerank: boolean | null;
+    results: QueryLogResult[];
+    ms: number;
+    stages?: QueryLogStages;
+    /** Stages that ran past their deadline; the search went on without them */
+    timeouts?: QueryLogTimeout[];
+    /** Injectable clock for tests; defaults to the time of the call. */
+    now?: Date;
+};
+export type QueryLogStatus = {
+    enabled: boolean;
+    path: string;
+    lastWrite: string | null;
+    lastError: string | null;
+};
+/** Path of the log file for the local month containing `date`. */
+export declare const queryLogPath: (date?: Date) => string;
+/** ISO-8601 in local time with the UTC offset, e.g. 2026-09-17T16:05:03.123+09:00. */
+export declare const isoWithOffset: (date: Date) => string;
+/**
+ * Queue one row. Returns immediately; the write happens after the response.
+ * No-op unless the flag is on and the request did not ask to be skipped.
+ * Never throws — the REST handler calls this after the response has ended.
+ */
+export declare const logQuery: (entry: QueryLogEntry, store: StatusSource) => void;
+/** Resolves once every queued row has been written or has failed. */
+export declare const flushQueryLog: () => Promise<void>;
+/** In-process view (the daemon's own `status` tool). */
+export declare const queryLogStatus: () => QueryLogStatus;
+export type QueryLogFileState = {
+    kind: "none";
+} | {
+    kind: "file";
+    path: string;
+    modified: Date;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Newest log file on disk, for `qmd status` — which runs in a different
+ * process than the daemon and so cannot see the daemon's env or state.
+ * A missing cache dir is "none"; any other failure yields kind "error" with
+ * the error code only (status output carries no filesystem paths).
+ */
+export declare const latestQueryLogFile: () => QueryLogFileState;
+/** Map a REST `/query` request the same way the handler does. */
+export declare const entryFromRest: (input: {
+    path: string;
+    headers: IncomingHttpHeaders;
+    /** The handler's already-mapped searches. */
+    searches: {
+        type: string;
+        query: string;
+    }[];
+    /** Raw JSON body fields the handler reads with typeof checks. */
+    params: {
+        limit?: unknown;
+        rerank?: unknown;
+    };
+    /** The collections actually searched (the handler's defaults applied). */
+    collections: string[];
+    results: QueryLogResult[];
+    ms: number;
+    stages?: QueryLogStages;
+    timeouts?: QueryLogTimeout[];
+}) => QueryLogEntry;
+/** Map an MCP `query` tool call. Only the HTTP transport supplies headers. */
+export declare const entryFromMcp: (input: {
+    headers: Headers;
+    /** The tool's typed sub-queries, or the plain `query` it auto-expanded. */
+    searches: {
+        type: string;
+        query: string;
+    }[];
+    /** The collections actually searched (the tool's defaults applied). */
+    collections: string[];
+    limit: number;
+    rerank: boolean;
+    results: QueryLogResult[];
+    ms: number;
+    stages?: QueryLogStages;
+    timeouts?: QueryLogTimeout[];
+}) => QueryLogEntry;
+export declare const _resetQueryLogForTesting: () => void;
+export {};

package/dist/query-log.js

@@ -0,0 +1,2 @@
+var x=Object.defineProperty;var o=(e,t)=>x(e,"name",{value:t,configurable:!0});import{appendFile as y,mkdir as E}from"node:fs/promises";import{readFileSync as F,readdirSync as L,statSync as M}from"node:fs";import{dirname as w,join as l}from"node:path";import{fileURLToPath as R}from"node:url";import{qmdHomedir as O}from"./paths.js";import{resolveCommit as C}from"./cli/version.js";const D=1,T=["primary","probe","canary","replay"],b=32,Q=64,A=6e4,k=o(e=>e!==void 0&&["1","true","yes"].includes(e.trim().toLowerCase()),"isTruthyFlag"),S=o(()=>k(process.env.QMD_QUERY_LOG),"isQueryLogEnabled"),_=o(()=>l(process.env.XDG_CACHE_HOME||l(O(),".cache"),"qmd"),"queryLogDir"),a=o(e=>String(e).padStart(2,"0"),"pad2"),h=o((e=new Date)=>l(_(),`queries-${e.getFullYear()}-${a(e.getMonth()+1)}.jsonl`),"queryLogPath"),H=o(e=>{const t=-e.getTimezoneOffset(),s=t>=0?"+":"-",n=Math.abs(t),i=String(e.getMilliseconds()).padStart(3,"0");return`${e.getFullYear()}-${a(e.getMonth()+1)}-${a(e.getDate())}T${a(e.getHours())}:${a(e.getMinutes())}:${a(e.getSeconds())}.${i}${s}${a(Math.floor(n/60))}:${a(n%60)}`},"isoWithOffset"),u=o((e,t)=>{if(e instanceof Headers)return e.get(t);const s=e[t.toLowerCase()];return(Array.isArray(s)?s[0]:s)??null},"readHeader"),v=o((e,t)=>e===null||e===""?null:e.slice(0,t),"clip"),N=o(e=>T.find(t=>t===e)??null,"parseRole"),I=o(e=>(e.startsWith("qmd://")?e.slice(6):e).split("/").map(s=>{try{return decodeURIComponent(s)}catch{return s}}).join("/"),"normalizeResultFile");let m;const j=o(()=>{if(m!==void 0)return m;const e=w(R(import.meta.url)),t=l(e,"..");try{const s=JSON.parse(F(l(t,"package.json"),"utf-8")),n=C(l(e,"cli"),t);m=n?`${s.version??"unknown"} (${n})`:s.version??"unknown"}catch{m="unknown"}return m},"qmdVersion");let c=null;const G=o(async e=>{const t=Date.now();if(c&&c.store===e&&t-c.at<A)return c.value;let s;try{const n=await e.getStatus(),i=n.collections.map(r=>r.lastUpdated).filter(Boolean).sort().at(-1)??null;s={docs:n.totalDocuments,updated:i}}catch{s={docs:null,updated:null}}return c={store:e,at:t,value:s},s},"indexFingerprint");let d=Promise.resolve(),p=null,g=null,q=!1;const $=o((e,t)=>{g=t,!q&&(q=!0,console.error(`qmd: query log write failed (${e}): ${t} \u2014 searches are unaffected`))},"recordFailure"),K=o((e,t)=>{try{P(e,t)}catch(s){$(h(),s instanceof Error?s.message:String(s))}},"logQuery"),P=o((e,t)=>{if(!S()||k(u(e.headers,"x-qmd-no-log")??void 0))return;const s=e.now??new Date,n=h(s),i={v:D,ts:H(s),qmd:j(),via:e.via,tool:e.tool,searches:e.searches.map(({type:r,query:f})=>({type:r,query:f})),collections:e.collections,limit:e.limit,rerank:e.timeouts?.includes("rerank")?"timeout":e.rerank,results:e.results.map((r,f)=>({file:I(r.file),score:r.score,...r.vec_score!==void 0&&{vec_score:r.vec_score},...r.fts_score!==void 0&&{fts_score:r.fts_score},rank:f+1})),ms:e.ms,...e.stages&&{stages:e.stages},...e.timeouts&&e.timeouts.length>0&&{timeouts:e.timeouts},client:{tag:v(u(e.headers,"x-qmd-tag"),b),qid:v(u(e.headers,"x-qmd-qid"),Q),role:N(u(e.headers,"x-qmd-role"))}};d=d.then(async()=>{try{const r=JSON.stringify({...i,index:await G(t)})+`
+`;await E(w(n),{recursive:!0}),await y(n,r,{mode:384}),p=new Date().toISOString(),g=null}catch(r){$(n,r instanceof Error?r.message:String(r))}})},"queueRow"),Z=o(()=>d,"flushQueryLog"),ee=o(()=>({enabled:S(),path:h(),lastWrite:p,lastError:g}),"queryLogStatus"),U=o(e=>e.code??e.message,"errorCode"),te=o(()=>{const e=_();try{const t=L(e).filter(n=>/^queries-\d{4}-\d{2}\.jsonl$/.test(n)).sort().at(-1);if(!t)return{kind:"none"};const s=l(e,t);return{kind:"file",path:s,modified:M(s).mtime}}catch(t){const s=U(t);return s==="ENOENT"?{kind:"none"}:{kind:"error",message:s}}},"latestQueryLogFile"),se=o(e=>({via:"rest",tool:e.path,headers:e.headers,searches:e.searches,collections:e.collections.length>0?e.collections:null,limit:typeof e.params.limit=="number"?e.params.limit:10,rerank:typeof e.params.rerank=="boolean"?e.params.rerank:null,results:e.results,ms:e.ms,stages:e.stages,timeouts:e.timeouts}),"entryFromRest"),oe=o(e=>({via:"mcp",tool:"query",headers:e.headers,searches:e.searches,collections:e.collections.length>0?e.collections:null,limit:e.limit,rerank:e.rerank,results:e.results,ms:e.ms,stages:e.stages,timeouts:e.timeouts}),"entryFromMcp"),re=o(()=>{d=Promise.resolve(),p=null,g=null,q=!1,c=null},"_resetQueryLogForTesting");export{D as QUERY_LOG_SCHEMA_VERSION,re as _resetQueryLogForTesting,oe as entryFromMcp,se as entryFromRest,Z as flushQueryLog,H as isoWithOffset,te as latestQueryLogFile,K as logQuery,h as queryLogPath,ee as queryLogStatus};

package/dist/refresh.d.ts

@@ -0,0 +1,60 @@
+/**
+ * refresh.ts - keep the text index current for the daemon, without `qmd update`.
+ *
+ * A note written a minute ago should be findable now. The index only moves when someone runs
+ * `qmd update`, and nobody does between writing and asking, so the daemon checks the
+ * collections a query is about to search and re-indexes the ones that changed on disk.
+ *
+ * Three things it deliberately does not do:
+ * - Run a collection's `update:` command. That is a shell hook (`git pull` in the documented
+ *   example), gated on `qmd trust` for project-local configs; firing it because a query
+ *   arrived would run commands nobody asked for.
+ * - Clear the LLM cache. `store.update()` does, and a refresh after every edit would then send
+ *   every following query through expansion and rerank cold.
+ * - Embed. Embedding 232 documents takes minutes on a laptop GPU; a new note is findable by
+ *   BM25 immediately and by vector search after the next `qmd embed`.
+ */
+import type { QMDStore } from "./index.js";
+export type RefreshCollection = {
+    readonly name: string;
+    readonly path: string;
+    readonly pattern: string;
+    readonly ignore?: string[];
+};
+export type CollectionSnapshot = {
+    readonly fileCount: number;
+    readonly newestMtimeMs: number;
+};
+export type IndexRefresherDeps = {
+    /** Collections with the time the index last recorded a change in each, or null if never. */
+    readonly listCollections: () => ReadonlyArray<RefreshCollection & {
+        readonly lastIndexedMs: number | null;
+    }>;
+    readonly snapshot: (collection: RefreshCollection) => Promise<CollectionSnapshot>;
+    readonly reindex: (collection: RefreshCollection) => Promise<void>;
+    readonly now?: () => number;
+    readonly cooldownMs?: number;
+    readonly onError?: (collection: string, error: unknown) => void;
+};
+export type IndexRefresher = {
+    /** Re-index each named collection that changed on disk. Never rejects. */
+    readonly refreshIfStale: (collections: readonly string[]) => Promise<void>;
+    /** Re-check now, ignoring the cooldown — for a caller that just wrote into the collection. */
+    readonly refreshNow: (collections: readonly string[]) => Promise<void>;
+};
+/** How long a collection's last check stays good. Bounds the directory walk, not the re-index. */
+export declare const REFRESH_COOLDOWN_MS = 30000;
+export declare const createIndexRefresher: (deps: IndexRefresherDeps) => IndexRefresher;
+/**
+ * A refresher wired to a store's own collections.
+ *
+ * `configPath`, when given, is the config the daemon was started from. A project-local config
+ * arrives with `git clone`, so its collection paths outside the project are somebody else's
+ * choice until the user runs `qmd trust`; `qmd update` skips them for an untrusted config, and
+ * a refresh — which never asks — skips them always.
+ */
+export declare const createStoreIndexRefresher: (store: QMDStore, options?: {
+    configPath?: string;
+    cooldownMs?: number;
+    onError?: (collection: string, error: unknown) => void;
+}) => IndexRefresher;

package/dist/refresh.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var o=(t,i)=>g(t,"name",{value:i,configurable:!0});import{statSync as M}from"node:fs";import{resolve as x}from"node:path";import{getStoreCollections as A,listCollectionFiles as S,listCollections as y,reindexCollection as P}from"./store.js";import{isCollectionPathInsideProject as I,isLocalConfigPath as E}from"./trust.js";const O=3e4,k=o(t=>{const i=t.now??Date.now,d=t.cooldownMs??O,f=new Map,h=new Map,s=new Set,a=o(async e=>{const n=i(),r=f.get(e.name);if(!s.delete(e.name)&&r&&n-r.checkedAt<d)return;const m=await t.snapshot(e);if(m.fileCount===0&&(r?.fileCount??0)>0){f.set(e.name,{...r,checkedAt:n});return}const w=Math.max(e.lastIndexedMs??0,r?.refreshedAt??0),p=m.newestMtimeMs>w,C=r!==void 0&&m.fileCount!==r.fileCount;if(!p&&!C){f.set(e.name,{checkedAt:n,refreshedAt:r?.refreshedAt??0,fileCount:m.fileCount});return}await t.reindex(e),f.set(e.name,{checkedAt:n,refreshedAt:n,fileCount:m.fileCount})},"refreshOne"),l=o(e=>{const n=h.get(e.name);if(n)return n;const r=a(e).catch(c=>{t.onError?.(e.name,c)}).finally(()=>{h.delete(e.name)});return h.set(e.name,r),r},"refreshShared"),u=o(async e=>{let n;try{const r=new Set(e);n=t.listCollections().filter(c=>r.has(c.name))}catch(r){for(const c of e)t.onError?.(c,r);return}await Promise.all(n.map(l))},"refreshIfStale");return{refreshIfStale:u,refreshNow:o(async e=>{for(const n of e)s.add(n);await Promise.all(e.map(n=>h.get(n))),await u(e)},"refreshNow")}},"createIndexRefresher"),v=o(async t=>{const i=await S(t.path,t.pattern,t.ignore);let d=0;for(const f of i)try{d=Math.max(d,M(x(t.path,f)).mtimeMs)}catch{}return{fileCount:i.length,newestMtimeMs:d}},"snapshotCollection"),j=o((t,i={})=>{const d=t.internal.db,f=i.configPath,h=o(s=>f!==void 0&&E(f)&&!I(f,s),"isOutsideLocalProject");return k({listCollections:o(()=>{const s=new Map(y(d).map(a=>[a.name,a.last_modified]));return A(d).filter(a=>!h(a.path)).map(a=>{const l=s.get(a.name);return{name:a.name,path:a.path,pattern:a.pattern||"**/*.md",ignore:a.ignore,lastIndexedMs:l?Date.parse(l):null}})},"listCollections"),snapshot:v,reindex:o(async s=>{await P(t.internal,s.path,s.pattern,s.name,{ignorePatterns:s.ignore})},"reindex"),cooldownMs:i.cooldownMs,onError:i.onError})},"createStoreIndexRefresher");export{O as REFRESH_COOLDOWN_MS,k as createIndexRefresher,j as createStoreIndexRefresher};

package/dist/rerank-input.d.ts

@@ -0,0 +1,46 @@
+/**
+ * rerank-input.ts - what the cross-encoder reranker is shown.
+ *
+ * Both search paths (`hybridQuery`, `structuredSearch`) and `rerank()` build the reranker's
+ * input here and nowhere else: the query string, which chunk of a candidate document is sent,
+ * and the document text made from that chunk. The query string is also the rerank cache key,
+ * so a change here re-scores every cached pair.
+ */
+/** A chunk as the search paths cut it: text plus its character offset in the body. */
+export type RerankChunk = {
+    text: string;
+    pos: number;
+};
+/** Candidate metadata a document text may draw on besides the chunk. */
+export type RerankDocMeta = {
+    file: string;
+    title: string;
+    displayPath: string;
+};
+/** Weight of an intent term in chunk selection; a non-Hangul query word counts 2, a Hangul bigram 1 */
+export declare const INTENT_WEIGHT_CHUNK = 1;
+/** The reranker's query: intent, a blank line, then the query; the query alone without intent. */
+export declare const formatRerankQuery: (query: string, intent?: string) => string;
+/**
+ * Head start of the first chunk (title, summary); a later chunk must out-score it by more than this,
+ * which a typical short query cannot do, so its first chunk is always sent.
+ */
+export declare const FIRST_CHUNK_HEAD_START = 16;
+/** The head start when intent is given: halved, so intent words can still steer selection to a later chunk. */
+export declare const FIRST_CHUNK_HEAD_START_WITH_INTENT = 8;
+/**
+ * Scorer for one chunk's text against `query`: two points per query word longer than two characters
+ * with no Hangul, one per query Hangul syllable bigram, and one per intent word (half a non-Hangul
+ * query word). Case-insensitive substring match.
+ */
+export declare const rerankChunkScorer: (query: string, intentTerms: string[]) => ((text: string) => number);
+/**
+ * Index of the chunk to rerank: the highest `rerankChunkScorer` score, with the first chunk starting
+ * FIRST_CHUNK_HEAD_START ahead (FIRST_CHUNK_HEAD_START_WITH_INTENT with intent), so the note's lead is
+ * sent unless a later chunk matches far more of the query. A tie keeps the earlier chunk.
+ */
+export declare const selectRerankChunk: (chunks: RerankChunk[], query: string, intentTerms: string[]) => number;
+/** Frontmatter longer than this drowns the first chunk in source URLs; short blocks stay put. */
+export declare const LONG_FRONTMATTER_CHARS = 350;
+/** The document text sent for one candidate: the selected chunk alone, without long frontmatter. */
+export declare const formatRerankDoc: (chunkText: string, _meta: RerankDocMeta) => string;

package/dist/rerank-input.js

@@ -0,0 +1,5 @@
+var g=Object.defineProperty;var s=(e,t)=>g(e,"name",{value:t,configurable:!0});const C=1,I=s((e,t)=>t?`${t}
+
+${e}`:e,"formatRerankQuery"),i=s(e=>(e.match(/[가-힣]{3,}/g)??[]).flatMap(t=>Array.from({length:t.length-1},(c,l)=>t.slice(l,l+2))),"hangulBigrams"),T=16,_=8,u=s((e,t)=>{const c=e.toLowerCase(),l=c.split(/\s+/).filter(o=>o.length>2&&!/[가-힣]/.test(o)),p=i(c);return o=>{const a=o.toLowerCase();return l.reduce((r,n)=>r+(a.includes(n)?2:0),0)+p.reduce((r,n)=>r+(a.includes(n)?1:0),0)+t.reduce((r,n)=>r+(a.includes(n)?1:0),0)}},"rerankChunkScorer"),d=s((e,t,c)=>{const l=u(t,c),p=c.length===0?T:_;let o=0,a=-1;for(let r=0;r<e.length;r++){const n=l(e[r].text)+(r===0?p:0);n>a&&(a=n,o=r)}return o},"selectRerankChunk"),h=350,m=s(e=>{if(!/^---\r?\n/.test(e))return e;const t=e.match(/^---\r?\n[\s\S]{1,100000}?---\r?\n/);return t&&t[0].length>h?e.slice(t[0].length):e},"stripLongFrontmatter"),S=s(e=>e.replace(/!?\[([^\]]*)\]\((?:[^()]|\([^()]*\))*\)/g,"$1").replace(/https?:\/\/\S+/g,t=>t.match(/[.,;:!?)\]}>]+$/)?.[0]??""),"stripUrls"),N=s(e=>e.split(`
+`).map(t=>t.replace(/^\s*(>\s*)+/,"")).join(`
+`),"stripQuotes"),H=s(e=>e.replace(/<!--[\s\S]*?-->/g,"").replace(/<script\b[^<>]*>[\s\S]*?<\/script\s*>/gi,"").replace(/<style\b[^<>]*>[\s\S]*?<\/style\s*>/gi,"").replace(/<\/?[a-zA-Z][^<>]*>/g,""),"stripHtmlTags"),f=s((e,t)=>H(N(S(m(e)))),"formatRerankDoc");export{T as FIRST_CHUNK_HEAD_START,_ as FIRST_CHUNK_HEAD_START_WITH_INTENT,C as INTENT_WEIGHT_CHUNK,h as LONG_FRONTMATTER_CHARS,f as formatRerankDoc,I as formatRerankQuery,u as rerankChunkScorer,d as selectRerankChunk};