@monoes/monomindcli 2.14.0 → 2.15.0

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

@@ -0,0 +1,168 @@
+/**
+ * Highlights as atomic notes (RCL-04) — the ingest half.
+ *
+ * The extension writes `highlights.json` into the capture envelope beside
+ * `readable.md` (chrome-extension/highlights.js). This module turns each
+ * entry into a NOTE IN ITS OWN RIGHT that points back at the document it
+ * came from — searchable on its own terms, not buried inside a chunk of
+ * the page it was taken from.
+ *
+ * WHY A CHILD NOTE AND NOT A TAG ON THE PARENT. A highlight is a claim
+ * about what mattered, made by the reader, at a moment. Folding it into the
+ * parent's chunks loses all three: it stops being separately findable, it
+ * stops carrying its own comment, and it stops having a date. So each one
+ * is stored as its own entry, keyed under the parent's content hash, and
+ * linked back by `parent:` and `url:` tags.
+ *
+ * THE ANCHOR is the careful part. The extension measured its offsets
+ * against the LIVE PAGE'S TEXT; what got indexed is `readable.md`, a
+ * Readability pass over that same DOM. The two are close and not identical.
+ * So the offsets that arrive are treated as a hint and the QUOTE is treated
+ * as the truth: `locate` re-locates the quote in the extracted text and
+ * cuts a real citation anchor (`<hash12>#<start>-<end>`, citation.ts's
+ * shape) against the version it actually found. A highlight whose text is
+ * not in the document at all gets NO anchor rather than a plausible wrong
+ * one — the same rule citation.ts applies to a stale anchor, for the same
+ * reason.
+ *
+ * Everything here is as defensive as capture-envelope.ts, and for the same
+ * reason: `highlights.json` was written by a browser extension on a machine
+ * we do not control, and a malformed one must cost the capture nothing.
+ *
+ * @module v1/cli/knowledge/highlights
+ */
+import type { CaptureProvenance } from './capture-envelope.js';
+export declare const HIGHLIGHTS_FILE = "highlights.json";
+/** Tag namespaces, so a highlight is findable as one and traceable to its
+ *  parent without parsing anything. */
+export declare const HIGHLIGHT_TAG = "highlight";
+export declare const PARENT_TAG_PREFIX = "parent:";
+export declare const URL_TAG_PREFIX = "url:";
+/** The anchor as the extension measured it — offsets against the page's
+ *  visible text, plus the quote and its neighbourhood. */
+export interface HighlightAnchor {
+    /** A HINT. Measured against the live page, not the extracted text. */
+    startChar?: number;
+    endChar?: number;
+    /** The truth. What the reader actually selected. */
+    quote: string;
+    prefix?: string;
+    suffix?: string;
+    /** W3C `:~:text=` fragment, as citation.ts builds one. */
+    fragment?: string;
+}
+export interface Highlight {
+    id: string;
+    text: string;
+    anchor: HighlightAnchor;
+    createdAt?: string;
+    comment?: string;
+    color?: string;
+    /** The page URL pointed at this passage, as the extension wrote it. */
+    url?: string;
+}
+/** One highlight, resolved against the document it belongs to. */
+export interface HighlightNote {
+    id: string;
+    /** `<scope>:<filePath>` — the parent document's own id. */
+    parentDocId: string;
+    parentPath: string;
+    scope: string;
+    /** The parent's identity URL. */
+    parentUrl?: string;
+    parentTitle?: string;
+    text: string;
+    quote: string;
+    comment?: string;
+    createdAt?: string;
+    color?: string;
+    /** `<hash12>#<start>-<end>` against the EXTRACTED text — present only
+     *  when the quote was actually found there. */
+    anchor?: string;
+    startChar?: number;
+    endChar?: number;
+    /** The link that lands on the passage in the live page. */
+    citeUrl?: string;
+    capturedAt?: string;
+    /** What gets stored and embedded: the highlight, its note, its source. */
+    content: string;
+    tags: string[];
+}
+/** Keep only what we understand, coerced. An entry with no text is not a
+ *  highlight and is dropped rather than carried through as an empty note. */
+export declare function normalizeHighlight(raw: unknown, index?: number): Highlight | null;
+/**
+ * readHighlights reads the `highlights.json` sitting in `dir`. Returns an
+ * empty list — never throws — when there is none, it is unreadable,
+ * oversized, not JSON, or the wrong shape entirely.
+ */
+export declare function readHighlights(dir: string): Highlight[];
+/** readHighlightsFor reads the highlights belonging to an indexed file,
+ *  i.e. the ones in its envelope directory. */
+export declare function readHighlightsFor(filePath: string): Highlight[];
+/**
+ * locate finds a highlight's quote in the extracted text and returns its
+ * span there, or null.
+ *
+ * The order is the order of trustworthiness, and it is the SAME order the
+ * extension's own restore path uses (chrome-extension/highlights.js
+ * `relocate`), so a highlight that can be painted back onto the page can
+ * also be cited out of the archive:
+ *
+ *  1. prefix + quote + suffix — the neighbourhood, which survives the
+ *     Readability pass dropping a nav bar above it;
+ *  2. the occurrence nearest the recorded offset, for a quote that appears
+ *     more than once;
+ *  3. nothing. A quote that is not in the document gets no anchor. It is
+ *     still stored as a note — the reader did read it — but a citation
+ *     that cannot be checked is not offered as if it could.
+ */
+export declare function locate(text: string, anchor: HighlightAnchor): {
+    startChar: number;
+    endChar: number;
+} | null;
+export interface ParentDocument {
+    filePath: string;
+    scope: string;
+    /** Hash of the EXTRACTED text — the same one the anchor binds to. */
+    contentHash: string;
+    /** The extracted text itself, when the caller has it. Without it, no
+     *  anchor can be cut and the notes are stored unanchored. */
+    text?: string;
+    canonicalUrl?: string;
+    provenance?: CaptureProvenance;
+}
+/**
+ * highlightNotes turns an envelope's highlights into notes against a parent
+ * document. Pure: it reads nothing and writes nothing, so it is the whole
+ * of the interesting behaviour and the whole of what is tested.
+ */
+export declare function highlightNotes(parent: ParentDocument, highlights: readonly Highlight[]): HighlightNote[];
+export interface IngestHighlightsResult {
+    /** How many notes were stored. */
+    stored: number;
+    /** How many were found in the envelope at all. */
+    found: number;
+    /** How many resolved to a citable span in the extracted text. */
+    anchored: number;
+    notes: HighlightNote[];
+    error?: string;
+}
+/** The storage key for one highlight. Keyed under the PARENT'S content
+ *  hash, so re-ingesting the same version upserts the same notes rather
+ *  than accumulating a copy per ingest — the same discipline as the
+ *  pipeline's `doc:<hash>:<index>` chunk keys. */
+export declare function highlightKey(parentContentHash: string, id: string): string;
+/**
+ * ingestHighlights stores an envelope's highlights as notes linked to the
+ * parent document.
+ *
+ * Reports rather than throws: a capture whose highlights could not be
+ * stored is still a perfectly good capture, and failing the whole ingest
+ * over the annotations would lose the page as well as the notes.
+ */
+export declare function ingestHighlights(parent: ParentDocument, opts?: {
+    highlights?: readonly Highlight[];
+    dbPath?: string;
+}): Promise<IngestHighlightsResult>;
+//# sourceMappingURL=highlights.d.ts.map

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

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

