@lapis-notes/api 0.1.0

package/dist/file-manager.js

@@ -0,0 +1,289 @@
+import { getFrontMatterInfo } from "./cache.svelte";
+import { TFile } from "./storage/fs";
+import { joinPath } from "./storage/path";
+import { defaultLinkSettings, generateInternalLink, } from "./links";
+import { parseLinktext } from "./utils";
+const FRONTMATTER_RETRY_ERROR = "__lapis_frontmatter_retry__";
+function linkOffsets(position) {
+    if (!position || typeof position !== "object")
+        return null;
+    const value = position;
+    return typeof value.start?.offset === "number" &&
+        typeof value.end?.offset === "number"
+        ? { start: value.start.offset, end: value.end.offset }
+        : null;
+}
+/**
+ * High-level helpers for vault file operations that need metadata-aware
+ * follow-up work.
+ *
+ * @public
+ */
+export class FileManager {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    cloneFrontmatter(frontmatter) {
+        return JSON.parse(JSON.stringify(frontmatter));
+    }
+    async readFrontmatterSeed(file, content) {
+        const cachedFrontmatter = (await this.app.metadataCache.getFileCacheAsync(file))?.frontmatter;
+        if (cachedFrontmatter && typeof cachedFrontmatter === "object") {
+            return this.cloneFrontmatter(cachedFrontmatter);
+        }
+        const fileContent = content ?? (await this.app.vault.read(file));
+        const metadata = await this.app.metadataCache.read(fileContent, file);
+        if (metadata?.frontmatter && typeof metadata.frontmatter === "object") {
+            return this.cloneFrontmatter(metadata.frontmatter);
+        }
+        return {};
+    }
+    isFrontmatterEqual(left, right) {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    writeUpdatedFrontmatter(file, data, frontmatter) {
+        const info = getFrontMatterInfo(data);
+        const hasEntries = Object.keys(frontmatter).length > 0;
+        if (!hasEntries) {
+            return info.exists ? data.slice(info.contentStart) : data;
+        }
+        const updated = this.app.metadataCache.writeFrontmatter(file, frontmatter);
+        const block = `---\n${updated}\n---\n`;
+        if (info.exists) {
+            return `${data.slice(0, info.from)}${block}${data.slice(info.contentStart)}`;
+        }
+        return `${block}${data}`;
+    }
+    getLinkSettings() {
+        const config = this.app.configuration.getConfiguration();
+        return {
+            newLinkFormat: config.get("files.links.newLinkFormat", defaultLinkSettings.newLinkFormat),
+            useWikilinks: config.get("files.links.useWikilinks", defaultLinkSettings.useWikilinks),
+            omitMarkdownExtension: config.get("files.links.omitMarkdownExtension", defaultLinkSettings.omitMarkdownExtension),
+            useShortestUniqueSuffix: config.get("files.links.useShortestUniqueSuffix", defaultLinkSettings.useShortestUniqueSuffix),
+        };
+    }
+    buildVaultIndex() {
+        return {
+            getFiles: () => this.app.vault.getFiles().map((file) => ({
+                path: file.path,
+                basename: file.basename,
+                extension: file.extension,
+            })),
+        };
+    }
+    getReplacementLink(sourcePath, targetPath, originalLink, originalText) {
+        const parsed = parseLinktext(originalLink);
+        const isEmbed = originalText.startsWith("!");
+        const alias = this.extractAlias(originalText);
+        return generateInternalLink({
+            targetPath,
+            sourcePath,
+            alias,
+            embed: isEmbed,
+            heading: parsed.subpath?.startsWith("^") ? undefined : parsed.subpath,
+            blockId: parsed.subpath?.startsWith("^")
+                ? parsed.subpath.slice(1)
+                : undefined,
+            settings: this.getLinkSettings(),
+            vaultIndex: this.buildVaultIndex(),
+        });
+    }
+    extractAlias(originalText) {
+        if (originalText.startsWith("[[") || originalText.startsWith("![[")) {
+            const body = originalText.replace(/^!?\[\[/, "").replace(/\]\]$/, "");
+            const separator = body.indexOf("|");
+            if (separator === -1) {
+                return undefined;
+            }
+            const alias = body.slice(separator + 1).trim();
+            return alias.length ? alias : undefined;
+        }
+        const markdownMatch = /^!?\[(.*)]\((.*)\)$/.exec(originalText);
+        if (!markdownMatch) {
+            return undefined;
+        }
+        const alias = markdownMatch[1]?.trim();
+        if (!alias.length) {
+            return undefined;
+        }
+        return alias;
+    }
+    async collectRenameEdits(file, newPath) {
+        void newPath;
+        const editsBySource = new Map();
+        const refs = await this.app.metadataCache.queryLinks({
+            direction: "incoming",
+            path: file.path,
+            resolution: "resolved",
+            limit: 100_000,
+        });
+        for (const ref of refs) {
+            const offsets = linkOffsets(ref.position);
+            if (!offsets)
+                continue;
+            const sourceEdits = editsBySource.get(ref.sourcePath) ?? [];
+            sourceEdits.push({
+                start: offsets.start,
+                end: offsets.end,
+                link: ref.targetText,
+                original: ref.original ?? ref.targetText,
+            });
+            editsBySource.set(ref.sourcePath, sourceEdits);
+        }
+        return [...editsBySource.entries()].map(([sourcePath, refs]) => ({
+            sourcePath,
+            refs: refs.sort((left, right) => right.start - left.start),
+        }));
+    }
+    /**
+     * Gets the folder that new files should be saved to, given the user's
+     * preferences.
+     *
+     * @param sourcePath - The path to the current open/focused file, used when
+     *   the user wants new files to be created 'in the same folder'. Use an empty
+     *   string if there is no active file.
+     * @param newFilePath - The path to the file that will be newly created, used
+     *   to infer what settings to use based on the path's extension.
+     * @public
+     */
+    getNewFileParent(sourcePath, newFilePath) {
+        return this.app.vault.getRoot();
+    }
+    getAvailablePathForAttachment(filename, sourcePath) {
+        const parent = this.getNewFileParent(sourcePath ?? "", filename);
+        const extMatch = /(\.[^.]*)$/.exec(filename);
+        const stem = extMatch ? filename.slice(0, -extMatch[1].length) : filename;
+        const ext = extMatch?.[1] ?? "";
+        let index = 0;
+        let path = joinPath(parent.path, filename);
+        while (this.app.vault.getAbstractFileByPath(path)) {
+            index += 1;
+            path = joinPath(parent.path, `${stem} ${index}${ext}`);
+        }
+        return path;
+    }
+    /**
+     * Rename or move a file safely, and update all links to it depending on the
+     * user's preferences.
+     *
+     * @param file - The file to rename
+     * @param newPath - The new path for the file
+     * @public
+     */
+    async renameFile(file, newPath) {
+        if (!(file instanceof TFile)) {
+            return this.app.vault.rename(file, newPath);
+        }
+        const oldPath = file.path;
+        const edits = await this.collectRenameEdits(file, newPath);
+        await this.app.vault.rename(file, newPath);
+        for (const edit of edits) {
+            const sourcePath = edit.sourcePath === oldPath ? newPath : edit.sourcePath;
+            const sourceFile = this.app.vault.getFileByPath(sourcePath);
+            if (!sourceFile) {
+                continue;
+            }
+            await this.app.vault.process(sourceFile, (data) => {
+                let next = data;
+                for (const ref of edit.refs) {
+                    const replacement = this.getReplacementLink(sourcePath, newPath, ref.link, ref.original);
+                    next = next.slice(0, ref.start) + replacement + next.slice(ref.end);
+                }
+                return next;
+            });
+        }
+    }
+    /**
+     * Remove a file or a folder from the vault according the user's preferred
+     * 'trash' options (either moving the file to .trash/ or the OS trash bin).
+     *
+     * @param file
+     * @public
+     */
+    trashFile(file) {
+        return this.app.vault.trash(file, true);
+    }
+    promptForDeletion(file) {
+        return this.trashFile(file);
+    }
+    /**
+     * Generate a Markdown link based on the user's preferences.
+     *
+     * @param file - The file to link to.
+     * @param sourcePath - Where the link is stored in, used to compute relative
+     *   links.
+     * @param subpath - A subpath, starting with `#`, used for linking to headings
+     *   or blocks.
+     * @param alias - The display text if it's to be different than the file name.
+     *   Pass empty string to use file name.
+     * @public
+     */
+    generateMarkdownLink(file, sourcePath, subpath, alias) {
+        const normalizedSubpath = subpath?.trim() ?? "";
+        return generateInternalLink({
+            targetPath: file.path,
+            sourcePath,
+            alias,
+            heading: normalizedSubpath.startsWith("#^") || !normalizedSubpath.length
+                ? undefined
+                : normalizedSubpath.replace(/^#/, ""),
+            blockId: normalizedSubpath.startsWith("#^")
+                ? normalizedSubpath.slice(2)
+                : undefined,
+            settings: this.getLinkSettings(),
+            vaultIndex: this.buildVaultIndex(),
+        });
+    }
+    /**
+     * Atomically read, modify, and save the frontmatter of a note. The
+     * frontmatter is passed in as a JS object, and should be mutated directly to
+     * achieve the desired result.
+     *
+     * Remember to handle errors thrown by this method.
+     *
+     * @example
+     *   ```ts
+     *   app.fileManager.processFrontMatter(file, (frontmatter) => {
+     *       frontmatter['key1'] = value;
+     *       delete frontmatter['key2'];
+     *   });
+     *   ```;
+     *
+     * @param file - The file to be modified. Must be a Markdown file.
+     * @param fn - A callback function which mutates the frontmatter object
+     *   synchronously.
+     * @param options - Write options.
+     * @throws YAMLParseError if the YAML parsing fails
+     * @throws Any errors that your callback function throws
+     * @public
+     */
+    processFrontMatter(file, fn, options) {
+        const attempt = async () => {
+            const snapshot = await this.app.vault.read(file);
+            const seedFrontmatter = await this.readFrontmatterSeed(file, snapshot);
+            const nextFrontmatter = this.cloneFrontmatter(seedFrontmatter);
+            fn(nextFrontmatter);
+            if (this.isFrontmatterEqual(seedFrontmatter, nextFrontmatter)) {
+                return;
+            }
+            try {
+                await this.app.vault.process(file, (data) => {
+                    if (data !== snapshot) {
+                        throw new Error(FRONTMATTER_RETRY_ERROR);
+                    }
+                    return this.writeUpdatedFrontmatter(file, data, nextFrontmatter);
+                }, options);
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message === FRONTMATTER_RETRY_ERROR) {
+                    return attempt();
+                }
+                throw error;
+            }
+        };
+        return attempt();
+    }
+}

package/dist/file-tools/app-tools.d.ts

@@ -0,0 +1,3 @@
+import type { AppTool } from "../agent-tools";
+import type { Vault } from "../storage/vault.svelte";
+export declare function createVaultFileAppTools(vault: Vault): AppTool[];

package/dist/file-tools/app-tools.js

@@ -0,0 +1,242 @@
+import { APPLY_PATCH_INPUT_SCHEMA, EDIT_INPUT_SCHEMA, READ_INPUT_SCHEMA, WRITE_INPUT_SCHEMA, applyUpdateChunksToText, executeApplyPatch, executeEdit, executeRead, executeWrite, parseApplyPatch, prepareApplyPatchInput, prepareEditInput, prepareReadInput, prepareWriteInput, } from "@lapismd/ai-host/file-tools";
+import { assertPayloadSize, isAllowedFileToolPath, revisionFromStat, } from "./paths";
+import { createVaultFileOperations } from "./vault-operations";
+function asSchema(schema) {
+    return structuredClone(schema);
+}
+function createScopedResolver(context) {
+    return (path) => {
+        const resolved = context.scope.resolve(path);
+        if (!isAllowedFileToolPath(resolved)) {
+            throw new Error("File path must not address internal content.");
+        }
+        return resolved;
+    };
+}
+function conflictResult(path, reason, matchCount, hunkIndex) {
+    const structuredContent = {
+        status: "conflict",
+        path,
+        reason,
+        ...(matchCount === undefined ? {} : { matchCount }),
+        ...(hunkIndex === undefined ? {} : { hunkIndex }),
+    };
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: `Edit conflict for ${path}: ${reason}`,
+            },
+        ],
+        structuredContent,
+    };
+}
+function createReadTool(vault, operations) {
+    return {
+        name: "read",
+        description: `
+Read a bounded line range from a scoped vault text file.
+Prefer this tool over cat or sed in the agent cwd; host cwd is not the browser vault.
+`.trim(),
+        inputSchema: asSchema(READ_INPUT_SCHEMA),
+        outputSchema: { type: "object" },
+        effect: "read",
+        execute: async (input, context) => {
+            context.signal.throwIfAborted();
+            const prepared = prepareReadInput(input);
+            const result = await executeRead(operations, createScopedResolver(context), prepared);
+            context.signal.throwIfAborted();
+            const structuredContent = {
+                ...result,
+                revision: revisionFromStat(await vault.stat(result.path)),
+            };
+            return {
+                content: [{ type: "text", text: result.text }],
+                structuredContent,
+            };
+        },
+    };
+}
+function createWriteTool(vault, operations) {
+    return {
+        name: "write",
+        description: `
+Create or overwrite a scoped vault text file after creating missing parents.
+Prefer this tool over shell redirects in the agent cwd; paths are vault-relative.
+`.trim(),
+        inputSchema: asSchema(WRITE_INPUT_SCHEMA),
+        outputSchema: { type: "object" },
+        effect: "write",
+        describeApproval: async (input, context) => {
+            const prepared = prepareWriteInput(input);
+            assertPayloadSize(prepared.content, "File content");
+            const path = createScopedResolver(context)(prepared.path);
+            const existing = await operations.stat(path);
+            if (existing?.type === "directory") {
+                throw new Error(`${path} is a folder`);
+            }
+            const before = existing?.type === "file" ? await operations.readFile(path) : "";
+            return {
+                title: `Write ${path}`,
+                description: existing
+                    ? "Overwrite this scoped text file."
+                    : "Create this scoped text file.",
+                path,
+                diff: { before, after: prepared.content },
+            };
+        },
+        execute: async (input, context) => {
+            context.signal.throwIfAborted();
+            const prepared = prepareWriteInput(input);
+            assertPayloadSize(prepared.content, "File content");
+            const result = await executeWrite(operations, createScopedResolver(context), prepared);
+            context.signal.throwIfAborted();
+            const structuredContent = {
+                status: result.created ? "created" : result.changed ? "updated" : "unchanged",
+                ...result,
+                revision: revisionFromStat(await vault.stat(result.path)),
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result.created
+                            ? `Created ${result.path}`
+                            : result.changed
+                                ? `Wrote ${result.path}`
+                                : `Unchanged ${result.path}`,
+                    },
+                ],
+                structuredContent,
+            };
+        },
+    };
+}
+function createEditTool(vault, operations) {
+    return {
+        name: "edit",
+        description: `
+Replace unique exact text hunks in a scoped vault text file.
+Prefer this tool over sed or patching files in the agent cwd.
+`.trim(),
+        inputSchema: asSchema(EDIT_INPUT_SCHEMA),
+        outputSchema: { type: "object" },
+        effect: "write",
+        describeApproval: async (input, context) => {
+            const prepared = prepareEditInput(input);
+            const path = createScopedResolver(context)(prepared.path);
+            return {
+                title: `Edit ${path}`,
+                description: "Replace unique exact text hunks in this file.",
+                path,
+                diffs: prepared.edits.map((edit) => ({
+                    path,
+                    before: edit.oldText,
+                    after: edit.newText,
+                })),
+            };
+        },
+        execute: async (input, context) => {
+            context.signal.throwIfAborted();
+            const prepared = prepareEditInput(input);
+            const result = await executeEdit(operations, createScopedResolver(context), prepared.path, prepared.edits);
+            if (!result.ok) {
+                return conflictResult(result.path, result.reason, result.matchCount, result.hunkIndex);
+            }
+            context.signal.throwIfAborted();
+            const structuredContent = {
+                status: "edited",
+                path: result.path,
+                revision: revisionFromStat(await vault.stat(result.path)),
+            };
+            return {
+                content: [{ type: "text", text: `Edited ${result.path}` }],
+                structuredContent,
+            };
+        },
+    };
+}
+function createApplyPatchTool(operations) {
+    return {
+        name: "apply_patch",
+        description: `
+Apply a V4A patch that adds, updates, moves, or deletes scoped vault text files.
+Prefer this tool over applying patches in the agent cwd.
+`.trim(),
+        inputSchema: asSchema(APPLY_PATCH_INPUT_SCHEMA),
+        outputSchema: { type: "object" },
+        effect: "write",
+        describeApproval: async (input, context) => {
+            const prepared = prepareApplyPatchInput(input);
+            assertPayloadSize(prepared.input, "Patch");
+            const resolvePath = createScopedResolver(context);
+            const hunks = parseApplyPatch(prepared.input);
+            const diffs = [];
+            const paths = [];
+            for (const hunk of hunks) {
+                if (hunk.kind === "add") {
+                    const path = resolvePath(hunk.path);
+                    paths.push(path);
+                    diffs.push({ path, before: "", after: hunk.contents });
+                    continue;
+                }
+                if (hunk.kind === "delete") {
+                    const path = resolvePath(hunk.path);
+                    paths.push(path);
+                    diffs.push({
+                        path,
+                        before: await operations.readFile(path),
+                        after: "",
+                    });
+                    continue;
+                }
+                const path = resolvePath(hunk.path);
+                const current = await operations.readFile(path);
+                const after = applyUpdateChunksToText(current, path, hunk.chunks);
+                if (hunk.movePath) {
+                    const destination = resolvePath(hunk.movePath);
+                    paths.push(path, destination);
+                    diffs.push({ path, before: current, after: "" });
+                    diffs.push({ path: destination, before: "", after });
+                    continue;
+                }
+                paths.push(path);
+                diffs.push({ path, before: current, after });
+            }
+            return {
+                title: paths.length === 1
+                    ? `Patch ${paths[0]}`
+                    : `Patch ${paths.length} files`,
+                description: "Apply a validated V4A patch to scoped text files.",
+                path: paths[0],
+                paths,
+                diffs,
+            };
+        },
+        execute: async (input, context) => {
+            context.signal.throwIfAborted();
+            const prepared = prepareApplyPatchInput(input);
+            assertPayloadSize(prepared.input, "Patch");
+            const result = await executeApplyPatch(operations, createScopedResolver(context), prepared.input);
+            context.signal.throwIfAborted();
+            const structuredContent = {
+                status: "patched",
+                ...result.summary,
+            };
+            return {
+                content: [{ type: "text", text: result.text }],
+                structuredContent,
+            };
+        },
+    };
+}
+export function createVaultFileAppTools(vault) {
+    const operations = createVaultFileOperations(vault);
+    return [
+        createReadTool(vault, operations),
+        createWriteTool(vault, operations),
+        createEditTool(vault, operations),
+        createApplyPatchTool(operations),
+    ];
+}

