@abhishekmcp/notes 0.1.1 → 0.3.0

package/dist/parse.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure, dependency-free markdown parsing: a tiny YAML-frontmatter reader plus
+ * extractors for headings, sections, wiki-links, tags and todos. We deliberately
+ * avoid gray-matter / js-yaml (npm-audit noise + native-free goal); the subset of
+ * YAML notes actually use in frontmatter is small enough to hand-roll safely.
+ */
+export interface Frontmatter {
+    title?: string;
+    tags?: string[];
+    [key: string]: unknown;
+}
+export interface Heading {
+    level: number;
+    text: string;
+    line: number;
+}
+export interface Todo {
+    text: string;
+    done: boolean;
+    line: number;
+}
+export interface ParsedNote {
+    frontmatter: Frontmatter;
+    body: string;
+    title?: string;
+    tags: string[];
+    links: string[];
+    headings: Heading[];
+}
+/** Strip a trailing ".md" and normalize separators so links/names compare equal. */
+export declare function normalizeLinkTarget(raw: string): string;
+/**
+ * Split raw note text into a frontmatter object and the remaining body.
+ * Recognizes a leading `---` ... `---` fence. Unparseable frontmatter is
+ * treated as body (never throws).
+ */
+export declare function splitFrontmatter(raw: string): {
+    frontmatter: Frontmatter;
+    body: string;
+};
+/** Extract ATX headings (`#`..`######`) from body text, ignoring fenced code blocks. */
+export declare function extractHeadings(body: string): Heading[];
+/**
+ * Return the text under a heading (case-insensitive match on heading text),
+ * up to the next heading of the same or higher level. Returns null if not found.
+ */
+export declare function extractSection(body: string, heading: string): string | null;
+/** Extract wiki-link targets (`[[name]]` / `[[name|alias]]`), normalized + deduped. */
+export declare function extractWikiLinks(body: string): string[];
+/** Collect tags from frontmatter plus inline #hashtags in the body, deduped. */
+export declare function extractTags(frontmatter: Frontmatter, body: string): string[];
+/** Extract checkbox todos (`- [ ]` / `- [x]`) from body text. */
+export declare function extractTodos(body: string): Todo[];
+/** Full parse of a raw note into structured pieces used by the index and graph. */
+export declare function parseNote(raw: string): ParsedNote;

package/dist/parse.js