package/dist/src/knowledge/highlights.js

@@ -0,0 +1,311 @@
+/**
+ * Highlights as atomic notes (RCL-04) — the ingest half.
+ *
+ * The extension writes `highlights.json` into the capture envelope beside
+ * `readable.md` (chrome-extension/highlights.js). This module turns each
+ * entry into a NOTE IN ITS OWN RIGHT that points back at the document it
+ * came from — searchable on its own terms, not buried inside a chunk of
+ * the page it was taken from.
+ *
+ * WHY A CHILD NOTE AND NOT A TAG ON THE PARENT. A highlight is a claim
+ * about what mattered, made by the reader, at a moment. Folding it into the
+ * parent's chunks loses all three: it stops being separately findable, it
+ * stops carrying its own comment, and it stops having a date. So each one
+ * is stored as its own entry, keyed under the parent's content hash, and
+ * linked back by `parent:` and `url:` tags.
+ *
+ * THE ANCHOR is the careful part. The extension measured its offsets
+ * against the LIVE PAGE'S TEXT; what got indexed is `readable.md`, a
+ * Readability pass over that same DOM. The two are close and not identical.
+ * So the offsets that arrive are treated as a hint and the QUOTE is treated
+ * as the truth: `locate` re-locates the quote in the extracted text and
+ * cuts a real citation anchor (`<hash12>#<start>-<end>`, citation.ts's
+ * shape) against the version it actually found. A highlight whose text is
+ * not in the document at all gets NO anchor rather than a plausible wrong
+ * one — the same rule citation.ts applies to a stale anchor, for the same
+ * reason.
+ *
+ * Everything here is as defensive as capture-envelope.ts, and for the same
+ * reason: `highlights.json` was written by a browser extension on a machine
+ * we do not control, and a malformed one must cost the capture nothing.
+ *
+ * @module v1/cli/knowledge/highlights
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { citationAnchor, citationUrl, passageQuote } from './citation.js';
+export const HIGHLIGHTS_FILE = 'highlights.json';
+/** Tag namespaces, so a highlight is findable as one and traceable to its
+ *  parent without parsing anything. */
+export const HIGHLIGHT_TAG = 'highlight';
+export const PARENT_TAG_PREFIX = 'parent:';
+export const URL_TAG_PREFIX = 'url:';
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_HIGHLIGHTS = 500;
+const MAX_TEXT = 4000;
+const MAX_COMMENT = 2000;
+// ── Reading ────────────────────────────────────────────────────────
+const str = (v, max) => {
+    if (typeof v !== 'string')
+        return undefined;
+    const trimmed = v.trim().slice(0, max).trim();
+    return trimmed ? trimmed : undefined;
+};
+const int = (v) => {
+    const n = typeof v === 'number' ? v : Number.NaN;
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : undefined;
+};
+/** Keep only what we understand, coerced. An entry with no text is not a
+ *  highlight and is dropped rather than carried through as an empty note. */
+export function normalizeHighlight(raw, index = 0) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const o = raw;
+    const text = str(o.text, MAX_TEXT);
+    if (!text)
+        return null;
+    const rawAnchor = o.anchor && typeof o.anchor === 'object' && !Array.isArray(o.anchor)
+        ? o.anchor
+        : {};
+    const quote = str(rawAnchor.quote, MAX_TEXT) ?? text;
+    const anchor = { quote };
+    const start = int(rawAnchor.startChar);
+    const end = int(rawAnchor.endChar);
+    if (start !== undefined)
+        anchor.startChar = start;
+    if (end !== undefined && (start === undefined || end >= start))
+        anchor.endChar = end;
+    const prefix = str(rawAnchor.prefix, 200);
+    const suffix = str(rawAnchor.suffix, 200);
+    const fragment = str(rawAnchor.fragment, 4000);
+    if (prefix)
+        anchor.prefix = prefix;
+    if (suffix)
+        anchor.suffix = suffix;
+    if (fragment)
+        anchor.fragment = fragment;
+    return {
+        id: str(o.id, 128) ?? `hl-${index}`,
+        text,
+        anchor,
+        ...(str(o.createdAt, 64) ? { createdAt: str(o.createdAt, 64) } : {}),
+        ...(str(o.comment, MAX_COMMENT) ? { comment: str(o.comment, MAX_COMMENT) } : {}),
+        ...(str(o.color, 32) ? { color: str(o.color, 32) } : {}),
+        ...(str(o.url, 4000) ? { url: str(o.url, 4000) } : {}),
+    };
+}
+/**
+ * readHighlights reads the `highlights.json` sitting in `dir`. Returns an
+ * empty list — never throws — when there is none, it is unreadable,
+ * oversized, not JSON, or the wrong shape entirely.
+ */
+export function readHighlights(dir) {
+    const file = path.join(path.resolve(dir), HIGHLIGHTS_FILE);
+    try {
+        if (!fs.existsSync(file))
+            return [];
+        if (fs.statSync(file).size > MAX_FILE_BYTES)
+            return [];
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const list = Array.isArray(parsed) ? parsed : parsed?.highlights;
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        const seen = new Set();
+        for (const [i, raw] of list.slice(0, MAX_HIGHLIGHTS).entries()) {
+            const h = normalizeHighlight(raw, i);
+            if (!h || seen.has(h.id))
+                continue;
+            seen.add(h.id);
+            out.push(h);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** readHighlightsFor reads the highlights belonging to an indexed file,
+ *  i.e. the ones in its envelope directory. */
+export function readHighlightsFor(filePath) {
+    return readHighlights(path.dirname(path.resolve(filePath)));
+}
+// ── Resolving ──────────────────────────────────────────────────────
+/**
+ * locate finds a highlight's quote in the extracted text and returns its
+ * span there, or null.
+ *
+ * The order is the order of trustworthiness, and it is the SAME order the
+ * extension's own restore path uses (chrome-extension/highlights.js
+ * `relocate`), so a highlight that can be painted back onto the page can
+ * also be cited out of the archive:
+ *
+ *  1. prefix + quote + suffix — the neighbourhood, which survives the
+ *     Readability pass dropping a nav bar above it;
+ *  2. the occurrence nearest the recorded offset, for a quote that appears
+ *     more than once;
+ *  3. nothing. A quote that is not in the document gets no anchor. It is
+ *     still stored as a note — the reader did read it — but a citation
+ *     that cannot be checked is not offered as if it could.
+ */
+export function locate(text, anchor) {
+    const haystack = String(text ?? '');
+    const quote = String(anchor?.quote ?? '');
+    if (!quote || !haystack)
+        return null;
+    if (anchor.prefix || anchor.suffix) {
+        const window = `${anchor.prefix ?? ''}${quote}${anchor.suffix ?? ''}`;
+        const at = haystack.indexOf(window);
+        if (at !== -1) {
+            const start = at + (anchor.prefix ?? '').length;
+            return { startChar: start, endChar: start + quote.length };
+        }
+    }
+    const hint = anchor.startChar;
+    let best = -1;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let at = haystack.indexOf(quote); at !== -1; at = haystack.indexOf(quote, at + 1)) {
+        if (hint === undefined) {
+            best = at;
+            break;
+        }
+        const distance = Math.abs(at - hint);
+        if (distance < bestDistance) {
+            best = at;
+            bestDistance = distance;
+        }
+    }
+    if (best === -1)
+        return null;
+    return { startChar: best, endChar: best + quote.length };
+}
+/** A note's stored body: the passage, the reader's comment, and where it
+ *  came from — so a search hit is legible without another lookup. */
+function noteContent(note) {
+    const lines = [note.text];
+    if (note.comment)
+        lines.push('', `Note: ${note.comment}`);
+    const source = note.parentTitle || note.parentUrl;
+    if (source)
+        lines.push('', `— ${source}`);
+    return lines.join('\n');
+}
+/**
+ * highlightNotes turns an envelope's highlights into notes against a parent
+ * document. Pure: it reads nothing and writes nothing, so it is the whole
+ * of the interesting behaviour and the whole of what is tested.
+ */
+export function highlightNotes(parent, highlights) {
+    const parentDocId = `${parent.scope}:${parent.filePath}`;
+    const parentUrl = parent.canonicalUrl ?? parent.provenance?.canonicalUrl ?? parent.provenance?.url;
+    const parentTitle = parent.provenance?.title;
+    const capturedAt = parent.provenance?.capturedAt;
+    return highlights.map((h) => {
+        const span = parent.text ? locate(parent.text, h.anchor) : null;
+        const note = {
+            id: h.id,
+            parentDocId,
+            parentPath: parent.filePath,
+            scope: parent.scope,
+            ...(parentUrl ? { parentUrl } : {}),
+            ...(parentTitle ? { parentTitle } : {}),
+            text: h.text,
+            quote: passageQuote(h.text),
+            ...(h.comment ? { comment: h.comment } : {}),
+            ...(h.createdAt ? { createdAt: h.createdAt } : {}),
+            ...(h.color ? { color: h.color } : {}),
+            ...(span
+                ? {
+                    anchor: citationAnchor(parent.contentHash, span.startChar, span.endChar),
+                    startChar: span.startChar,
+                    endChar: span.endChar,
+                }
+                : {}),
+            // The extension already built a text-fragment link; prefer it, and
+            // fall back to building one the same way citation.ts does.
+            ...(h.url
+                ? { citeUrl: h.url }
+                : parentUrl
+                    ? { citeUrl: citationUrl(parentUrl, h.text) }
+                    : {}),
+            ...(capturedAt ? { capturedAt } : {}),
+            content: '',
+            tags: [
+                HIGHLIGHT_TAG,
+                `${PARENT_TAG_PREFIX}${parentDocId}`,
+                ...(parentUrl ? [`${URL_TAG_PREFIX}${parentUrl}`] : []),
+                ...(h.color ? [`color:${h.color}`] : []),
+            ],
+        };
+        note.content = noteContent(note);
+        return note;
+    });
+}
+const KNOWLEDGE_NS_PREFIX = 'knowledge:';
+/** The storage key for one highlight. Keyed under the PARENT'S content
+ *  hash, so re-ingesting the same version upserts the same notes rather
+ *  than accumulating a copy per ingest — the same discipline as the
+ *  pipeline's `doc:<hash>:<index>` chunk keys. */
+export function highlightKey(parentContentHash, id) {
+    return `highlight:${parentContentHash}:${id}`;
+}
+async function getBridge() {
+    try {
+        return (await import('../memory/memory-bridge.js'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ingestHighlights stores an envelope's highlights as notes linked to the
+ * parent document.
+ *
+ * Reports rather than throws: a capture whose highlights could not be
+ * stored is still a perfectly good capture, and failing the whole ingest
+ * over the annotations would lose the page as well as the notes.
+ */
+export async function ingestHighlights(parent, opts = {}) {
+    const highlights = opts.highlights ?? readHighlightsFor(parent.filePath);
+    const notes = highlightNotes(parent, highlights);
+    const anchored = notes.filter((n) => n.anchor).length;
+    const base = {
+        stored: 0,
+        found: highlights.length,
+        anchored,
+        notes,
+    };
+    if (!notes.length)
+        return base;
+    const bridge = await getBridge();
+    if (!bridge)
+        return { ...base, error: 'memory bridge unavailable — no highlights stored' };
+    let stored = 0;
+    for (const note of notes) {
+        try {
+            const result = await bridge.bridgeStoreEntry({
+                key: highlightKey(parent.contentHash, note.id),
+                value: note.content,
+                namespace: `${KNOWLEDGE_NS_PREFIX}${parent.scope}`,
+                generateEmbeddingFlag: true,
+                tags: note.tags,
+                upsert: true,
+                ...(opts.dbPath ? { dbPath: opts.dbPath } : {}),
+            });
+            if (result?.success)
+                stored++;
+        }
+        catch {
+            // One note failing is not the others' problem, and the count below
+            // reports the shortfall honestly.
+        }
+    }
+    return {
+        ...base,
+        stored,
+        ...(stored === notes.length
+            ? {}
+            : { error: `stored ${stored}/${notes.length} highlights — re-ingest to repair` }),
+    };
+}
+//# sourceMappingURL=highlights.js.map

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

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

package/dist/src/knowledge/html-extract.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Dependency-free HTML → readable Markdown-ish text (RCL-01).
+ *
+ * WHY NO DEPENDENCY — the capture path has to work in an `npx monomind`
+ * install with nothing extra resolved, and the extension already runs
+ * Readability against the live DOM. What lands here is the fallback for an
+ * archive nobody cleaned: a small, predictable extractor beats a large one we
+ * cannot install.
+ *
+ * WHY BOILERPLATE STRIPPING IS THE POINT — a site's nav, header, footer and
+ * cookie banner are byte-identical on every page. Leave them in and every
+ * document from that site chunks into near-identical text, so their embeddings
+ * cluster on the chrome rather than the article and recall collapses. Dropping
+ * a little real content is a far cheaper error than keeping the chrome.
+ *
+ * @module v1/cli/knowledge/html-extract
+ */
+import { decodeEntities } from './html-tags.js';
+export { decodeEntities };
+export interface HtmlExtractOptions {
+    /** Drop nav/header/footer/aside/cookie-banner containers. Default true. */
+    stripBoilerplate?: boolean;
+}
+export interface ExtractedHtml {
+    /** `<title>` text, or null when the document has none. */
+    title: string | null;
+    /** Markdown-ish body text; headings as ATX, list items as `- `. */
+    text: string;
+}
+/**
+ * Parse `html` into a title and clean block text.
+ *
+ * Unbalanced markup is expected — real archives are full of it — so closing a
+ * tag pops back to its last matching open and a never-closed element simply
+ * stays open until its parent closes. Nothing here throws.
+ */
+export declare function extractHtmlDocument(html: string, opts?: HtmlExtractOptions): ExtractedHtml;
+/**
+ * Clean text for an HTML document, with the `<title>` promoted to an `# h1`
+ * when the page has no top-level heading of its own.
+ */
+export declare function htmlToMarkdown(html: string, opts?: HtmlExtractOptions): string;
+//# sourceMappingURL=html-extract.d.ts.map

package/dist/src/knowledge/html-extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-extract.d.ts","sourceRoot":"","sources":["../../../src/knowledge/html-extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAML,cAAc,EAIf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd;AAoLD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,aAAa,CAwF9F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,MAAM,CAKlF"}