package/dist/file-tools/index.d.ts

@@ -0,0 +1,3 @@
+export { createVaultFileAppTools } from "./app-tools";
+export { createVaultFileOperations } from "./vault-operations";
+export { HIDDEN_FILE_TOOL_SEGMENTS, MAX_WRITE_BYTES, isAllowedFileToolPath, } from "./paths";

package/dist/file-tools/index.js

@@ -0,0 +1,3 @@
+export { createVaultFileAppTools } from "./app-tools";
+export { createVaultFileOperations } from "./vault-operations";
+export { HIDDEN_FILE_TOOL_SEGMENTS, MAX_WRITE_BYTES, isAllowedFileToolPath, } from "./paths";

package/dist/file-tools/paths.d.ts

@@ -0,0 +1,14 @@
+export declare const HIDDEN_FILE_TOOL_SEGMENTS: Set<string>;
+export declare const MAX_WRITE_BYTES: number;
+export declare function isAllowedFileToolPath(path: string): boolean;
+export declare function parentDirectory(path: string): string | null;
+export declare function byteLength(value: string): number;
+export declare function assertTextContent(content: string, path: string): void;
+export declare function assertPayloadSize(content: string, label: string): void;
+export declare function revisionFromStat(stat: {
+    mtime: number;
+    size: number;
+} | null): {
+    mtime: number;
+    size: number;
+} | null;

