@monoes/monomindcli 2.14.0 → 2.14.1

package/dist/src/knowledge/library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../../../src/knowledge/library.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,GAAG,MAAM,GAAG,SAAS,CAQrB;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,GAAG,MAAM,CAET;AAUD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAa,GAAG,MAAM,GAAG,IAAI,CAOpF;AAkBD,iDAAiD;AACjD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,MAAM,GAAE,aAAkB,EAC1B,GAAG,SAAa,GACf,OAAO,CAqCT;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,YAAY,EAAE,EACpB,MAAM,GAAE,aAAkB,EAC1B,GAAG,SAAa,GACf,YAAY,EAAE,CAEhB;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAAE,EACpB,IAAI,GAAE,WAAwB,EAC9B,KAAK,GAAE,KAAK,GAAG,MAAe,GAC7B,YAAY,EAAE,CAsBhB;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAmB7D;AAED,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,kBAAuB,GAAG,YAAY,EAAE,CAM/F;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG;IACnD,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,IAAI,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD,CAiBA"}

package/dist/src/knowledge/library.js

@@ -0,0 +1,195 @@
+/**
+ * The capture library (RCL-09) — browsing what has been captured, rather than
+ * searching it.
+ *
+ * `listDocuments` answers "what is indexed". A library answers a different
+ * question: everything from this site, captured last week, tagged `reading`,
+ * newest first. The facets come from the capture envelope's `meta.json`
+ * (RCL-07), which is already on every record — this module is the query layer
+ * over them, and the data layer the desktop GUI renders.
+ *
+ * Rules, once, here:
+ *  - within a facet values are OR'd, across facets AND'd (`--site a --site b
+ *    --tag x` = "from a or b, tagged x");
+ *  - `--site example.com` matches `www.example.com` and `docs.example.com`,
+ *    because nobody browsing their own library means the bare host only;
+ *  - a document with no provenance (an ordinary file on disk) sorts by its
+ *    index time and matches no capture facet — it is not a capture.
+ *
+ * @module v1/cli/knowledge/library
+ */
+import * as path from 'node:path';
+// ── Facet extraction ───────────────────────────────────────────────
+/** The host a document was captured from, or undefined for a local file. */
+export function documentSite(meta) {
+    const url = meta.canonicalUrl ?? meta.provenance?.canonicalUrl ?? meta.provenance?.url;
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** When the page was captured; falls back to when it was indexed. */
+export function documentCapturedAt(meta) {
+    return meta.provenance?.capturedAt ?? meta.indexedAt ?? '';
+}
+const RELATIVE_RE = /^(\d+(?:\.\d+)?)\s*(m|h|d|w)$/i;
+const UNIT_MS = {
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/**
+ * A point in time from `2026-09-01`, a full ISO stamp, or an AGE like `7d`
+ * (meaning "7 days ago"). Returns null for anything unparseable so a typo
+ * cannot silently filter the whole library away.
+ */
+export function parseWhen(value, now = Date.now()) {
+    const raw = (value ?? '').trim();
+    if (!raw)
+        return null;
+    const rel = RELATIVE_RE.exec(raw);
+    if (rel)
+        return now - Number(rel[1]) * UNIT_MS[rel[2].toLowerCase()];
+    const parsed = Date.parse(raw.length === 10 ? `${raw}T00:00:00.000Z` : raw);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function siteMatches(host, wanted) {
+    if (!host)
+        return false;
+    return wanted.some((w) => {
+        const want = w
+            .trim()
+            .toLowerCase()
+            .replace(/^www\./, '');
+        return !!want && (host === want || host.endsWith(`.${want}`));
+    });
+}
+function anyOf(values, wanted) {
+    const have = (values ?? []).map((v) => v.toLowerCase());
+    return wanted.some((w) => have.includes(w.trim().toLowerCase()));
+}
+/** True when a document belongs in this view. */
+export function matchesLibraryFilter(meta, filter = {}, now = Date.now()) {
+    if (filter.scope && meta.scope !== filter.scope)
+        return false;
+    const prov = meta.provenance;
+    const isCapture = !!prov || !!meta.canonicalUrl;
+    if (filter.capturedOnly && !isCapture)
+        return false;
+    if (filter.site?.length && !siteMatches(documentSite(meta), filter.site))
+        return false;
+    if (filter.tag?.length && !anyOf(prov?.tags, filter.tag))
+        return false;
+    if (filter.collection?.length &&
+        !anyOf(prov?.collection ? [prov.collection] : [], filter.collection))
+        return false;
+    if (filter.source?.length && !anyOf(prov?.source ? [prov.source] : [], filter.source))
+        return false;
+    if (filter.since || filter.until) {
+        const at = Date.parse(documentCapturedAt(meta));
+        const since = parseWhen(filter.since, now);
+        const until = parseWhen(filter.until, now);
+        if (Number.isNaN(at))
+            return false;
+        if (since !== null && at < since)
+            return false;
+        if (until !== null && at > until)
+            return false;
+    }
+    if (filter.text) {
+        const needle = filter.text.toLowerCase();
+        const hay = [
+            prov?.title ?? '',
+            meta.canonicalUrl ?? prov?.url ?? '',
+            meta.filePath,
+            prov?.note ?? '',
+        ]
+            .join(' ')
+            .toLowerCase();
+        if (!hay.includes(needle))
+            return false;
+    }
+    return true;
+}
+export function filterDocuments(docs, filter = {}, now = Date.now()) {
+    return docs.filter((d) => matchesLibraryFilter(d, filter, now));
+}
+export function sortDocuments(docs, sort = 'captured', order = 'desc') {
+    const dir = order === 'asc' ? 1 : -1;
+    const key = (d) => {
+        switch (sort) {
+            case 'indexed':
+                return d.indexedAt ?? '';
+            case 'title':
+                return (d.provenance?.title ?? path.basename(d.filePath)).toLowerCase();
+            case 'path':
+                return d.filePath;
+            case 'size':
+                return d.size ?? 0;
+            default:
+                return documentCapturedAt(d);
+        }
+    };
+    return [...docs].sort((a, b) => {
+        const ka = key(a);
+        const kb = key(b);
+        if (ka === kb)
+            return a.filePath.localeCompare(b.filePath);
+        return ka < kb ? -dir : dir;
+    });
+}
+/** The flat, JSON-friendly row the GUI and `--json` consumers read. */
+export function libraryEntry(meta) {
+    const prov = meta.provenance;
+    const url = meta.canonicalUrl ?? prov?.canonicalUrl ?? prov?.url;
+    return {
+        filePath: meta.filePath,
+        scope: meta.scope,
+        title: prov?.title ?? path.basename(meta.filePath),
+        ...(url ? { url } : {}),
+        ...(documentSite(meta) ? { site: documentSite(meta) } : {}),
+        capturedAt: documentCapturedAt(meta),
+        indexedAt: meta.indexedAt,
+        ...(prov?.source ? { source: prov.source } : {}),
+        ...(prov?.collection ? { collection: prov.collection } : {}),
+        tags: prov?.tags ?? [],
+        chunkCount: meta.chunkCount,
+        size: meta.size,
+        ...(meta.version ? { version: meta.version } : {}),
+        captured: !!prov || !!meta.canonicalUrl,
+    };
+}
+/** Browse the library: filter, sort, cap. Never throws on an empty store. */
+export function listLibrary(docs, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const filtered = filterDocuments(docs, opts, now);
+    const sorted = sortDocuments(filtered, opts.sort ?? 'captured', opts.order ?? 'desc');
+    const capped = opts.limit && opts.limit > 0 ? sorted.slice(0, opts.limit) : sorted;
+    return capped.map(libraryEntry);
+}
+/** Facet counts for the current view — what a sidebar renders. */
+export function libraryFacets(docs) {
+    const tally = (values) => {
+        const counts = new Map();
+        for (const v of values) {
+            if (!v)
+                continue;
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+        }
+        return [...counts.entries()]
+            .map(([value, count]) => ({ value, count }))
+            .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+    };
+    return {
+        sites: tally(docs.map(documentSite)),
+        tags: tally(docs.flatMap((d) => d.provenance?.tags ?? [])),
+        collections: tally(docs.map((d) => d.provenance?.collection)),
+        sources: tally(docs.map((d) => d.provenance?.source)),
+    };
+}
+//# sourceMappingURL=library.js.map

package/dist/src/knowledge/library.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.js","sourceRoot":"","sources":["../../../src/knowledge/library.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge/mhtml.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MHTML / MHT container parsing (RCL-01).
+ *
+ * An MHTML archive is an RFC 2557 `multipart/related` MIME message: the page
+ * plus every subresource it referenced, each part carrying its own transfer
+ * encoding and charset. Chrome's `Page.captureSnapshot` writes them
+ * quoted-printable; Internet Explorer and most "save as web archive" tools
+ * write base64.
+ *
+ * Only the ROOT frame is prose. Picking the first `text/html` part instead is
+ * how an ad iframe ends up indexed as the article, so the root is resolved
+ * from the container's `Snapshot-Content-Location` / `Content-Location` when
+ * one is present.
+ *
+ * Read the file as `latin1` (or pass a Buffer): byte fidelity matters before
+ * transfer decoding, and the real charset is only known per part.
+ *
+ * @module v1/cli/knowledge/mhtml
+ */
+export interface MhtmlPart {
+    /** Lowercased MIME type without parameters, e.g. `text/html`. */
+    contentType: string;
+    /** Charset from the part's Content-Type, lowercased, or null. */
+    charset: string | null;
+    /** Content-Location, or null. */
+    location: string | null;
+    /** Lowercased Content-Transfer-Encoding; `binary` when unstated. */
+    encoding: string;
+    /** Raw bytes after transfer decoding. */
+    body: Buffer;
+    headers: Record<string, string>;
+}
+export interface ParsedMhtml {
+    /** The part holding the page itself, or null when there is no HTML part. */
+    root: MhtmlPart | null;
+    parts: MhtmlPart[];
+    /** Container `Snapshot-Content-Location`/`Content-Location` header. */
+    snapshotLocation: string | null;
+    /** Container `Subject` header — Chrome writes the page title here. */
+    subject: string | null;
+}
+/** Decode a quoted-printable body to bytes: soft line breaks vanish, `=XX`
+ *  becomes one byte, everything else is its own latin1 byte. */
+export declare function decodeQuotedPrintable(input: string): Buffer;
+/** Decode bytes under a MIME charset, falling back to UTF-8 (then latin1)
+ *  rather than failing an ingest over an exotic label. */
+export declare function decodeCharset(bytes: Buffer, charset: string | null): string;
+/**
+ * Parse an MHTML container. Anything that is not a well-formed multipart
+ * message is treated as a single part, so a plain `.html` file renamed to
+ * `.mhtml` still ingests.
+ */
+export declare function parseMhtml(raw: string | Buffer): ParsedMhtml;
+/** Parse a container and return its root frame decoded to a string. */
+export declare function mhtmlToHtml(raw: string | Buffer): {
+    html: string;
+    location: string | null;
+    subject: string | null;
+};
+//# sourceMappingURL=mhtml.d.ts.map

package/dist/src/knowledge/mhtml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mhtml.d.ts","sourceRoot":"","sources":["../../../src/knowledge/mhtml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;gEACgE;AAChE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyB3D;AAaD;0DAC0D;AAC1D,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAU3E;AA4CD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAiC5D;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAOA"}

package/dist/src/knowledge/mhtml.js

@@ -0,0 +1,154 @@
+/**
+ * MHTML / MHT container parsing (RCL-01).
+ *
+ * An MHTML archive is an RFC 2557 `multipart/related` MIME message: the page
+ * plus every subresource it referenced, each part carrying its own transfer
+ * encoding and charset. Chrome's `Page.captureSnapshot` writes them
+ * quoted-printable; Internet Explorer and most "save as web archive" tools
+ * write base64.
+ *
+ * Only the ROOT frame is prose. Picking the first `text/html` part instead is
+ * how an ad iframe ends up indexed as the article, so the root is resolved
+ * from the container's `Snapshot-Content-Location` / `Content-Location` when
+ * one is present.
+ *
+ * Read the file as `latin1` (or pass a Buffer): byte fidelity matters before
+ * transfer decoding, and the real charset is only known per part.
+ *
+ * @module v1/cli/knowledge/mhtml
+ */
+/** Decode a quoted-printable body to bytes: soft line breaks vanish, `=XX`
+ *  becomes one byte, everything else is its own latin1 byte. */
+export function decodeQuotedPrintable(input) {
+    const out = [];
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch !== '=') {
+            out.push(input.charCodeAt(i) & 0xff);
+            continue;
+        }
+        if (input[i + 1] === '\r' && input[i + 2] === '\n') {
+            i += 2; // soft line break
+            continue;
+        }
+        if (input[i + 1] === '\n') {
+            i += 1; // soft line break, LF-only file
+            continue;
+        }
+        const hex = input.slice(i + 1, i + 3);
+        if (/^[0-9a-fA-F]{2}$/.test(hex)) {
+            out.push(Number.parseInt(hex, 16));
+            i += 2;
+            continue;
+        }
+        out.push(0x3d); // a lone `=` — keep it
+    }
+    return Buffer.from(out);
+}
+function decodeBody(raw, encoding) {
+    switch (encoding) {
+        case 'quoted-printable':
+            return decodeQuotedPrintable(raw);
+        case 'base64':
+            return Buffer.from(raw.replace(/\s+/g, ''), 'base64');
+        default:
+            return Buffer.from(raw, 'latin1');
+    }
+}
+/** Decode bytes under a MIME charset, falling back to UTF-8 (then latin1)
+ *  rather than failing an ingest over an exotic label. */
+export function decodeCharset(bytes, charset) {
+    const label = (charset ?? 'utf-8').trim().toLowerCase();
+    for (const candidate of [label, 'utf-8']) {
+        try {
+            return new TextDecoder(candidate, { fatal: false }).decode(bytes);
+        }
+        catch {
+            /* unknown label — try the next */
+        }
+    }
+    return bytes.toString('latin1');
+}
+/** Split a MIME chunk into unfolded headers and the body after the first
+ *  blank line. Continuation lines (leading space/tab) join their header. */
+function splitHeaders(chunk) {
+    const sep = /\r?\n\r?\n/.exec(chunk);
+    const headerText = sep ? chunk.slice(0, sep.index) : chunk;
+    const body = sep ? chunk.slice(sep.index + sep[0].length) : '';
+    const headers = {};
+    let current = '';
+    for (const rawLine of headerText.split(/\r?\n/)) {
+        if (/^[ \t]/.test(rawLine) && current) {
+            headers[current] += ` ${rawLine.trim()}`;
+            continue;
+        }
+        const colon = rawLine.indexOf(':');
+        if (colon === -1)
+            continue;
+        current = rawLine.slice(0, colon).trim().toLowerCase();
+        headers[current] = rawLine.slice(colon + 1).trim();
+    }
+    return { headers, body };
+}
+function param(headerValue, name) {
+    if (!headerValue)
+        return null;
+    const m = new RegExp(`${name}\\s*=\\s*("[^"]*"|'[^']*'|[^;\\s]+)`, 'i').exec(headerValue);
+    return m ? m[1].replace(/^["']|["']$/g, '') : null;
+}
+function toPart(chunk) {
+    const { headers, body } = splitHeaders(chunk);
+    const contentType = (headers['content-type'] ?? 'text/html').split(';')[0].trim().toLowerCase();
+    const encoding = (headers['content-transfer-encoding'] ?? 'binary').trim().toLowerCase();
+    return {
+        contentType,
+        charset: param(headers['content-type'], 'charset')?.toLowerCase() ?? null,
+        location: headers['content-location'] ?? null,
+        encoding,
+        body: decodeBody(body, encoding),
+        headers,
+    };
+}
+/**
+ * Parse an MHTML container. Anything that is not a well-formed multipart
+ * message is treated as a single part, so a plain `.html` file renamed to
+ * `.mhtml` still ingests.
+ */
+export function parseMhtml(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('latin1');
+    const { headers, body } = splitHeaders(text);
+    const snapshotLocation = headers['snapshot-content-location'] ?? headers['content-location'] ?? null;
+    const subject = headers.subject ?? null;
+    const boundary = param(headers['content-type'], 'boundary');
+    let parts;
+    if (!boundary) {
+        // No boundary: either a single-part message or a bare HTML file. Feeding
+        // the whole document through `toPart` covers both — an HTML file has no
+        // header block, so everything lands in the body.
+        parts = [toPart(/^[a-z-]+:/i.test(text) ? text : `Content-Type: text/html\r\n\r\n${text}`)];
+    }
+    else {
+        const delimiter = `--${boundary}`;
+        parts = body
+            .split(delimiter)
+            .slice(1) // text before the first delimiter is the MIME preamble
+            .filter((chunk) => !chunk.startsWith('--')) // the closing `--boundary--`
+            .map((chunk) => chunk.replace(/^\r?\n/, ''))
+            .map(toPart);
+    }
+    const html = parts.filter((p) => p.contentType === 'text/html' || p.contentType === 'application/xhtml+xml');
+    const root = (snapshotLocation ? html.find((p) => p.location === snapshotLocation) : undefined) ??
+        html[0] ??
+        null;
+    return { root, parts, snapshotLocation, subject };
+}
+/** Parse a container and return its root frame decoded to a string. */
+export function mhtmlToHtml(raw) {
+    const parsed = parseMhtml(raw);
+    return {
+        html: parsed.root ? decodeCharset(parsed.root.body, parsed.root.charset) : '',
+        location: parsed.root?.location ?? parsed.snapshotLocation,
+        subject: parsed.subject,
+    };
+}
+//# sourceMappingURL=mhtml.js.map

package/dist/src/knowledge/mhtml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mhtml.js","sourceRoot":"","sources":["../../../src/knowledge/mhtml.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge/related.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Related-at-save (RCL-03) — "3 things in your brain relate to this".
+ *
+ * The extension calls this on EVERY capture, while the user watches. That
+ * single fact sets every design decision here:
+ *
+ *  - it never throws. An empty store, a missing embedder, a URL that was
+ *    never captured — all of them are an empty list, because a capture must
+ *    not fail because the sidebar had nothing to say;
+ *  - it is bounded. The vector pass races a timeout (default 2s) and the
+ *    cheap signals — same URL, same site, read straight off the metadata log —
+ *    are computed first, so a slow or absent embedder degrades to a fast
+ *    answer instead of no answer;
+ *  - the target itself is never in its own results, by path AND by canonical
+ *    URL, so a re-capture does not "relate" to the version it replaced.
+ *
+ * Three signals, combined: exact URL (the same page, captured before),
+ * same site, and vector similarity over the chunks already embedded.
+ *
+ * @module v1/cli/knowledge/related
+ */
+export type RelatedReason = 'same-url' | 'same-site' | 'similar';
+export interface RelatedDocument {
+    filePath: string;
+    scope: string;
+    title: string;
+    url?: string;
+    site?: string;
+    /** 0–1. Exact-URL matches lead; similarity and site agreement compound. */
+    score: number;
+    reasons: RelatedReason[];
+    capturedAt?: string;
+    /** The most similar passage, when similarity is one of the reasons. */
+    excerpt?: string;
+    chunkIndex?: number;
+    anchor?: string;
+}
+export interface RelatedOptions {
+    rootDir?: string;
+    scope?: string;
+    limit?: number;
+    /** Budget for the vector pass. The metadata signals ignore it: they are
+     *  synchronous file reads. */
+    timeoutMs?: number;
+    minScore?: number;
+    store?: 'project' | 'global' | 'all';
+    /** Text to compare against, when the caller already has it (a capture that
+     *  has not been ingested yet). */
+    text?: string;
+}
+/**
+ * The documents most related to `target` (a URL, a docId, or an indexed path).
+ *
+ * Safe to call on every capture: bounded, and empty rather than thrown on any
+ * failure.
+ */
+export declare function relatedDocuments(target: string, opts?: RelatedOptions): Promise<RelatedDocument[]>;
+//# sourceMappingURL=related.d.ts.map

package/dist/src/knowledge/related.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../../src/knowledge/related.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC;sCACkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAwFD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAmH5B"}