@@ -0,0 +1,202 @@
+/**
+ * Pure, dependency-free markdown parsing: a tiny YAML-frontmatter reader plus
+ * extractors for headings, sections, wiki-links, tags and todos. We deliberately
+ * avoid gray-matter / js-yaml (npm-audit noise + native-free goal); the subset of
+ * YAML notes actually use in frontmatter is small enough to hand-roll safely.
+ */
+const WIKI_LINK = /\[\[([^\]]+)\]\]/g;
+/** Inline #hashtag: a '#' not followed by whitespace (so markdown headings "# x" don't match). */
+const HASHTAG = /(?:^|\s)#([A-Za-z0-9][\w/-]*)/g;
+/** Strip a trailing ".md" and normalize separators so links/names compare equal. */
+export function normalizeLinkTarget(raw) {
+    return raw.trim().replace(/\.md$/i, "").replace(/\\/g, "/").replace(/^\.?\/+/, "");
+}
+/** Strip surrounding single/double quotes from a scalar value. */
+function unquote(v) {
+    const t = v.trim();
+    if (t.length >= 2 && ((t[0] === '"' && t.endsWith('"')) || (t[0] === "'" && t.endsWith("'")))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+/** Parse `[a, b, "c"]` or `a, b, c` into a string list. */
+function parseInlineList(v) {
+    let s = v.trim();
+    if (s.startsWith("[") && s.endsWith("]"))
+        s = s.slice(1, -1);
+    return s
+        .split(",")
+        .map((x) => unquote(x))
+        .filter((x) => x.length > 0);
+}
+/**
+ * Split raw note text into a frontmatter object and the remaining body.
+ * Recognizes a leading `---` ... `---` fence. Unparseable frontmatter is
+ * treated as body (never throws).
+ */
+export function splitFrontmatter(raw) {
+    // Must start with --- on the very first line.
+    const m = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(raw);
+    if (!m || raw.slice(0, 3) !== "---") {
+        return { frontmatter: {}, body: raw };
+    }
+    const block = m[1];
+    const body = raw.slice(m[0].length);
+    const fm = {};
+    const lines = block.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        const kv = /^([A-Za-z0-9_-]+):[ \t]*(.*)$/.exec(line);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        const rest = kv[2];
+        if (rest.trim() === "") {
+            // Possible block list: subsequent "- item" lines.
+            const items = [];
+            let j = i + 1;
+            for (; j < lines.length; j++) {
+                const item = /^[ \t]+-[ \t]+(.*)$/.exec(lines[j]);
+                if (!item)
+                    break;
+                items.push(unquote(item[1]));
+            }
+            if (items.length > 0) {
+                fm[key] = key === "tags" ? items : items;
+                i = j - 1;
+            }
+            else {
+                fm[key] = "";
+            }
+            continue;
+        }
+        if (key === "tags") {
+            fm.tags = parseInlineList(rest);
+        }
+        else if (rest.trim().startsWith("[")) {
+            fm[key] = parseInlineList(rest);
+        }
+        else {
+            fm[key] = unquote(rest);
+        }
+    }
+    return { frontmatter: fm, body };
+}
+/** Extract ATX headings (`#`..`######`) from body text, ignoring fenced code blocks. */
+export function extractHeadings(body) {
+    const out = [];
+    const lines = body.split(/\r?\n/);
+    let inFence = false;
+    let fence = "";
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fenceMatch = /^[ \t]*(```+|~~~+)/.exec(line);
+        if (fenceMatch) {
+            if (!inFence) {
+                inFence = true;
+                fence = fenceMatch[1][0];
+            }
+            else if (line.trimStart().startsWith(fence)) {
+                inFence = false;
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        const h = /^(#{1,6})[ \t]+(.+?)[ \t]*#*$/.exec(line);
+        if (h)
+            out.push({ level: h[1].length, text: h[2].trim(), line: i + 1 });
+    }
+    return out;
+}
+/**
+ * Return the text under a heading (case-insensitive match on heading text),
+ * up to the next heading of the same or higher level. Returns null if not found.
+ */
+export function extractSection(body, heading) {
+    const lines = body.split(/\r?\n/);
+    const want = heading.trim().toLowerCase();
+    const headings = extractHeadings(body);
+    const start = headings.find((h) => h.text.toLowerCase() === want);
+    if (!start)
+        return null;
+    const startIdx = start.line - 1;
+    let endIdx = lines.length;
+    for (const h of headings) {
+        if (h.line - 1 > startIdx && h.level <= start.level) {
+            endIdx = h.line - 1;
+            break;
+        }
+    }
+    // Include the heading line itself for context.
+    return lines.slice(startIdx, endIdx).join("\n").trimEnd();
+}
+/** Extract wiki-link targets (`[[name]]` / `[[name|alias]]`), normalized + deduped. */
+export function extractWikiLinks(body) {
+    const seen = new Set();
+    const out = [];
+    let m;
+    WIKI_LINK.lastIndex = 0;
+    while ((m = WIKI_LINK.exec(body)) !== null) {
+        const target = normalizeLinkTarget(m[1].split("|")[0]);
+        if (target && !seen.has(target)) {
+            seen.add(target);
+            out.push(target);
+        }
+    }
+    return out;
+}
+/** Collect tags from frontmatter plus inline #hashtags in the body, deduped. */
+export function extractTags(frontmatter, body) {
+    const seen = new Set();
+    const out = [];
+    const add = (t) => {
+        const tag = t.trim().replace(/^#/, "");
+        const key = tag.toLowerCase();
+        if (tag && !seen.has(key)) {
+            seen.add(key);
+            out.push(tag);
+        }
+    };
+    if (Array.isArray(frontmatter.tags))
+        for (const t of frontmatter.tags)
+            add(String(t));
+    // Strip fenced code so code samples don't pollute tags.
+    const withoutFences = body.replace(/(```+|~~~+)[\s\S]*?\1/g, "");
+    let m;
+    HASHTAG.lastIndex = 0;
+    while ((m = HASHTAG.exec(withoutFences)) !== null)
+        add(m[1]);
+    return out;
+}
+/** Extract checkbox todos (`- [ ]` / `- [x]`) from body text. */
+export function extractTodos(body) {
+    const out = [];
+    const lines = body.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^[ \t]*[-*+][ \t]+\[([ xX])\][ \t]+(.*)$/.exec(lines[i]);
+        if (m)
+            out.push({ done: m[1].toLowerCase() === "x", text: m[2].trim(), line: i + 1 });
+    }
+    return out;
+}
+/** Full parse of a raw note into structured pieces used by the index and graph. */
+export function parseNote(raw) {
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const headings = extractHeadings(body);
+    const tags = extractTags(frontmatter, body);
+    const links = extractWikiLinks(body);
+    let title;
+    if (typeof frontmatter.title === "string" && frontmatter.title.trim()) {
+        title = frontmatter.title.trim();
+    }
+    else {
+        const h1 = headings.find((h) => h.level === 1);
+        if (h1)
+            title = h1.text;
+    }
+    return { frontmatter, body, title, tags, links, headings };
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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

package/dist/semantic.d.ts

@@ -0,0 +1,14 @@
+import { type SearchHit } from "./store.js";
+/**
+ * Rank notes by semantic similarity to `query`. With `hybrid`, fuse the vector
+ * ranking with MiniSearch's lexical ranking via Reciprocal Rank Fusion (k=60).
+ * First call downloads/loads the model and embeds the whole vault.
+ */
+export declare function semanticSearch(query: string, opts?: {
+    limit?: number;
+    hybrid?: boolean;
+}): Promise<{
+    hits: SearchHit[];
+    total: number;
+    hasMore: boolean;
+}>;

package/dist/semantic.js

@@ -0,0 +1,142 @@
+/**
+ * Semantic vector store: keeps an L2-normalized embedding per note, persisted to
+ * a sidecar cache and incrementally synced (mtime/size) against the text index.
+ * Mirrors store.ts's cache+sync pattern. The embedding model is only touched
+ * when a semantic search actually runs (first call embeds the whole vault).
+ */
+import { promises as fs } from "node:fs";
+import { EMBED_CACHE_VERSION, EMBED_DIM, EMBED_MODEL_ID, getEmbeddingsPath, cacheDisabled, } from "./config.js";
+import { atomicWrite, readRaw, resolveSafe } from "./fsutil.js";
+import { parseNote } from "./parse.js";
+import { embed } from "./embed.js";
+import { getAllMeta, searchNotes } from "./store.js";
+const vectors = new Map();
+let cacheLoaded = false;
+function encodeVec(v) {
+    return Buffer.from(v.buffer, v.byteOffset, v.byteLength).toString("base64");
+}
+function decodeVec(b64) {
+    const buf = Buffer.from(b64, "base64");
+    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+/** Load the persisted vectors once (ignored if model/dim/version changed). */
+async function loadCache() {
+    if (cacheLoaded || cacheDisabled()) {
+        cacheLoaded = true;
+        return;
+    }
+    cacheLoaded = true;
+    try {
+        const cache = JSON.parse(await fs.readFile(getEmbeddingsPath(), "utf8"));
+        if (cache.version !== EMBED_CACHE_VERSION || cache.model !== EMBED_MODEL_ID || cache.dim !== EMBED_DIM) {
+            return; // stale → will be rebuilt by sync
+        }
+        for (const [name, e] of Object.entries(cache.perNote ?? {})) {
+            vectors.set(name, { mtimeMs: e.mtimeMs, size: e.size, vec: decodeVec(e.vector) });
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            console.error(`Embeddings cache unreadable, rebuilding: ${err.message}`);
+        }
+    }
+}
+async function writeCache() {
+    if (cacheDisabled())
+        return;
+    const perNote = {};
+    for (const [name, e] of vectors)
+        perNote[name] = { mtimeMs: e.mtimeMs, size: e.size, vector: encodeVec(e.vec) };
+    const cache = { version: EMBED_CACHE_VERSION, model: EMBED_MODEL_ID, dim: EMBED_DIM, perNote };
+    try {
+        await atomicWrite(getEmbeddingsPath(), JSON.stringify(cache));
+    }
+    catch (err) {
+        console.error(`Could not write embeddings cache: ${err.message}`);
+    }
+}
+/** Embed new/changed notes, drop deleted ones, persist if anything changed. */
+async function sync() {
+    await loadCache();
+    const meta = getAllMeta();
+    let changed = false;
+    for (const [name, m] of meta) {
+        const prev = vectors.get(name);
+        if (prev && prev.mtimeMs === m.mtimeMs && prev.size === m.size)
+            continue;
+        try {
+            const { title, body } = parseNote(await readRaw(await resolveSafe(name)));
+            const vec = await embed(`${title ?? name}\n${body}`);
+            vectors.set(name, { mtimeMs: m.mtimeMs, size: m.size, vec });
+            changed = true;
+        }
+        catch (err) {
+            console.error(`Could not embed "${name}": ${err.message}`);
+        }
+    }
+    for (const name of [...vectors.keys()]) {
+        if (!meta.has(name)) {
+            vectors.delete(name);
+            changed = true;
+        }
+    }
+    if (changed)
+        await writeCache();
+}
+function dot(a, b) {
+    let s = 0;
+    for (let i = 0; i < EMBED_DIM; i++)
+        s += a[i] * b[i];
+    return s;
+}
+function snippet(body, width = 160) {
+    const flat = body.replace(/\s+/g, " ").trim();
+    return flat.length > width ? `${flat.slice(0, width)}…` : flat;
+}
+async function snippetFor(name) {
+    try {
+        return snippet(parseNote(await readRaw(await resolveSafe(name))).body);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Rank notes by semantic similarity to `query`. With `hybrid`, fuse the vector
+ * ranking with MiniSearch's lexical ranking via Reciprocal Rank Fusion (k=60).
+ * First call downloads/loads the model and embeds the whole vault.
+ */
+export async function semanticSearch(query, opts = {}) {
+    const limit = opts.limit ?? 10;
+    await sync();
+    const qv = await embed(query);
+    const ranked = [...vectors.entries()]
+        .map(([name, e]) => ({ name, score: dot(qv, e.vec) }))
+        .sort((a, b) => b.score - a.score);
+    let order;
+    if (opts.hybrid) {
+        const K = 60;
+        const fused = new Map();
+        ranked.slice(0, 50).forEach((r, i) => fused.set(r.name, (fused.get(r.name) ?? 0) + 1 / (K + i + 1)));
+        const lexical = await searchNotes(query, { limit: 50 });
+        lexical.hits.forEach((h, i) => fused.set(h.name, (fused.get(h.name) ?? 0) + 1 / (K + i + 1)));
+        order = [...fused.entries()].map(([name, score]) => ({ name, score })).sort((a, b) => b.score - a.score);
+    }
+    else {
+        order = ranked;
+    }
+    const total = order.length;
+    const page = order.slice(0, limit);
+    const meta = getAllMeta();
+    const hits = [];
+    for (const r of page) {
+        hits.push({
+            name: r.name,
+            title: meta.get(r.name)?.title ?? r.name,
+            score: r.score,
+            snippet: await snippetFor(r.name),
+        });
+    }
+    return { hits, total, hasMore: limit < total };
+}
+//# sourceMappingURL=semantic.js.map

package/dist/semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAerE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;AAC5C,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,SAAS,SAAS,CAAC,CAAe;IAChC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC9E,CAAC;AACD,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACvC,OAAO,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,8EAA8E;AAC9E,KAAK,UAAU,SAAS;IACtB,IAAI,WAAW,IAAI,aAAa,EAAE,EAAE,CAAC;QACnC,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO;IACT,CAAC;IACD,WAAW,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,EAAE,EAAE,MAAM,CAAC,CAAe,CAAC;QACvF,IAAI,KAAK,CAAC,OAAO,KAAK,mBAAmB,IAAI,KAAK,CAAC,KAAK,KAAK,cAAc,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YACvG,OAAO,CAAC,kCAAkC;QAC5C,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YAC5D,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,4CAA6C,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU;IACvB,IAAI,aAAa,EAAE;QAAE,OAAO;IAC5B,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IAChH,MAAM,KAAK,GAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC3G,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,iBAAiB,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,qCAAsC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,EAAE,CAAC;IAClB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;YAAE,SAAS;QACzE,IAAI,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,MAAM,OAAO,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC1E,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,KAAK,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;YAC7D,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,oBAAoB,IAAI,MAAO,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACrB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IACD,IAAI,OAAO;QAAE,MAAM,UAAU,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,GAAG,CAAC,CAAe,EAAE,CAAe;IAC3C,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE;QAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,KAAK,GAAG,GAAG;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,OAAO,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAa,EACb,OAA6C,EAAE;IAE/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,MAAM,IAAI,EAAE,CAAC;IAEb,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;SAClC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;SACrD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAErC,IAAI,KAA6C,CAAC;IAClD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,CAAC,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrG,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9F,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC3G,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,MAAM,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,IAAI;YACxC,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,KAAK,EAAE,CAAC;AACjD,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,102 @@
+import { validateName } from "./fsutil.js";
+/** Per-note metadata kept in memory and persisted to the cache. */
+export interface NoteMeta {
+    mtimeMs: number;
+    size: number;
+    title: string;
+    tags: string[];
+    outLinks: string[];
+}
+/**
+ * Load the index. Tries the cache and incrementally syncs against disk
+ * (re-parsing only new/changed files, dropping deleted ones). Falls back to a
+ * full rebuild if the cache is missing, unreadable, or the version changed.
+ * Call once on startup before serving requests.
+ */
+export declare function buildIndex(): Promise<void>;
+export declare function getAllMeta(): Map<string, NoteMeta>;
+export declare function getMeta(name: string): NoteMeta | undefined;
+export declare function noteExists(name: string): boolean;
+export interface NoteSummary {
+    name: string;
+    title: string;
+    size: number;
+    mtimeMs: number;
+    tags: string[];
+}
+export interface ListResult {
+    items: NoteSummary[];
+    total: number;
+    hasMore: boolean;
+}
+/** List notes (newest first), optionally filtered by tag, with pagination. */
+export declare function listNotes(offset?: number, limit?: number, tag?: string): ListResult;
+export interface ReadResult {
+    text: string;
+    truncated: boolean;
+}
+/**
+ * Read a note's content. With `section`, returns just that heading's block.
+ * With `offset`/`limit` (character window), returns a slice + a `truncated` flag.
+ */
+export declare function readNote(name: string, opts?: {
+    section?: string;
+    offset?: number;
+    limit?: number;
+}): Promise<ReadResult>;
+/** Heading-tree outline of a note (cheap way to grasp a big note). */
+export declare function getOutline(name: string): Promise<string>;
+export declare function createNote(name: string, content: string, overwrite?: boolean): Promise<string>;
+export declare function appendNote(name: string, content: string): Promise<string>;
+export declare function deleteNote(name: string): Promise<void>;
+export interface MoveResult {
+    from: string;
+    to: string;
+    rewritten: string[];
+}
+/**
+ * Move/rename a note and rewrite every `[[from]]` wiki-link across the vault to
+ * `[[to]]`. Keeps the index, graph and cache consistent.
+ */
+export declare function moveNote(from: string, to: string): Promise<MoveResult>;
+export interface SearchHit {
+    name: string;
+    title: string;
+    score: number;
+    snippet: string;
+}
+export interface SearchResultPage {
+    hits: SearchHit[];
+    total: number;
+    hasMore: boolean;
+}
+/**
+ * Ranked full-text search. Supports `fuzzy`, `prefix`, a `field` filter
+ * (title/tag/body, or `path` to match the note name), and pagination. Returns
+ * ranked snippets with surrounding context.
+ */
+export declare function searchNotes(query: string, opts?: {
+    fuzzy?: boolean;
+    prefix?: boolean;
+    field?: string;
+    offset?: number;
+    limit?: number;
+}): Promise<SearchResultPage>;
+export interface TagCount {
+    tag: string;
+    count: number;
+}
+/** All tags across the vault with note counts (case-insensitive grouping). */
+export declare function listTags(): TagCount[];
+export interface TodoItem {
+    note: string;
+    text: string;
+    done: boolean;
+    line: number;
+}
+/** Aggregate `- [ ]` / `- [x]` checkboxes across all notes. */
+export declare function listTodos(includeDone?: boolean): Promise<TodoItem[]>;
+/** Notes-dir banner for startup logging. */
+export declare function notesDir(): string;
+/** Exposed for tests: validate a name without touching disk. */
+export { validateName };