package/dist/file-tools/paths.js

@@ -0,0 +1,33 @@
+export const HIDDEN_FILE_TOOL_SEGMENTS = new Set([
+    ".obsidian",
+    ".lapis",
+    ".trash",
+]);
+export const MAX_WRITE_BYTES = 256 * 1024;
+export function isAllowedFileToolPath(path) {
+    return !path
+        .split("/")
+        .some((segment) => HIDDEN_FILE_TOOL_SEGMENTS.has(segment));
+}
+export function parentDirectory(path) {
+    const index = path.lastIndexOf("/");
+    if (index <= 0)
+        return null;
+    return path.slice(0, index);
+}
+export function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+export function assertTextContent(content, path) {
+    if (content.includes("\0")) {
+        throw new Error(`${path} is not a UTF-8 text file.`);
+    }
+}
+export function assertPayloadSize(content, label) {
+    if (byteLength(content) > MAX_WRITE_BYTES) {
+        throw new Error(`${label} exceeds the size limit.`);
+    }
+}
+export function revisionFromStat(stat) {
+    return stat ? { mtime: stat.mtime, size: stat.size } : null;
+}

package/dist/file-tools/vault-operations.d.ts

@@ -0,0 +1,3 @@
+import type { FileToolOperations } from "@lapismd/ai-host/file-tools";
+import type { Vault } from "../storage/vault.svelte";
+export declare function createVaultFileOperations(vault: Vault): FileToolOperations;

