@monoes/monomindcli 2.14.0 → 2.14.1

package/dist/src/knowledge/related.js

@@ -0,0 +1,222 @@
+/**
+ * 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
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { captureIdentityUrl, readCaptureProvenance } from './capture-envelope.js';
+import { passageQuote } from './citation.js';
+import { documentCapturedAt, documentSite } from './library.js';
+const DEFAULT_LIMIT = 3;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_MIN_SCORE = 0.25;
+const QUERY_CHARS = 1200;
+const SAME_URL_SCORE = 1;
+/** Ceiling for everything that is not literally the same page. */
+const NEAR_SCORE_CAP = 0.95;
+const SAME_SITE_SCORE = 0.45;
+const BOTH_SIGNALS_BONUS = 0.1;
+const EXCERPT_CHARS = 200;
+function stripFragment(url) {
+    const hash = url.indexOf('#');
+    return (hash === -1 ? url : url.slice(0, hash)).trim();
+}
+function looksLikeUrl(target) {
+    return /^https?:\/\//i.test(target.trim());
+}
+function hostOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Words a URL alone gives us — the fallback query when there is no text. */
+function urlWords(url) {
+    try {
+        const u = new URL(url);
+        return [u.hostname.replace(/^www\./, ''), ...u.pathname.split(/[/\-_.]+/)]
+            .filter((w) => w && !/^\d+$/.test(w) && w.length > 1)
+            .join(' ');
+    }
+    catch {
+        return url;
+    }
+}
+async function queryText(record, target, provided) {
+    if (provided?.trim())
+        return provided.slice(0, QUERY_CHARS);
+    const parts = [];
+    if (record?.provenance?.title)
+        parts.push(record.provenance.title);
+    if (record && fs.existsSync(record.filePath)) {
+        try {
+            const { extractText } = await import('../capabilities/cap-documents.js');
+            const stat = fs.statSync(record.filePath);
+            const text = await extractText({
+                path: record.filePath,
+                absolutePath: record.filePath,
+                extension: path.extname(record.filePath).toLowerCase(),
+                size: stat.size,
+                modified: stat.mtime,
+                created: stat.birthtime,
+            });
+            if (text)
+                parts.push(text.slice(0, QUERY_CHARS));
+        }
+        catch {
+            /* fall through to the URL words */
+        }
+    }
+    if (!parts.length)
+        parts.push(urlWords(looksLikeUrl(target) ? target : path.basename(target)));
+    return parts.join('\n').slice(0, QUERY_CHARS);
+}
+/** Resolve the vector pass or give up on time — whichever comes first. */
+function withTimeout(work, ms, fallback) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(fallback), ms);
+        work
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch(() => {
+            clearTimeout(timer);
+            resolve(fallback);
+        });
+    });
+}
+/**
+ * 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 async function relatedDocuments(target, opts = {}) {
+    try {
+        const pipeline = await import('./document-pipeline.js');
+        const scope = opts.scope;
+        const rootDir = opts.rootDir ?? pipeline.getKnowledgeRoot(scope ?? 'shared');
+        const limit = opts.limit ?? DEFAULT_LIMIT;
+        const self = pipeline.findDocumentRecord(rootDir, target, scope);
+        // A capture that has been written but not yet ingested is the case this
+        // story exists for: the extension has the directory on disk and wants to
+        // know what it relates to BEFORE the ingest finishes. Its identity comes
+        // from the envelope's own meta.json.
+        const pending = !self && !looksLikeUrl(target) ? readCaptureProvenance(target) : null;
+        const selfUrl = self?.canonicalUrl ??
+            (looksLikeUrl(target) ? stripFragment(target) : captureIdentityUrl(pending));
+        const selfSite = hostOf(selfUrl);
+        const selfPaths = new Set([self?.filePath, looksLikeUrl(target) ? undefined : path.resolve(target)].filter((p) => !!p));
+        // Excluding by URL is right when the target IS that page — an indexed
+        // document, or a caller asking about the URL itself. It is wrong for a
+        // capture still sitting in the inbox: there the earlier capture of the
+        // same page is the single most related thing in the brain.
+        const excludeByUrl = !!self || looksLikeUrl(target);
+        const isSelf = (doc) => selfPaths.has(doc.filePath) || (excludeByUrl && !!selfUrl && doc.canonicalUrl === selfUrl);
+        const docs = pipeline.listDocuments(rootDir, scope).filter((d) => !isSelf(d));
+        const byPath = new Map(docs.map((d) => [d.filePath, d]));
+        const scored = new Map();
+        const put = (doc, reason, score, extra = {}) => {
+            const existing = scored.get(doc.filePath);
+            if (existing) {
+                if (!existing.reasons.includes(reason))
+                    existing.reasons.push(reason);
+                // Agreeing signals compound, but only the same page itself reaches 1 —
+                // otherwise a same-site neighbour that also embeds well would tie with
+                // the earlier capture of this very page and win on sort order.
+                const cap = existing.reasons.includes('same-url') ? SAME_URL_SCORE : NEAR_SCORE_CAP;
+                existing.score = Math.min(cap, Math.max(existing.score, score) + BOTH_SIGNALS_BONUS);
+                Object.assign(existing, extra);
+                return;
+            }
+            const url = doc.canonicalUrl ?? doc.provenance?.canonicalUrl ?? doc.provenance?.url;
+            scored.set(doc.filePath, {
+                filePath: doc.filePath,
+                scope: doc.scope,
+                title: doc.provenance?.title ?? path.basename(doc.filePath),
+                ...(url ? { url } : {}),
+                ...(documentSite(doc) ? { site: documentSite(doc) } : {}),
+                score,
+                reasons: [reason],
+                ...(documentCapturedAt(doc) ? { capturedAt: documentCapturedAt(doc) } : {}),
+                ...extra,
+            });
+        };
+        // 1 + 2 — the cheap signals, straight off the metadata log.
+        for (const doc of docs) {
+            const url = doc.canonicalUrl ?? doc.provenance?.canonicalUrl;
+            if (selfUrl && url && stripFragment(url) === selfUrl)
+                put(doc, 'same-url', SAME_URL_SCORE);
+            else if (selfSite && documentSite(doc) === selfSite)
+                put(doc, 'same-site', SAME_SITE_SCORE);
+        }
+        // 3 — similarity, bounded. A store with no embeddings comes back empty
+        // here and the metadata signals still stand.
+        // For a not-yet-ingested capture the text to compare against is the file
+        // the caller pointed at, read through the same extraction the ingest uses.
+        const queryRecord = self ?? (pending ? { filePath: path.resolve(target), provenance: pending } : undefined);
+        const query = await queryText(queryRecord, target, opts.text);
+        if (query.trim()) {
+            const hits = await withTimeout(pipeline.searchKnowledge(query, {
+                scope: scope ?? 'shared',
+                rootDir,
+                limit: Math.max(limit * 6, 12),
+                minScore: opts.minScore ?? DEFAULT_MIN_SCORE,
+                store: opts.store ?? 'all',
+            }), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, []);
+            const best = new Map();
+            for (const hit of hits) {
+                if (!hit.filePath || selfPaths.has(hit.filePath))
+                    continue;
+                const current = best.get(hit.filePath);
+                if (!current || hit.similarity > current.similarity)
+                    best.set(hit.filePath, hit);
+            }
+            for (const [filePath, hit] of best) {
+                const doc = byPath.get(filePath);
+                if (!doc || isSelf(doc))
+                    continue;
+                put(doc, 'similar', Math.min(1, hit.similarity), {
+                    excerpt: passageQuote(hit.text ?? '', EXCERPT_CHARS),
+                    chunkIndex: hit.chunkIndex,
+                    ...(hit.anchor ? { anchor: hit.anchor } : {}),
+                });
+            }
+        }
+        return [...scored.values()]
+            .sort((a, b) => b.score - a.score || (b.capturedAt ?? '').localeCompare(a.capturedAt ?? ''))
+            .slice(0, limit);
+    }
+    catch (err) {
+        // Called on every capture: an unexpected failure is "nothing related",
+        // never a broken save. It is still a bug when it is one of ours, so it is
+        // visible under DEBUG rather than only in an empty sidebar.
+        if (process.env.DEBUG || process.env.MONOMIND_DEBUG) {
+            console.error(`[relatedDocuments] ${target}:`, err);
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=related.js.map

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

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

package/dist/src/knowledge/section-diff.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Semantic diff between two versions of a captured page (RCL-08).
+ *
+ * A character diff of a re-captured page is noise: the byline date moved, an
+ * ad slot re-rendered, the markdown re-wrapped. What a watcher actually wants
+ * to be told is WHICH SECTIONS changed and roughly how much — "Pricing gained
+ * a paragraph, Changelog got three new entries, everything else is the same".
+ *
+ * So the unit here is the markdown section (heading + body), keyed by its
+ * full heading path, and the measure is words and sentences rather than
+ * characters. Sentences are also what gives a change its sample line: the
+ * first sentence that is in the new version and was not in the old one is the
+ * most useful single thing to print.
+ *
+ * No dependency, no LLM: heading paths and sentence sets are enough to say
+ * what moved.
+ *
+ * @module v1/cli/knowledge/section-diff
+ */
+export interface Section {
+    /** Full heading path, e.g. `Pricing > Enterprise`. `(intro)` for text
+     *  before the first heading. */
+    key: string;
+    heading: string;
+    level: number;
+    body: string;
+}
+export interface SectionChange {
+    key: string;
+    addedWords: number;
+    removedWords: number;
+    /** First sentence present in the new version and absent from the old. */
+    sample?: string;
+}
+export interface SectionDiff {
+    added: string[];
+    removed: string[];
+    changed: SectionChange[];
+    unchanged: number;
+    /** One line, ready to print or to put in a notification. */
+    summary: string;
+}
+/** Split markdown into sections keyed by heading path. Duplicate paths get a
+ *  `#2` suffix so two "Notes" sections never collapse into one. */
+export declare function splitSections(text: string): Section[];
+/** What changed between two versions of the same page. */
+export declare function diffSections(oldText: string, newText: string): SectionDiff;
+//# sourceMappingURL=section-diff.d.ts.map

