@oomkapwn/enquire-mcp 0.10.6 → 0.13.0

package/dist/tools.js

@@ -33,7 +33,23 @@ export async function listNotes(vault, args) {
 export async function readNote(vault, args) {
     await vault.ensureExists();
     const entry = await resolveTarget(vault, args);
-    const { parsed, mtimeMs } = await vault.readNote(entry.absPath, entry.mtimeMs);
+    const { content, parsed, mtimeMs } = await vault.readNote(entry.absPath, entry.mtimeMs);
+    if (args.format === "map") {
+        // Document-map projection — headings + frontmatter keys + counts. Lets an
+        // LLM plan a surgical edit without paying token cost for the full body.
+        return {
+            path: entry.relPath,
+            title: stripMd(entry.basename),
+            format: "map",
+            frontmatter_keys: Object.keys(parsed.frontmatter),
+            headings: extractHeadings(parsed.body),
+            wikilinks_count: parsed.wikilinks.length,
+            embeds_count: parsed.embeds.length,
+            tags: parsed.tags,
+            mtime: new Date(mtimeMs).toISOString(),
+            byte_size: Buffer.byteLength(content, "utf8")
+        };
+    }
     return {
         path: entry.relPath,
         title: stripMd(entry.basename),
@@ -45,6 +61,28 @@ export async function readNote(vault, args) {
         mtime: new Date(mtimeMs).toISOString()
     };
 }
+/** Pull ATX headings (`#`, `##`, `###`, etc.) out of note body for the
+ *  document-map projection. Skips ATX inside fenced code blocks via a simple
+ *  line-by-line backtick toggle. */
+function extractHeadings(body) {
+    const out = [];
+    const lines = body.split("\n");
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (/^\s*```/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const m = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+        if (m && m[1] && m[2]) {
+            out.push({ level: m[1].length, text: m[2], line: i + 1 });
+        }
+    }
+    return out;
+}
 export async function resolveWikilink(vault, args) {
     await vault.ensureExists();
     const cleaned = args.wikilink.replace(/^!?\[\[|\]\]$/g, "");
@@ -376,6 +414,61 @@ function extractFrontmatterTagsLower(fm) {
             : [];
     return list.map((t) => t.replace(/^#+/, "").toLowerCase());
 }
+/** Resolve "today"/"daily"/"weekly"/"monthly" to today's periodic-note name
+ *  using the standard Obsidian Daily-Notes-plugin formats. Custom formats are
+ *  out of scope (users with non-default conventions address by exact name). */
+function resolvePeriodicAlias(title) {
+    const lower = title.trim().toLowerCase();
+    if (lower !== "daily" && lower !== "today" && lower !== "weekly" && lower !== "monthly") {
+        return null;
+    }
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    if (lower === "daily" || lower === "today")
+        return `${yyyy}-${mm}-${dd}`;
+    if (lower === "monthly")
+        return `${yyyy}-${mm}`;
+    // ISO week number (Mon-based, ISO 8601). Weekly format: YYYY-Www.
+    const target = new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+    const dayNum = target.getUTCDay() || 7; // Mon=1..Sun=7
+    target.setUTCDate(target.getUTCDate() + 4 - dayNum); // Thursday of this week
+    const yearStart = new Date(Date.UTC(target.getUTCFullYear(), 0, 1));
+    const weekNo = Math.ceil(((target.valueOf() - yearStart.valueOf()) / 86400000 + 1) / 7);
+    return `${target.getUTCFullYear()}-W${String(weekNo).padStart(2, "0")}`;
+}
+/** Up to 3 vault-relative paths whose basename or relPath looks similar to
+ *  the missing target. Used to enrich `Note not found` errors with did-you-mean
+ *  hints — meaningful for LLMs that mistype a note name. */
+async function suggestSimilar(vault, target) {
+    try {
+        const all = await vault.listMarkdown();
+        const lower = target.toLowerCase().replace(/\.md$/i, "");
+        const ranked = all
+            .map((e) => {
+            const baseLower = stripMd(e.basename).toLowerCase();
+            const relLower = e.relPath.toLowerCase();
+            let score = 0;
+            if (baseLower === lower)
+                score = 100;
+            else if (baseLower.startsWith(lower) || lower.startsWith(baseLower))
+                score = 70;
+            else if (baseLower.includes(lower) || lower.includes(baseLower))
+                score = 50;
+            else if (relLower.includes(lower))
+                score = 30;
+            return { path: e.relPath, score };
+        })
+            .filter((r) => r.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 3);
+        return ranked.map((r) => r.path);
+    }
+    catch {
+        return [];
+    }
+}
 async function resolveTarget(vault, args) {
     if (args.path) {
         const candidates = args.path.toLowerCase().endsWith(".md") ? [args.path] : [args.path, `${args.path}.md`];
@@ -395,16 +488,423 @@ async function resolveTarget(vault, args) {
                 lastErr = err;
             }
         }
-        throw lastErr instanceof Error ? lastErr : new Error(`Note not found: ${args.path}`);
+        const suggestions = await suggestSimilar(vault, args.path);
+        const hint = suggestions.length ? `. Did you mean: ${suggestions.join(", ")}?` : "";
+        throw lastErr instanceof Error
+            ? new Error(`${lastErr.message}${hint}`)
+            : new Error(`Note not found: ${args.path}${hint}`);
     }
     if (args.title) {
-        const found = await vault.findByTitle(args.title);
-        if (!found)
-            throw new Error(`No note found with title: ${args.title}`);
-        return found;
+        // Try literal title first — a user may have an actual file named
+        // "Daily.md" / "Today.md" they meant to address. Only fall back to the
+        // periodic-note alias when the literal lookup misses.
+        const literal = await vault.findByTitle(args.title);
+        if (literal)
+            return literal;
+        const aliased = resolvePeriodicAlias(args.title);
+        if (aliased) {
+            const aliasMatch = await vault.findByTitle(aliased);
+            if (aliasMatch)
+                return aliasMatch;
+        }
+        const suggestions = await suggestSimilar(vault, args.title);
+        const hint = suggestions.length ? `. Did you mean: ${suggestions.join(", ")}?` : "";
+        const aliasNote = aliased ? ` (also tried periodic alias "${aliased}")` : "";
+        throw new Error(`No note found with title: ${args.title}${aliasNote}${hint}`);
     }
     throw new Error("Either path or title is required");
 }
+export async function validateNoteProposal(vault, args) {
+    await vault.ensureExists();
+    const mode = args.mode ?? "create";
+    const errors = [];
+    const warnings = [];
+    // 1. Path sanity. resolveInside throws on traversal — capture as error,
+    //    don't let it propagate as a generic exception (the validator should
+    //    return a structured result for ANY input).
+    let normalizedPath = args.path.toLowerCase().endsWith(".md") ? args.path : `${args.path}.md`;
+    let absPath = null;
+    try {
+        absPath = vault.resolveInside(normalizedPath);
+        normalizedPath = vault.toRel(absPath);
+    }
+    catch (err) {
+        errors.push({
+            kind: "path-traversal",
+            message: err instanceof Error ? err.message : String(err)
+        });
+    }
+    // 2. YAML parse via gray-matter (the same parser used at write time).
+    const yamlReport = { parsed: false, error: null, keys: [] };
+    let bodyAfterFm = args.content;
+    try {
+        const parsed = matter(args.content);
+        yamlReport.parsed = true;
+        yamlReport.keys = Object.keys(parsed.data ?? {});
+        bodyAfterFm = parsed.content;
+    }
+    catch (err) {
+        yamlReport.error = err instanceof Error ? err.message : String(err);
+        errors.push({ kind: "yaml-invalid", message: `YAML frontmatter could not be parsed: ${yamlReport.error}` });
+    }
+    // 3. Wikilink resolution against the live vault.
+    const all = await vault.listMarkdown();
+    const wikilinkRe = /(?<!!)\[\[([^\]\n]+?)\]\]/g;
+    const wikilinks = [];
+    for (const m of bodyAfterFm.matchAll(wikilinkRe)) {
+        const raw = m[0];
+        const inner = (m[1] ?? "").trim();
+        if (!inner)
+            continue;
+        // Strip alias / section / block to get the bare target name.
+        const beforePipe = inner.split("|")[0] ?? "";
+        const beforeHash = beforePipe.split("#")[0] ?? "";
+        const target = beforeHash.split("^")[0]?.trim() ?? "";
+        if (!target)
+            continue;
+        const match = findBestMatch(all, target, normalizedPath);
+        if (match) {
+            wikilinks.push({
+                raw,
+                target,
+                status: "resolved",
+                resolved_path: match.relPath,
+                suggestions: []
+            });
+        }
+        else {
+            const suggestions = await suggestSimilar(vault, target);
+            wikilinks.push({
+                raw,
+                target,
+                status: "broken",
+                resolved_path: null,
+                suggestions
+            });
+            warnings.push({
+                kind: "broken-wikilink",
+                message: `[[${target}]] does not resolve to any existing note`,
+                suggestion: suggestions.length ? `Closest matches: ${suggestions.join(", ")}` : undefined
+            });
+        }
+    }
+    // 4. Tag pre-classification (existing vs new).
+    const existingTags = new Set((await listTags(vault, {})).map((t) => t.tag.toLowerCase()));
+    const proposedTagsRaw = new Set();
+    // Frontmatter tags.
+    const fmData = yamlReport.parsed ? matter(args.content).data : {};
+    const fmTags = fmData.tags ?? fmData.tag;
+    if (Array.isArray(fmTags)) {
+        for (const t of fmTags)
+            if (typeof t === "string" && t)
+                proposedTagsRaw.add(t.replace(/^#/, ""));
+    }
+    else if (typeof fmTags === "string" && fmTags) {
+        for (const t of fmTags.split(/[\s,]+/))
+            if (t)
+                proposedTagsRaw.add(t.replace(/^#/, ""));
+    }
+    // Inline tags.
+    const inlineTagRe = /(?:^|[\s([{>])#([\p{L}][\p{L}\p{N}_/-]*)/gu;
+    for (const m of bodyAfterFm.matchAll(inlineTagRe)) {
+        if (m[1])
+            proposedTagsRaw.add(m[1]);
+    }
+    const tags = [];
+    for (const t of proposedTagsRaw) {
+        const status = existingTags.has(t.toLowerCase()) ? "existing" : "new";
+        tags.push({ name: t, status });
+        if (status === "new") {
+            warnings.push({
+                kind: "new-tag",
+                message: `#${t} is new — won't fork an existing tag (case-insensitive check)`
+            });
+        }
+    }
+    // 5. Path collision check.
+    let collision = { kind: "none" };
+    if (absPath) {
+        try {
+            await vault.stat(absPath);
+            // Path exists.
+            if (mode === "create") {
+                errors.push({
+                    kind: "path-collision",
+                    message: `Note already exists at ${normalizedPath} (mode="create" refuses overwrite)`
+                });
+            }
+            collision = { kind: "path-exists", existing_path: normalizedPath };
+        }
+        catch {
+            // Path doesn't exist — try title collision (an existing note at a different path).
+            const titleFromBasename = stripMd(path.basename(normalizedPath));
+            const existing = await vault.findByTitle(titleFromBasename);
+            if (existing && existing.relPath !== normalizedPath) {
+                warnings.push({
+                    kind: "title-collision",
+                    message: `A note titled "${titleFromBasename}" already exists at ${existing.relPath} — proceeding will create a same-titled file at a different path`,
+                    suggestion: existing.relPath
+                });
+                collision = { kind: "title-exists-elsewhere", existing_path: existing.relPath };
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        proposed_path: normalizedPath,
+        mode,
+        errors,
+        warnings,
+        yaml: yamlReport,
+        wikilinks,
+        tags,
+        collision
+    };
+}
+export async function findSimilar(vault, args) {
+    await vault.ensureExists();
+    const limit = args.limit ?? 10;
+    const minScore = args.min_score ?? 0.05;
+    const target = await resolveTarget(vault, args);
+    const entries = await vault.listMarkdown();
+    const metas = new Map();
+    for (const e of entries) {
+        const { parsed } = await vault.readNote(e.absPath, e.mtimeMs);
+        const tags = new Set(parsed.tags.map((t) => t.toLowerCase()));
+        const title3grams = ngrams(stripMd(e.basename).toLowerCase(), 3);
+        const outbound = new Set();
+        for (const link of parsed.wikilinks) {
+            const m = findBestMatch(entries, link.target, e.relPath);
+            if (m)
+                outbound.add(m.relPath);
+        }
+        metas.set(e.relPath, { entry: e, tags, title3grams, outbound });
+    }
+    const targetMeta = metas.get(target.relPath);
+    if (!targetMeta) {
+        // The target was found by resolveTarget but may have been excluded from
+        // listMarkdown by --exclude-glob. Treat as zero results rather than crash.
+        return [];
+    }
+    // For co-backlink: build "who links to X?" for everyone we care about
+    // (target + all candidates). Single pass over outbound sets.
+    const inboundFor = new Map();
+    for (const [from, m] of metas) {
+        for (const to of m.outbound) {
+            const set = inboundFor.get(to) ?? new Set();
+            set.add(from);
+            inboundFor.set(to, set);
+        }
+    }
+    const targetInbound = inboundFor.get(target.relPath) ?? new Set();
+    const out = [];
+    for (const [relPath, m] of metas) {
+        if (relPath === target.relPath)
+            continue;
+        const tagJ = jaccard(targetMeta.tags, m.tags);
+        const titleJ = jaccard(targetMeta.title3grams, m.title3grams);
+        const candInbound = inboundFor.get(relPath) ?? new Set();
+        // shared_outbound: how much of A's outbound is also in B's
+        const sharedOut = targetMeta.outbound.size === 0 ? 0 : intersectionSize(targetMeta.outbound, m.outbound) / targetMeta.outbound.size;
+        // co_backlink: how many notes link to both target and candidate, over union
+        const coBack = jaccard(targetInbound, candInbound);
+        const score = 3.0 * tagJ + 1.5 * titleJ + 2.0 * sharedOut + 2.0 * coBack;
+        if (score < minScore)
+            continue;
+        const shared = [];
+        for (const t of targetMeta.tags)
+            if (m.tags.has(t))
+                shared.push(t);
+        shared.sort();
+        out.push({
+            path: m.entry.relPath,
+            title: stripMd(m.entry.basename),
+            score: Math.round(score * 10000) / 10000,
+            signals: {
+                tag_jaccard: Math.round(tagJ * 10000) / 10000,
+                title_3gram: Math.round(titleJ * 10000) / 10000,
+                shared_outbound: Math.round(sharedOut * 10000) / 10000,
+                co_backlink: Math.round(coBack * 10000) / 10000
+            },
+            shared_tags: shared,
+            mtime: new Date(m.entry.mtimeMs).toISOString()
+        });
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out.slice(0, limit);
+}
+export async function getNoteNeighbors(vault, args) {
+    await vault.ensureExists();
+    const cap = args.max_per_bucket ?? 20;
+    const target = await resolveTarget(vault, args);
+    const entries = await vault.listMarkdown();
+    const { parsed: targetParsed } = await vault.readNote(target.absPath, target.mtimeMs);
+    const targetTagsLower = new Set(targetParsed.tags.map((t) => t.toLowerCase()));
+    // Outbound: resolved unique destinations from the target.
+    const seenOut = new Set();
+    const outbound = [];
+    for (const link of targetParsed.wikilinks) {
+        const m = findBestMatch(entries, link.target, target.relPath);
+        if (!m || seenOut.has(m.relPath))
+            continue;
+        seenOut.add(m.relPath);
+        const { parsed: nbrParsed } = await vault.readNote(m.absPath, m.mtimeMs);
+        outbound.push({ path: m.relPath, title: stripMd(m.basename), tags: nbrParsed.tags });
+        if (outbound.length >= cap)
+            break;
+    }
+    // Inbound: notes that link to target, with backlink count.
+    const inboundCounts = new Map();
+    for (const e of entries) {
+        if (e.absPath === target.absPath)
+            continue;
+        const { parsed } = await vault.readNote(e.absPath, e.mtimeMs);
+        let cnt = 0;
+        for (const link of parsed.wikilinks) {
+            const m = findBestMatch(entries, link.target, e.relPath);
+            if (m && m.absPath === target.absPath)
+                cnt += 1;
+        }
+        if (cnt > 0)
+            inboundCounts.set(e.relPath, { entry: e, count: cnt, tags: parsed.tags });
+    }
+    const inbound = [...inboundCounts.values()]
+        .sort((a, b) => b.count - a.count)
+        .slice(0, cap)
+        .map((x) => ({ path: x.entry.relPath, title: stripMd(x.entry.basename), tags: x.tags, count: x.count }));
+    // Tag siblings: notes sharing ≥1 tag with target, excluding outbound/inbound.
+    const tag_siblings = [];
+    if (targetTagsLower.size > 0) {
+        const exclude = new Set([target.relPath, ...seenOut, ...inboundCounts.keys()]);
+        const candidates = [];
+        for (const e of entries) {
+            if (exclude.has(e.relPath))
+                continue;
+            const { parsed } = await vault.readNote(e.absPath, e.mtimeMs);
+            const shared = [];
+            for (const t of parsed.tags) {
+                if (targetTagsLower.has(t.toLowerCase()))
+                    shared.push(t);
+            }
+            if (shared.length > 0) {
+                candidates.push({ path: e.relPath, title: stripMd(e.basename), shared });
+            }
+        }
+        candidates.sort((a, b) => b.shared.length - a.shared.length);
+        for (const c of candidates.slice(0, cap)) {
+            tag_siblings.push({ path: c.path, title: c.title, shared_tags: c.shared });
+        }
+    }
+    return {
+        center: {
+            path: target.relPath,
+            title: stripMd(target.basename),
+            tags: targetParsed.tags,
+            mtime: new Date(target.mtimeMs).toISOString()
+        },
+        outbound,
+        inbound,
+        tag_siblings
+    };
+}
+export async function getVaultStats(vault, args) {
+    await vault.ensureExists();
+    const topTagsLimit = args.top_tags ?? 10;
+    const entries = await vault.listMarkdown();
+    const sevenDaysMs = Date.now() - 7 * 24 * 3600 * 1000;
+    let totalSize = 0;
+    let totalWords = 0;
+    let recent = 0;
+    let withFm = 0;
+    const tagCounts = new Map();
+    // Build inbound map in one pass so orphans and broken counts are O(N).
+    const inbound = new Map();
+    let broken = 0;
+    let outboundTotal = 0;
+    for (const e of entries) {
+        const { content, parsed } = await vault.readNote(e.absPath, e.mtimeMs);
+        totalSize += Buffer.byteLength(content, "utf8");
+        totalWords += content.trim() ? content.trim().split(/\s+/).length : 0;
+        if (e.mtimeMs >= sevenDaysMs)
+            recent += 1;
+        if (Object.keys(parsed.frontmatter).length > 0)
+            withFm += 1;
+        for (const t of parsed.tags) {
+            const key = t.toLowerCase();
+            tagCounts.set(key, (tagCounts.get(key) ?? 0) + 1);
+        }
+        for (const link of parsed.wikilinks) {
+            outboundTotal += 1;
+            const m = findBestMatch(entries, link.target, e.relPath);
+            if (!m) {
+                broken += 1;
+                continue;
+            }
+            inbound.set(m.relPath, (inbound.get(m.relPath) ?? 0) + 1);
+        }
+    }
+    // Orphan = no inbound AND no outbound. Need outbound-presence per file.
+    const outboundPresence = new Set();
+    for (const e of entries) {
+        const { parsed } = await vault.readNote(e.absPath, e.mtimeMs);
+        if (parsed.wikilinks.length > 0)
+            outboundPresence.add(e.relPath);
+    }
+    let orphans = 0;
+    for (const e of entries) {
+        if (!inbound.get(e.relPath) && !outboundPresence.has(e.relPath))
+            orphans += 1;
+    }
+    const top_tags = [...tagCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, topTagsLimit)
+        .map(([tag, count]) => ({ tag, count }));
+    // Sanity: outboundTotal isn't returned directly but is used to validate that
+    // the orphan/broken pass saw at least one link if any exist.
+    if (outboundTotal === 0 && broken !== 0)
+        broken = 0; // defensive — never reachable.
+    return {
+        total_notes: entries.length,
+        total_size_bytes: totalSize,
+        avg_note_words: entries.length === 0 ? 0 : Math.round(totalWords / entries.length),
+        recently_modified_7d: recent,
+        orphans,
+        broken_wikilinks: broken,
+        total_tags: tagCounts.size,
+        top_tags,
+        notes_with_frontmatter: withFm,
+        generated_at: new Date().toISOString()
+    };
+}
+// ─── small set / string helpers shared by find_similar / get_note_neighbors ─
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter += 1;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+function intersectionSize(a, b) {
+    let n = 0;
+    for (const x of a)
+        if (b.has(x))
+            n += 1;
+    return n;
+}
+function ngrams(s, n) {
+    const out = new Set();
+    if (s.length < n) {
+        if (s)
+            out.add(s);
+        return out;
+    }
+    for (let i = 0; i <= s.length - n; i++)
+        out.add(s.slice(i, i + n));
+    return out;
+}
 function findBestMatch(entries, target, fromNote) {
     if (target.startsWith("./") || target.startsWith("../") || target.includes("/../")) {
         if (fromNote) {