@tomingtoming/kioq 0.7.0

package/dist/noteStore.js

@@ -0,0 +1,1115 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const IGNORED_DIRS = new Set([".git", "node_modules", ".obsidian"]);
+const MARKDOWN_EXTENSION = ".md";
+function nowDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+function stripQuotes(value) {
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function sanitizeRelativePath(value) {
+    if (!value) {
+        return "";
+    }
+    const normalized = value
+        .replace(/\\/g, "/")
+        .split("/")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .join("/");
+    if (normalized.length === 0) {
+        return "";
+    }
+    const segments = normalized.split("/");
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`invalid relative path: ${value}`);
+    }
+    return segments.join("/");
+}
+function sanitizeFileBase(title) {
+    const trimmed = title.trim();
+    const replaced = trimmed
+        .replace(/[\\/:*?"<>|]/g, "-")
+        .replace(/\s+/g, " ")
+        .replace(/^\.+/, "")
+        .replace(/\.+$/, "")
+        .trim();
+    if (replaced.length === 0) {
+        return "untitled";
+    }
+    return replaced;
+}
+function inferTitleFromIdentifier(identifier) {
+    const trimmed = identifier.trim();
+    if (trimmed.length === 0) {
+        return "untitled";
+    }
+    const normalized = trimmed.replace(/\\/g, "/");
+    const last = normalized.split("/").filter((part) => part.length > 0).pop() ?? normalized;
+    const withoutExtension = last.replace(/\.md$/i, "").trim();
+    return withoutExtension.length > 0 ? withoutExtension : "untitled";
+}
+function isInsideDirectory(baseDir, targetPath) {
+    const normalizedBase = path.resolve(baseDir);
+    const normalizedTarget = path.resolve(targetPath);
+    return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}${path.sep}`);
+}
+function parseFrontmatterBlock(block) {
+    const result = {};
+    const lines = block.split(/\r?\n/);
+    let currentArrayKey;
+    for (const line of lines) {
+        const listMatch = line.match(/^\s*-\s*(.+)$/);
+        if (listMatch && currentArrayKey) {
+            const current = result[currentArrayKey];
+            if (Array.isArray(current)) {
+                current.push(stripQuotes(listMatch[1].trim()));
+            }
+            continue;
+        }
+        currentArrayKey = undefined;
+        const keyValueMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!keyValueMatch) {
+            continue;
+        }
+        const key = keyValueMatch[1];
+        const rawValue = keyValueMatch[2].trim();
+        if (rawValue.length === 0) {
+            result[key] = [];
+            currentArrayKey = key;
+            continue;
+        }
+        if (rawValue.startsWith("[") && rawValue.endsWith("]")) {
+            const inner = rawValue.slice(1, -1).trim();
+            result[key] = inner.length === 0
+                ? []
+                : inner.split(",").map((item) => stripQuotes(item.trim())).filter((item) => item.length > 0);
+            continue;
+        }
+        result[key] = stripQuotes(rawValue);
+    }
+    return result;
+}
+function splitFrontmatter(raw) {
+    if (!raw.startsWith("---\n")) {
+        return { frontmatter: {}, body: raw };
+    }
+    const separatorIndex = raw.indexOf("\n---\n", 4);
+    if (separatorIndex < 0) {
+        return { frontmatter: {}, body: raw };
+    }
+    const block = raw.slice(4, separatorIndex);
+    const body = raw.slice(separatorIndex + 5);
+    return {
+        frontmatter: parseFrontmatterBlock(block),
+        body,
+    };
+}
+function formatFrontmatterValue(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return "[]";
+        }
+        return `\n${value.map((item) => `- ${JSON.stringify(item)}`).join("\n")}`;
+    }
+    if (/^[A-Za-z0-9_./:-]+$/.test(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function buildFrontmatter(frontmatter) {
+    const preferredOrder = ["title", "type", "permalink", "tags", "created", "updated"];
+    const orderedKeys = [
+        ...preferredOrder.filter((key) => key in frontmatter),
+        ...Object.keys(frontmatter).filter((key) => !preferredOrder.includes(key)),
+    ];
+    const lines = orderedKeys.map((key) => `${key}: ${formatFrontmatterValue(frontmatter[key])}`);
+    return `---\n${lines.join("\n")}\n---`;
+}
+function ensureTrailingNewline(text) {
+    return text.endsWith("\n") ? text : `${text}\n`;
+}
+function normalizeContent(text) {
+    return text.replace(/\r\n/g, "\n");
+}
+function normalizeLookup(value) {
+    return value.toLowerCase().replace(/[\s._/-]+/g, "");
+}
+function safeString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function safeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function countOccurrences(text, query) {
+    if (!query || !text) {
+        return 0;
+    }
+    let count = 0;
+    let index = 0;
+    while (true) {
+        const foundIndex = text.indexOf(query, index);
+        if (foundIndex < 0) {
+            return count;
+        }
+        count += 1;
+        index = foundIndex + query.length;
+    }
+}
+function identifierMatchScore(key, query) {
+    const keyLower = key.toLowerCase();
+    const queryLower = query.toLowerCase();
+    if (!keyLower || !queryLower) {
+        return 0;
+    }
+    if (keyLower === queryLower) {
+        return 1000;
+    }
+    const keyNormalized = normalizeLookup(keyLower);
+    const queryNormalized = normalizeLookup(queryLower);
+    if (keyNormalized.length > 0 && keyNormalized === queryNormalized) {
+        return 900;
+    }
+    if (keyLower.includes(queryLower)) {
+        return Math.max(400, 700 - Math.max(0, keyLower.length - queryLower.length));
+    }
+    if (queryLower.includes(keyLower) && keyLower.length >= 4) {
+        return Math.max(250, 420 - Math.max(0, queryLower.length - keyLower.length));
+    }
+    if (queryNormalized.length > 0 && keyNormalized.includes(queryNormalized)) {
+        return Math.max(220, 520 - Math.max(0, keyNormalized.length - queryNormalized.length));
+    }
+    if (keyNormalized.length >= 4 && queryNormalized.includes(keyNormalized)) {
+        return Math.max(140, 320 - Math.max(0, queryNormalized.length - keyNormalized.length));
+    }
+    return 0;
+}
+function splitWikiTarget(targetRaw) {
+    const trimmed = targetRaw.trim();
+    if (trimmed.length === 0) {
+        return { base: "", suffix: "" };
+    }
+    const hashIndex = trimmed.indexOf("#");
+    const blockIndex = trimmed.indexOf("^");
+    let splitIndex = -1;
+    if (hashIndex >= 0 && blockIndex >= 0) {
+        splitIndex = Math.min(hashIndex, blockIndex);
+    }
+    else if (hashIndex >= 0) {
+        splitIndex = hashIndex;
+    }
+    else if (blockIndex >= 0) {
+        splitIndex = blockIndex;
+    }
+    if (splitIndex < 0) {
+        return { base: trimmed, suffix: "" };
+    }
+    return {
+        base: trimmed.slice(0, splitIndex).trim(),
+        suffix: trimmed.slice(splitIndex),
+    };
+}
+function extractWikiLinks(text) {
+    const pattern = /\[\[([^\]\n]+)\]\]/g;
+    const tokens = [];
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+        const raw = match[0];
+        const inner = match[1].trim();
+        const pipeIndex = inner.indexOf("|");
+        const targetRaw = (pipeIndex >= 0 ? inner.slice(0, pipeIndex) : inner).trim();
+        const alias = pipeIndex >= 0 ? inner.slice(pipeIndex + 1) : undefined;
+        const { base, suffix } = splitWikiTarget(targetRaw);
+        tokens.push({
+            raw,
+            inner,
+            targetRaw,
+            targetBase: base,
+            suffix,
+            alias,
+            start: match.index,
+            end: match.index + raw.length,
+        });
+    }
+    return tokens;
+}
+function renderWikiLink(targetBase, suffix, alias) {
+    const target = `${targetBase}${suffix}`;
+    if (alias === undefined) {
+        return `[[${target}]]`;
+    }
+    return `[[${target}|${alias}]]`;
+}
+function rewriteWikiLinks(text, replacer) {
+    const tokens = extractWikiLinks(text);
+    if (tokens.length === 0) {
+        return { text, replaced: 0 };
+    }
+    let out = "";
+    let replaced = 0;
+    let lastIndex = 0;
+    for (const token of tokens) {
+        out += text.slice(lastIndex, token.start);
+        const next = replacer(token);
+        if (next !== undefined && next !== token.raw) {
+            out += next;
+            replaced += 1;
+        }
+        else {
+            out += token.raw;
+        }
+        lastIndex = token.end;
+    }
+    out += text.slice(lastIndex);
+    return { text: out, replaced };
+}
+function uniqueByFilePath(notes) {
+    const seen = new Set();
+    const unique = [];
+    for (const note of notes) {
+        if (seen.has(note.filePath)) {
+            continue;
+        }
+        seen.add(note.filePath);
+        unique.push(note);
+    }
+    return unique;
+}
+function fileExistsSafe(filePath) {
+    return fs
+        .stat(filePath)
+        .then((stat) => stat.isFile())
+        .catch(() => false);
+}
+export class LocalNoteStore {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    projectRoot(name) {
+        return this.config.projectPaths[name] ?? path.resolve(this.config.projectRoot, name);
+    }
+    isProjectReadonly(name) {
+        return this.config.readonlyProjects.includes(name);
+    }
+    ensureProjectWritable(name) {
+        if (this.isProjectReadonly(name)) {
+            throw new Error(`project is read-only: ${name}`);
+        }
+    }
+    async projectExists(root) {
+        try {
+            const stat = await fs.stat(root);
+            return stat.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    identifierKeys(note) {
+        const relativeNoExt = note.relativePath.endsWith(MARKDOWN_EXTENSION)
+            ? note.relativePath.slice(0, -MARKDOWN_EXTENSION.length)
+            : note.relativePath;
+        return [
+            note.title,
+            note.permalink,
+            note.relativePath,
+            relativeNoExt,
+            path.basename(note.filePath, MARKDOWN_EXTENSION),
+        ];
+    }
+    candidateKeysFromTarget(targetBase) {
+        const trimmed = targetBase.trim();
+        if (trimmed.length === 0) {
+            return [];
+        }
+        const normalizedPath = trimmed.replace(/\\/g, "/").replace(/^\.\//, "");
+        const withoutExtension = normalizedPath.endsWith(MARKDOWN_EXTENSION)
+            ? normalizedPath.slice(0, -MARKDOWN_EXTENSION.length)
+            : normalizedPath;
+        const baseNoExt = path.posix.basename(withoutExtension);
+        const baseWithExt = path.posix.basename(normalizedPath);
+        return Array.from(new Set([normalizedPath, withoutExtension, baseNoExt, baseWithExt].filter((key) => key.length > 0)));
+    }
+    addToLookup(map, key, note) {
+        const normalizedKey = key.trim();
+        if (normalizedKey.length === 0) {
+            return;
+        }
+        const current = map.get(normalizedKey) ?? [];
+        if (!current.some((item) => item.filePath === note.filePath)) {
+            current.push(note);
+            map.set(normalizedKey, current);
+        }
+    }
+    buildLookup(notes) {
+        const exact = new Map();
+        const normalized = new Map();
+        for (const note of notes) {
+            const keys = this.identifierKeys(note);
+            for (const key of keys) {
+                this.addToLookup(exact, key.toLowerCase(), note);
+                this.addToLookup(normalized, normalizeLookup(key), note);
+            }
+        }
+        return { exact, normalized };
+    }
+    resolveWikiTarget(targetBase, lookup) {
+        const keys = this.candidateKeysFromTarget(targetBase);
+        if (keys.length === 0) {
+            return { status: "unresolved", reason: "empty_target" };
+        }
+        const exactCandidates = [];
+        for (const key of keys) {
+            exactCandidates.push(...(lookup.exact.get(key.toLowerCase()) ?? []));
+        }
+        const uniqueExact = uniqueByFilePath(exactCandidates);
+        if (uniqueExact.length === 1) {
+            return { status: "resolved", note: uniqueExact[0] };
+        }
+        if (uniqueExact.length > 1) {
+            return { status: "ambiguous", reason: "multiple_exact_matches" };
+        }
+        const normalizedCandidates = [];
+        for (const key of keys) {
+            normalizedCandidates.push(...(lookup.normalized.get(normalizeLookup(key)) ?? []));
+        }
+        const uniqueNormalized = uniqueByFilePath(normalizedCandidates);
+        if (uniqueNormalized.length === 1) {
+            return { status: "resolved", note: uniqueNormalized[0] };
+        }
+        if (uniqueNormalized.length > 1) {
+            return { status: "ambiguous", reason: "multiple_normalized_matches" };
+        }
+        return { status: "unresolved", reason: "target_not_found" };
+    }
+    resolveWikiLinksForText(text, lookup) {
+        const tokens = extractWikiLinks(text);
+        return tokens.map((token) => {
+            const resolved = this.resolveWikiTarget(token.targetBase, lookup);
+            if (resolved.status === "resolved" && resolved.note) {
+                return {
+                    raw: token.raw,
+                    target: token.targetBase,
+                    resolved: true,
+                    resolvedTitle: resolved.note.title,
+                    resolvedPermalink: resolved.note.permalink,
+                    resolvedFilePath: resolved.note.relativePath,
+                };
+            }
+            return {
+                raw: token.raw,
+                target: token.targetBase,
+                resolved: false,
+                reason: resolved.reason ?? resolved.status,
+            };
+        });
+    }
+    linkHealthFromResolutions(resolutions) {
+        const total = resolutions.length;
+        const unresolved = resolutions.filter((item) => !item.resolved).length;
+        return {
+            total,
+            resolved: total - unresolved,
+            unresolved,
+        };
+    }
+    unresolvedTargetsFromResolutions(resolutions) {
+        const unresolved = new Set();
+        for (const item of resolutions) {
+            if (!item.resolved) {
+                unresolved.add(item.target || item.raw);
+            }
+        }
+        return Array.from(unresolved.values()).sort((left, right) => left.localeCompare(right, "ja"));
+    }
+    linkSuggestionsForTarget(target, notes, limit) {
+        const candidates = [];
+        for (const note of notes) {
+            let score = 0;
+            for (const key of this.identifierKeys(note)) {
+                score = Math.max(score, identifierMatchScore(key, target));
+            }
+            if (score <= 0) {
+                continue;
+            }
+            candidates.push({
+                note,
+                score,
+            });
+        }
+        candidates.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            if (right.note.updated !== left.note.updated) {
+                return right.note.updated.localeCompare(left.note.updated);
+            }
+            return left.note.title.localeCompare(right.note.title, "ja");
+        });
+        return candidates.slice(0, limit).map((item) => ({
+            title: item.note.title,
+            permalink: item.note.permalink,
+            filePath: item.note.relativePath,
+            score: item.score,
+        }));
+    }
+    unresolvedHintsFromResolutions(resolutions, notes) {
+        return this.unresolvedTargetsFromResolutions(resolutions).map((target) => ({
+            target,
+            suggestions: this.linkSuggestionsForTarget(target, notes, 3),
+        }));
+    }
+    duplicateWarningsForNote(note, notes) {
+        const byTitle = notes.filter((item) => item.filePath !== note.filePath && item.title === note.title);
+        const byPermalink = notes.filter((item) => item.filePath !== note.filePath && item.permalink === note.permalink);
+        const warnings = [];
+        if (byTitle.length > 0) {
+            warnings.push({
+                kind: "title",
+                value: note.title,
+                count: byTitle.length,
+                examples: byTitle.slice(0, 3).map((item) => `${item.title} (${item.relativePath})`),
+            });
+        }
+        if (byPermalink.length > 0) {
+            warnings.push({
+                kind: "permalink",
+                value: note.permalink,
+                count: byPermalink.length,
+                examples: byPermalink.slice(0, 3).map((item) => `${item.title} (${item.relativePath})`),
+            });
+        }
+        return warnings;
+    }
+    backlinkCountForTarget(target, notes, lookup) {
+        let count = 0;
+        for (const source of notes) {
+            if (source.filePath === target.filePath) {
+                continue;
+            }
+            const links = this.resolveWikiLinksForText(source.body, lookup);
+            count += links.filter((link) => link.resolved && link.resolvedFilePath === target.relativePath).length;
+        }
+        return count;
+    }
+    qualitySignalsForNote(note, notes) {
+        const lookup = this.buildLookup(notes);
+        const resolutions = this.resolveWikiLinksForText(note.body, lookup);
+        const linkHealth = this.linkHealthFromResolutions(resolutions);
+        const unresolvedWikiLinks = this.unresolvedTargetsFromResolutions(resolutions);
+        const unresolvedLinkHints = this.unresolvedHintsFromResolutions(resolutions, notes);
+        const duplicateWarnings = this.duplicateWarningsForNote(note, notes);
+        const backlinkCount = this.backlinkCountForTarget(note, notes, lookup);
+        const orphanWarning = backlinkCount === 0 && linkHealth.resolved === 0;
+        return {
+            linkHealth,
+            unresolvedWikiLinks,
+            unresolvedLinkHints,
+            duplicateWarnings,
+            backlinkCount,
+            orphanWarning,
+        };
+    }
+    projectLinkHealth(notes) {
+        const lookup = this.buildLookup(notes);
+        let total = 0;
+        let resolved = 0;
+        for (const note of notes) {
+            const health = this.linkHealthFromResolutions(this.resolveWikiLinksForText(note.body, lookup));
+            total += health.total;
+            resolved += health.resolved;
+        }
+        return {
+            total,
+            resolved,
+            unresolved: total - resolved,
+        };
+    }
+    async loadProjectNotes(projectRoot) {
+        const files = await this.listMarkdownFiles(projectRoot);
+        return Promise.all(files.map((filePath) => this.loadNote(filePath, projectRoot)));
+    }
+    async listProjectsDetailed() {
+        const byName = new Map();
+        for (const [name, root] of Object.entries(this.config.projectPaths)) {
+            byName.set(name, {
+                name,
+                root,
+                exists: await this.projectExists(root),
+                readonly: this.isProjectReadonly(name),
+            });
+        }
+        try {
+            const entries = await fs.readdir(this.config.projectRoot, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name.startsWith(".")) {
+                    continue;
+                }
+                if (byName.has(entry.name)) {
+                    continue;
+                }
+                const root = this.projectRoot(entry.name);
+                byName.set(entry.name, {
+                    name: entry.name,
+                    root,
+                    exists: true,
+                    readonly: this.isProjectReadonly(entry.name),
+                });
+            }
+        }
+        catch {
+            // project root can be absent; explicit project paths are still valid
+        }
+        const projects = Array.from(byName.values());
+        projects.sort((left, right) => left.name.localeCompare(right.name, "ja"));
+        return projects;
+    }
+    async listProjects() {
+        const projects = await this.listProjectsDetailed();
+        return projects.map((project) => project.name);
+    }
+    async resolveProjectName(project) {
+        const requested = project?.trim();
+        if (requested && requested.length > 0) {
+            return requested;
+        }
+        if (this.config.defaultProject && this.config.defaultProject.trim().length > 0) {
+            return this.config.defaultProject;
+        }
+        const names = await this.listProjects();
+        if (names.length === 1) {
+            return names[0];
+        }
+        throw new Error("project is required. set project, KIOQ_DEFAULT_PROJECT, or keep only one project.");
+    }
+    async resolveProjectRoot(project, createIfMissing) {
+        const name = await this.resolveProjectName(project);
+        const root = this.projectRoot(name);
+        if (createIfMissing) {
+            this.ensureProjectWritable(name);
+            await fs.mkdir(root, { recursive: true });
+            return { name, root };
+        }
+        if (!(await this.projectExists(root))) {
+            throw new Error(`project not found: ${name} (${root})`);
+        }
+        return { name, root };
+    }
+    async listMarkdownFiles(projectRoot) {
+        const files = [];
+        const queue = [projectRoot];
+        while (queue.length > 0) {
+            const currentDir = queue.pop();
+            if (!currentDir) {
+                continue;
+            }
+            const entries = await fs.readdir(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const entryPath = path.join(currentDir, entry.name);
+                if (entry.isDirectory()) {
+                    if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+                        continue;
+                    }
+                    queue.push(entryPath);
+                    continue;
+                }
+                if (entry.isFile() && entry.name.endsWith(MARKDOWN_EXTENSION)) {
+                    files.push(entryPath);
+                }
+            }
+        }
+        return files;
+    }
+    async loadNote(filePath, projectRoot) {
+        const raw = await fs.readFile(filePath, "utf8");
+        const stat = await fs.stat(filePath);
+        const { frontmatter, body } = splitFrontmatter(raw);
+        const relativePath = toPosix(path.relative(projectRoot, filePath));
+        const title = safeString(frontmatter.title) ?? path.basename(filePath, MARKDOWN_EXTENSION);
+        const created = safeString(frontmatter.created) ?? stat.birthtime.toISOString().slice(0, 10);
+        const updated = safeString(frontmatter.updated) ?? stat.mtime.toISOString().slice(0, 10);
+        const defaultPermalink = relativePath.endsWith(MARKDOWN_EXTENSION)
+            ? relativePath.slice(0, -MARKDOWN_EXTENSION.length)
+            : relativePath;
+        const permalink = safeString(frontmatter.permalink) ?? defaultPermalink;
+        return {
+            title,
+            permalink,
+            filePath,
+            relativePath,
+            frontmatter,
+            body,
+            raw,
+            created,
+            updated,
+        };
+    }
+    async resolveIdentifier(projectRoot, identifier) {
+        const trimmed = identifier.trim();
+        if (trimmed.length === 0) {
+            return undefined;
+        }
+        const pathCandidates = [trimmed, trimmed.endsWith(MARKDOWN_EXTENSION) ? undefined : `${trimmed}${MARKDOWN_EXTENSION}`]
+            .filter((candidate) => Boolean(candidate))
+            .map((candidate) => sanitizeRelativePath(candidate));
+        for (const candidate of pathCandidates) {
+            const absolutePath = path.resolve(projectRoot, candidate);
+            if (!isInsideDirectory(projectRoot, absolutePath)) {
+                continue;
+            }
+            try {
+                const stat = await fs.stat(absolutePath);
+                if (stat.isFile()) {
+                    return await this.loadNote(absolutePath, projectRoot);
+                }
+            }
+            catch {
+                // continue
+            }
+        }
+        const notes = await this.loadProjectNotes(projectRoot);
+        const normalizedInput = trimmed.toLowerCase();
+        const fuzzyMatches = [];
+        for (const note of notes) {
+            const keys = this.identifierKeys(note);
+            if (keys.some((key) => key.toLowerCase() === normalizedInput)) {
+                return note;
+            }
+            let bestScore = 0;
+            for (const key of keys) {
+                bestScore = Math.max(bestScore, identifierMatchScore(key, trimmed));
+            }
+            if (bestScore > 0) {
+                fuzzyMatches.push({ note, score: bestScore });
+            }
+        }
+        if (fuzzyMatches.length === 0) {
+            return undefined;
+        }
+        fuzzyMatches.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return right.note.updated.localeCompare(left.note.updated);
+        });
+        if (fuzzyMatches.length === 1) {
+            return fuzzyMatches[0].note;
+        }
+        if (fuzzyMatches[0].score >= fuzzyMatches[1].score + 20) {
+            return fuzzyMatches[0].note;
+        }
+        return undefined;
+    }
+    noteScore(note, query) {
+        const loweredQueryTerms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .map((term) => term.trim())
+            .filter((term) => term.length > 0);
+        if (loweredQueryTerms.length === 0) {
+            return 0;
+        }
+        const title = note.title.toLowerCase();
+        const permalink = note.permalink.toLowerCase();
+        const body = note.body.toLowerCase();
+        let score = 0;
+        for (const term of loweredQueryTerms) {
+            score += countOccurrences(title, term) * 20;
+            score += countOccurrences(permalink, term) * 10;
+            score += countOccurrences(body, term);
+        }
+        return score;
+    }
+    async searchNotes(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, false);
+        const notes = await this.loadProjectNotes(root);
+        const results = [];
+        for (const note of notes) {
+            if (args.afterDate && note.updated < args.afterDate) {
+                continue;
+            }
+            const score = this.noteScore(note, args.query);
+            if (score <= 0) {
+                continue;
+            }
+            results.push({
+                title: note.title,
+                permalink: note.permalink,
+                filePath: note.relativePath,
+                content: note.body,
+                score,
+                updated: note.updated,
+            });
+        }
+        results.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return right.updated.localeCompare(left.updated);
+        });
+        return {
+            project,
+            results: results.slice(0, args.limit),
+        };
+    }
+    async recentNotes(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, false);
+        const notes = await this.loadProjectNotes(root);
+        const directoryPrefix = sanitizeRelativePath(args.directory);
+        const results = [];
+        for (const note of notes) {
+            if (directoryPrefix.length > 0) {
+                const matchPrefix = `${directoryPrefix}/`;
+                if (!note.relativePath.startsWith(matchPrefix)) {
+                    continue;
+                }
+            }
+            results.push({
+                title: note.title,
+                permalink: note.permalink,
+                filePath: note.relativePath,
+                updated: note.updated,
+            });
+        }
+        results.sort((left, right) => right.updated.localeCompare(left.updated));
+        return {
+            project,
+            results: results.slice(0, args.limit),
+        };
+    }
+    async suggestNotes(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, false);
+        const query = args.query.trim();
+        if (query.length === 0) {
+            return { project, results: [] };
+        }
+        const notes = await this.loadProjectNotes(root);
+        const results = [];
+        for (const note of notes) {
+            let keyScore = 0;
+            for (const key of this.identifierKeys(note)) {
+                keyScore = Math.max(keyScore, identifierMatchScore(key, query));
+            }
+            const bodyScore = this.noteScore(note, query);
+            const score = keyScore + bodyScore;
+            if (score <= 0) {
+                continue;
+            }
+            results.push({
+                title: note.title,
+                permalink: note.permalink,
+                filePath: note.relativePath,
+                content: note.body,
+                score,
+                updated: note.updated,
+            });
+        }
+        results.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return right.updated.localeCompare(left.updated);
+        });
+        return {
+            project,
+            results: results.slice(0, args.limit),
+        };
+    }
+    async readNote(identifier, project) {
+        const { name, root } = await this.resolveProjectRoot(project, false);
+        const note = await this.resolveIdentifier(root, identifier);
+        if (!note) {
+            throw new Error(`note not found: ${identifier}`);
+        }
+        const notes = await this.loadProjectNotes(root);
+        const currentNote = notes.find((item) => item.filePath === note.filePath) ?? note;
+        const signals = this.qualitySignalsForNote(currentNote, notes);
+        return {
+            project: name,
+            note: currentNote,
+            linkHealth: signals.linkHealth,
+            unresolvedWikiLinks: signals.unresolvedWikiLinks,
+            unresolvedLinkHints: signals.unresolvedLinkHints,
+            backlinkCount: signals.backlinkCount,
+            orphanWarning: signals.orphanWarning,
+        };
+    }
+    async resolveLinks(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, false);
+        const note = await this.resolveIdentifier(root, args.identifier);
+        if (!note) {
+            throw new Error(`note not found: ${args.identifier}`);
+        }
+        const notes = await this.loadProjectNotes(root);
+        const lookup = this.buildLookup(notes);
+        const links = this.resolveWikiLinksForText(note.body, lookup);
+        return {
+            project,
+            note,
+            links,
+        };
+    }
+    async listBacklinks(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, false);
+        const target = await this.resolveIdentifier(root, args.identifier);
+        if (!target) {
+            throw new Error(`note not found: ${args.identifier}`);
+        }
+        const notes = await this.loadProjectNotes(root);
+        const lookup = this.buildLookup(notes);
+        const backlinks = [];
+        for (const source of notes) {
+            const links = this.resolveWikiLinksForText(source.body, lookup);
+            const matches = links.filter((link) => link.resolved && link.resolvedFilePath === target.relativePath);
+            if (matches.length === 0) {
+                continue;
+            }
+            backlinks.push({
+                title: source.title,
+                permalink: source.permalink,
+                filePath: source.relativePath,
+                updated: source.updated,
+                count: matches.length,
+                examples: matches.slice(0, 3).map((item) => item.raw),
+            });
+        }
+        backlinks.sort((left, right) => {
+            if (right.count !== left.count) {
+                return right.count - left.count;
+            }
+            return right.updated.localeCompare(left.updated);
+        });
+        return {
+            project,
+            target,
+            backlinks: backlinks.slice(0, args.limit),
+        };
+    }
+    async writeNote(input) {
+        const { name: project, root } = await this.resolveProjectRoot(input.project, true);
+        this.ensureProjectWritable(project);
+        const directory = sanitizeRelativePath(input.directory ?? this.config.defaultDirectory);
+        const fileBase = sanitizeFileBase(input.title);
+        const fileName = `${fileBase}${MARKDOWN_EXTENSION}`;
+        const targetPath = path.resolve(root, directory, fileName);
+        if (!isInsideDirectory(root, targetPath)) {
+            throw new Error("invalid target path");
+        }
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        let operation = "created";
+        let existingFrontmatter = {};
+        try {
+            const current = await this.loadNote(targetPath, root);
+            existingFrontmatter = current.frontmatter;
+            operation = "updated";
+        }
+        catch {
+            // create new file
+        }
+        const date = nowDate();
+        const relativePath = toPosix(path.relative(root, targetPath));
+        const permalink = safeString(existingFrontmatter.permalink)
+            ?? (relativePath.endsWith(MARKDOWN_EXTENSION)
+                ? relativePath.slice(0, -MARKDOWN_EXTENSION.length)
+                : relativePath);
+        const nextTags = input.tags && input.tags.length > 0
+            ? input.tags.map((tag) => tag.trim()).filter((tag) => tag.length > 0)
+            : safeStringArray(existingFrontmatter.tags);
+        const frontmatter = {
+            title: input.title,
+            type: input.noteType ?? safeString(existingFrontmatter.type) ?? "note",
+            permalink,
+            tags: nextTags,
+            created: safeString(existingFrontmatter.created) ?? date,
+            updated: date,
+        };
+        const body = normalizeContent(input.content).trimEnd();
+        const rendered = `${buildFrontmatter(frontmatter)}\n\n${ensureTrailingNewline(body)}`;
+        await fs.writeFile(targetPath, rendered, "utf8");
+        const saved = await this.loadNote(targetPath, root);
+        const notes = await this.loadProjectNotes(root);
+        const signals = this.qualitySignalsForNote(saved, notes);
+        return {
+            project,
+            operation,
+            filePath: targetPath,
+            relativePath,
+            title: input.title,
+            permalink,
+            linkHealth: signals.linkHealth,
+            unresolvedWikiLinks: signals.unresolvedWikiLinks,
+            unresolvedLinkHints: signals.unresolvedLinkHints,
+            backlinkCount: signals.backlinkCount,
+            orphanWarning: signals.orphanWarning,
+            duplicateWarnings: signals.duplicateWarnings,
+        };
+    }
+    async appendNote(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, Boolean(args.createIfMissing));
+        this.ensureProjectWritable(project);
+        const note = await this.resolveIdentifier(root, args.identifier);
+        if (!note) {
+            if (!args.createIfMissing) {
+                throw new Error(`note not found: ${args.identifier}`);
+            }
+            const created = await this.writeNote({
+                project,
+                directory: args.directory,
+                title: inferTitleFromIdentifier(args.identifier),
+                content: normalizeContent(args.content).trimEnd(),
+                tags: args.tags,
+                noteType: args.noteType,
+            });
+            return {
+                project: created.project,
+                filePath: created.filePath,
+                relativePath: created.relativePath,
+                title: created.title,
+                permalink: created.permalink,
+                operation: "created",
+                linkHealth: created.linkHealth,
+                unresolvedWikiLinks: created.unresolvedWikiLinks,
+                unresolvedLinkHints: created.unresolvedLinkHints,
+                backlinkCount: created.backlinkCount,
+                orphanWarning: created.orphanWarning,
+                duplicateWarnings: created.duplicateWarnings,
+            };
+        }
+        const date = nowDate();
+        const nextBody = `${note.body.trimEnd()}\n\n${normalizeContent(args.content).trimEnd()}\n`;
+        const frontmatter = {
+            ...note.frontmatter,
+            title: note.title,
+            permalink: note.permalink,
+            created: note.created,
+            updated: date,
+        };
+        const rendered = `${buildFrontmatter(frontmatter)}\n\n${nextBody}`;
+        await fs.writeFile(note.filePath, rendered, "utf8");
+        const updated = await this.loadNote(note.filePath, root);
+        const notes = await this.loadProjectNotes(root);
+        const signals = this.qualitySignalsForNote(updated, notes);
+        return {
+            project,
+            filePath: note.filePath,
+            relativePath: note.relativePath,
+            title: note.title,
+            permalink: note.permalink,
+            operation: "appended",
+            linkHealth: signals.linkHealth,
+            unresolvedWikiLinks: signals.unresolvedWikiLinks,
+            unresolvedLinkHints: signals.unresolvedLinkHints,
+            backlinkCount: signals.backlinkCount,
+            orphanWarning: signals.orphanWarning,
+            duplicateWarnings: signals.duplicateWarnings,
+        };
+    }
+    async renameNote(args) {
+        const { name: project, root } = await this.resolveProjectRoot(args.project, false);
+        this.ensureProjectWritable(project);
+        const beforeNotes = await this.loadProjectNotes(root);
+        const projectLinkHealthBefore = this.projectLinkHealth(beforeNotes);
+        const note = await this.resolveIdentifier(root, args.identifier);
+        if (!note) {
+            throw new Error(`note not found: ${args.identifier}`);
+        }
+        const oldTitle = note.title;
+        const oldRelativePath = note.relativePath;
+        const oldPermalink = note.permalink;
+        const oldKeys = this.identifierKeys(note);
+        let nextDirectory = args.directory ? sanitizeRelativePath(args.directory) : path.posix.dirname(note.relativePath);
+        if (nextDirectory === ".") {
+            nextDirectory = "";
+        }
+        const newFileBase = sanitizeFileBase(args.newTitle);
+        const newRelativePath = nextDirectory.length > 0
+            ? `${nextDirectory}/${newFileBase}${MARKDOWN_EXTENSION}`
+            : `${newFileBase}${MARKDOWN_EXTENSION}`;
+        const newAbsolutePath = path.resolve(root, newRelativePath);
+        if (!isInsideDirectory(root, newAbsolutePath)) {
+            throw new Error("invalid rename path");
+        }
+        const oldAbsolutePath = note.filePath;
+        const samePath = path.resolve(oldAbsolutePath) === path.resolve(newAbsolutePath);
+        if (!samePath && (await fileExistsSafe(newAbsolutePath))) {
+            throw new Error(`target file already exists: ${newRelativePath}`);
+        }
+        if (!samePath) {
+            await fs.mkdir(path.dirname(newAbsolutePath), { recursive: true });
+            await fs.rename(oldAbsolutePath, newAbsolutePath);
+        }
+        const date = nowDate();
+        const newPermalink = newRelativePath.endsWith(MARKDOWN_EXTENSION)
+            ? newRelativePath.slice(0, -MARKDOWN_EXTENSION.length)
+            : newRelativePath;
+        const frontmatter = {
+            ...note.frontmatter,
+            title: args.newTitle,
+            permalink: newPermalink,
+            created: note.created,
+            updated: date,
+        };
+        const rewrittenTarget = `${buildFrontmatter(frontmatter)}\n\n${ensureTrailingNewline(note.body.trimEnd())}`;
+        await fs.writeFile(newAbsolutePath, rewrittenTarget, "utf8");
+        let updatedFiles = 0;
+        let updatedLinks = 0;
+        if (args.updateLinks !== false) {
+            const oldKeyLowerSet = new Set(oldKeys.map((key) => key.toLowerCase()));
+            const oldKeyNormalizedSet = new Set(oldKeys.map((key) => normalizeLookup(key)));
+            const notes = await this.loadProjectNotes(root);
+            for (const source of notes) {
+                const rewritten = rewriteWikiLinks(source.raw, (token) => {
+                    const targetLower = token.targetBase.toLowerCase();
+                    const targetNormalized = normalizeLookup(token.targetBase);
+                    const matches = oldKeyLowerSet.has(targetLower)
+                        || (targetNormalized.length > 0 && oldKeyNormalizedSet.has(targetNormalized));
+                    if (!matches) {
+                        return undefined;
+                    }
+                    return renderWikiLink(newPermalink, token.suffix, token.alias);
+                });
+                if (rewritten.replaced > 0) {
+                    await fs.writeFile(source.filePath, rewritten.text, "utf8");
+                    updatedFiles += 1;
+                    updatedLinks += rewritten.replaced;
+                }
+            }
+        }
+        const afterNotes = await this.loadProjectNotes(root);
+        const projectLinkHealthAfter = this.projectLinkHealth(afterNotes);
+        const renamed = await this.loadNote(newAbsolutePath, root);
+        const signals = this.qualitySignalsForNote(renamed, afterNotes);
+        return {
+            project,
+            oldTitle,
+            newTitle: renamed.title,
+            oldRelativePath,
+            newRelativePath: renamed.relativePath,
+            oldPermalink,
+            newPermalink: renamed.permalink,
+            updatedLinks,
+            updatedFiles,
+            renamedNoteLinkHealth: signals.linkHealth,
+            backlinkCount: signals.backlinkCount,
+            orphanWarning: signals.orphanWarning,
+            projectLinkHealthBefore,
+            projectLinkHealthAfter,
+            unresolvedWikiLinks: signals.unresolvedWikiLinks,
+            unresolvedLinkHints: signals.unresolvedLinkHints,
+        };
+    }
+}