package/dist/src/knowledge/section-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-diff.d.ts","sourceRoot":"","sources":["../../../src/knowledge/section-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,OAAO;IACtB;oCACgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;mEACmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAmCrD;AA2DD,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAgC1E"}

package/dist/src/knowledge/section-diff.js

@@ -0,0 +1,151 @@
+/**
+ * Semantic diff between two versions of a captured page (RCL-08).
+ *
+ * A character diff of a re-captured page is noise: the byline date moved, an
+ * ad slot re-rendered, the markdown re-wrapped. What a watcher actually wants
+ * to be told is WHICH SECTIONS changed and roughly how much — "Pricing gained
+ * a paragraph, Changelog got three new entries, everything else is the same".
+ *
+ * So the unit here is the markdown section (heading + body), keyed by its
+ * full heading path, and the measure is words and sentences rather than
+ * characters. Sentences are also what gives a change its sample line: the
+ * first sentence that is in the new version and was not in the old one is the
+ * most useful single thing to print.
+ *
+ * No dependency, no LLM: heading paths and sentence sets are enough to say
+ * what moved.
+ *
+ * @module v1/cli/knowledge/section-diff
+ */
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const INTRO_KEY = '(intro)';
+/** Split markdown into sections keyed by heading path. Duplicate paths get a
+ *  `#2` suffix so two "Notes" sections never collapse into one. */
+export function splitSections(text) {
+    const lines = String(text ?? '').split('\n');
+    const stack = [];
+    const sections = [];
+    const seen = new Map();
+    let current = { key: INTRO_KEY, heading: INTRO_KEY, level: 0, body: '' };
+    const buffer = [];
+    const flush = () => {
+        current.body = buffer.join('\n').trim();
+        buffer.length = 0;
+        if (current.key !== INTRO_KEY || current.body)
+            sections.push(current);
+    };
+    let inFence = false;
+    for (const line of lines) {
+        if (/^\s{0,3}(`{3,}|~{3,})/.test(line))
+            inFence = !inFence;
+        const m = inFence ? null : HEADING_RE.exec(line);
+        if (!m) {
+            buffer.push(line);
+            continue;
+        }
+        flush();
+        const level = m[1].length;
+        const heading = m[2].trim();
+        stack.length = Math.max(0, level - 1);
+        stack[level - 1] = heading;
+        let key = stack.filter(Boolean).join(' > ');
+        const n = (seen.get(key) ?? 0) + 1;
+        seen.set(key, n);
+        if (n > 1)
+            key = `${key} #${n}`;
+        current = { key, heading, level, body: '' };
+    }
+    flush();
+    return sections;
+}
+function words(text) {
+    return text.toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) ?? [];
+}
+function sentences(text) {
+    return text
+        .replace(/\s+/g, ' ')
+        .split(/(?<=[.!?])\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Multiset difference: how many words the new body has that the old did not
+ *  (and vice versa), so re-ordering a paragraph does not read as a rewrite. */
+function wordDelta(oldBody, newBody) {
+    const counts = new Map();
+    for (const w of words(oldBody))
+        counts.set(w, (counts.get(w) ?? 0) + 1);
+    let added = 0;
+    for (const w of words(newBody)) {
+        const have = counts.get(w) ?? 0;
+        if (have > 0)
+            counts.set(w, have - 1);
+        else
+            added++;
+    }
+    let removed = 0;
+    for (const n of counts.values())
+        removed += n;
+    return { added, removed };
+}
+const SAMPLE_MAX = 160;
+function firstNewSentence(oldBody, newBody) {
+    const before = new Set(sentences(oldBody));
+    for (const s of sentences(newBody)) {
+        if (before.has(s))
+            continue;
+        return s.length > SAMPLE_MAX ? `${s.slice(0, SAMPLE_MAX - 1)}…` : s;
+    }
+    return undefined;
+}
+const SUMMARY_SECTIONS = 3;
+function renderSummary(diff) {
+    const parts = [];
+    if (diff.changed.length)
+        parts.push(`${diff.changed.length} section(s) changed`);
+    if (diff.added.length)
+        parts.push(`${diff.added.length} added`);
+    if (diff.removed.length)
+        parts.push(`${diff.removed.length} removed`);
+    if (!parts.length)
+        return 'text changed, but no section did — formatting only';
+    const detail = [
+        ...diff.changed
+            .slice(0, SUMMARY_SECTIONS)
+            .map((c) => `${c.key} (+${c.addedWords}/-${c.removedWords} words)`),
+        ...diff.added.slice(0, SUMMARY_SECTIONS).map((k) => `+${k}`),
+        ...diff.removed.slice(0, SUMMARY_SECTIONS).map((k) => `-${k}`),
+    ];
+    return detail.length ? `${parts.join(', ')} — ${detail.join('; ')}` : parts.join(', ');
+}
+/** What changed between two versions of the same page. */
+export function diffSections(oldText, newText) {
+    const before = new Map(splitSections(oldText).map((s) => [s.key, s]));
+    const after = new Map(splitSections(newText).map((s) => [s.key, s]));
+    const added = [];
+    const changed = [];
+    let unchanged = 0;
+    for (const [key, section] of after) {
+        const previous = before.get(key);
+        if (!previous) {
+            added.push(key);
+            continue;
+        }
+        if (previous.body.replace(/\s+/g, ' ').trim() === section.body.replace(/\s+/g, ' ').trim()) {
+            unchanged++;
+            continue;
+        }
+        const delta = wordDelta(previous.body, section.body);
+        changed.push({
+            key,
+            addedWords: delta.added,
+            removedWords: delta.removed,
+            ...(firstNewSentence(previous.body, section.body)
+                ? { sample: firstNewSentence(previous.body, section.body) }
+                : {}),
+        });
+    }
+    const removed = [...before.keys()].filter((k) => !after.has(k));
+    const diff = { added, removed, changed, unchanged };
+    return { ...diff, summary: renderSummary(diff) };
+}
+//# sourceMappingURL=section-diff.js.map

package/dist/src/knowledge/section-diff.js.map

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

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

@@ -0,0 +1,92 @@
+/**
+ * Watch a captured page for change (RCL-08).
+ *
+ * WHAT THIS IS NOT: a scheduler, a daemon, or a fetcher. `checkWatches` is
+ * invoked by something else — mono-agent's scheduler drives it — and it does
+ * not touch the network. It re-reads what the pipeline already stored and
+ * compares content hashes, which is exactly the versioning RCL-06 put there.
+ * A re-capture is what makes a page "change"; this reports it.
+ *
+ * The watch list is a small JSON file next to the metadata log, keyed by the
+ * page's identity URL (or, for a local file, its path). Writes go through a
+ * temp file and a rename so a crashed check cannot leave a half-written list.
+ *
+ * @module v1/cli/knowledge/watch
+ */
+import { type SectionDiff } from './section-diff.js';
+export declare const WATCH_FILE = "watches.json";
+export declare const DEFAULT_INTERVAL_SECONDS = 86400;
+export interface WatchEntry {
+    /** Identity: the capture's canonical URL, or an indexed file path. */
+    url: string;
+    scope: string;
+    intervalSeconds: number;
+    /** Content hash last seen by a check — the baseline the next one compares to. */
+    lastHash?: string;
+    lastCheckedAt?: string;
+    lastChangedAt?: string;
+    addedAt: string;
+    label?: string;
+}
+export type WatchStatus = 'changed' | 'unchanged' | 'new' | 'missing' | 'not-due';
+export interface WatchCheck {
+    url: string;
+    scope: string;
+    status: WatchStatus;
+    checkedAt: string;
+    filePath?: string;
+    title?: string;
+    previousHash?: string;
+    currentHash?: string;
+    version?: number;
+    capturedAt?: string;
+    /** Present on `changed`, unless the previous version's file is gone. */
+    diff?: SectionDiff;
+    /** Why a change could not be summarized, when it could not. */
+    note?: string;
+}
+export interface WatchCheckReport {
+    checked: number;
+    changed: number;
+    skipped: number;
+    results: WatchCheck[];
+}
+export declare function listWatches(rootDir: string): WatchEntry[];
+/** `30m`, `6h`, `2d`, or bare seconds. Throws on a typo — a watch that
+ *  silently defaulted to daily would look like it was working. */
+export declare function parseInterval(value: string | number | undefined): number;
+export interface AddWatchOptions {
+    interval?: string | number;
+    scope?: string;
+    label?: string;
+    now?: Date;
+}
+/**
+ * Watch `target` (a URL, a docId or an indexed path).
+ *
+ * The baseline is seeded from what is indexed RIGHT NOW, so the first check
+ * after adding reports nothing — a watch exists to catch the NEXT change, not
+ * to re-announce the capture that created it. Re-adding an existing watch
+ * updates its interval and label and keeps the baseline.
+ */
+export declare function addWatch(rootDir: string, target: string, opts?: AddWatchOptions): Promise<WatchEntry>;
+/** Stop watching. Matches the stored identity URL, a docId, or a path. */
+export declare function removeWatch(rootDir: string, target: string, scope?: string): boolean;
+export interface CheckWatchesOptions {
+    scope?: string;
+    /** Check every watch regardless of its interval. */
+    force?: boolean;
+    /** Report without updating the stored baselines. */
+    dryRun?: boolean;
+    now?: Date;
+}
+/**
+ * Which watched pages have changed since the last check.
+ *
+ * Reads only what is already indexed: a page "changes" when a new capture of
+ * it was ingested under a new content hash. Each change carries a section-level
+ * summary (`diffSections`) built from the previous version's own archived
+ * file, or a note saying why it could not be built.
+ */
+export declare function checkWatches(rootDir: string, opts?: CheckWatchesOptions): Promise<WatchCheckReport>;
+//# sourceMappingURL=watch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../../src/knowledge/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEnE,eAAO,MAAM,UAAU,iBAAiB,CAAC;AACzC,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAQD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAWzD;AAaD;kEACkE;AAClE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAQxE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,UAAU,CAAC,CA8BrB;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CASpF;AAID,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AA2BD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA8E3B"}