package/dist/file-tools/vault-operations.js

@@ -0,0 +1,60 @@
+import { TFile, TFolder } from "../storage/fs";
+import { assertPayloadSize, assertTextContent, parentDirectory, } from "./paths";
+export function createVaultFileOperations(vault) {
+    return {
+        async readFile(path) {
+            const file = vault.getAbstractFileByPath(path);
+            if (!(file instanceof TFile))
+                throw new Error(`File not found: ${path}`);
+            const content = await vault.read(file);
+            assertTextContent(content, path);
+            return content;
+        },
+        async writeFile(path, content) {
+            assertTextContent(content, path);
+            assertPayloadSize(content, "File content");
+            const parent = parentDirectory(path);
+            if (parent)
+                await vault.mkpath(parent);
+            const existing = vault.getAbstractFileByPath(path);
+            if (existing instanceof TFolder) {
+                throw new Error(`${path} is a folder`);
+            }
+            if (existing instanceof TFile) {
+                await vault.modify(existing, content);
+                return;
+            }
+            await vault.create(path, content);
+        },
+        async mkdirp(path) {
+            if (!path)
+                return;
+            await vault.mkpath(path);
+        },
+        async stat(path) {
+            const existing = vault.getAbstractFileByPath(path);
+            if (existing instanceof TFolder)
+                return { type: "directory", size: 0 };
+            if (existing instanceof TFile) {
+                const stat = await vault.stat(path);
+                return { type: "file", size: stat?.size ?? existing.stat.size };
+            }
+            return null;
+        },
+        async remove(path) {
+            const existing = vault.getAbstractFileByPath(path);
+            if (!existing)
+                throw new Error(`File not found: ${path}`);
+            await vault.trash(existing);
+        },
+        async rename(from, to) {
+            const existing = vault.getAbstractFileByPath(from);
+            if (!existing)
+                throw new Error(`File not found: ${from}`);
+            const parent = parentDirectory(to);
+            if (parent)
+                await vault.mkpath(parent);
+            await vault.rename(existing, to);
+        },
+    };
+}