@lapis-notes/api 0.1.4 → 0.2.1

package/dist/file-text-mutation.js

@@ -0,0 +1,100 @@
+import { FileTextPersistence } from "./file-text-persistence";
+/** A retained one-shot draft; it has no view, timer or independent save path. */
+class TextMutation {
+    app;
+    file;
+    transform;
+    options;
+    #dirty = true;
+    #path;
+    #draft = "";
+    #persistence;
+    constructor(app, file, transform, options) {
+        this.app = app;
+        this.file = file;
+        this.transform = transform;
+        this.options = options;
+        this.#path = file.path;
+    }
+    get dirty() {
+        return this.#dirty || !!this.#persistence?.hasConflict;
+    }
+    native = {
+        hold: () => () => { },
+        savedText: () => this.#persistence?.baseline,
+    };
+    async flush() {
+        if (!this.dirty)
+            return;
+        if (this.file.path !== this.#path)
+            throw new Error("File mutation target changed");
+        if (!this.#persistence) {
+            const expected = this.options.expectedText;
+            // Keep the admitted transform if initial IO fails before a draft exists.
+            const baseline = expected === undefined
+                ? await this.app.vault.read(this.file)
+                : expected;
+            try {
+                this.#draft = await this.transform(baseline ?? "");
+                if (this.file.path !== this.#path)
+                    throw new Error("File mutation target changed");
+                if (this.#draft === baseline) {
+                    this.#dirty = false;
+                    return;
+                }
+                this.#persistence = new FileTextPersistence({
+                    vault: {
+                        read: (file) => this.app.vault.read(file),
+                        modifyIfUnchanged: (file, value, expected) => this.app.vault.modifyIfUnchanged(file, value, expected, this.options),
+                    },
+                    file: this.file,
+                    baseline,
+                    conflicts: this.app.fileEditingSessions.textConflicts,
+                    local: () => this.#draft,
+                    protect: () => ({
+                        release() { },
+                        saved: () => this.#saved(),
+                        reset: (text) => this.options.onReset?.(text, this.#persistence.baseline),
+                        resetSaved: (text) => {
+                            this.#draft = text;
+                            this.#dirty = false;
+                        },
+                    }),
+                    serialize: (run) => this.app.fileEditingSessions.recover(this, run),
+                });
+            }
+            catch (error) {
+                // Rejected transforms are invalid actions, rather than failed save drafts.
+                this.#dirty = false;
+                throw error;
+            }
+        }
+        if (this.options.validateBaseline?.() === false)
+            await this.#persistence.rejectPersistence();
+        try {
+            await this.#persistence.persist(this.#draft);
+        }
+        catch (error) {
+            if (!this.#persistence.hasConflict)
+                await this.#persistence.rejectPersistence(error);
+            throw error;
+        }
+        this.#saved();
+    }
+    #saved() {
+        this.#dirty = false;
+        this.options.onSaved?.(this.#draft);
+    }
+    async protect() {
+        // No user edits enter this captured one-shot draft after admission.
+        return () => { };
+    }
+}
+export function mutateFileText(app, file, transform, options = {}) {
+    const path = file.path;
+    return app.fileEditingSessions.mutate(path, () => {
+        if (file.path !== path)
+            throw new Error("File mutation target changed");
+        return new TextMutation(app, file, transform, options);
+    });
+}

package/dist/file-text-persistence.d.ts

@@ -0,0 +1,36 @@
+import type { TFile } from "./storage/fs";
+import type { Vault } from "./storage/vault.svelte";
+import type { FileTextConflictRegistry } from "./file-text-conflicts";
+/** A single recovery operation owns its protected document acknowledgement. */
+export type FileTextRecoveryLease = {
+    release(): void;
+    saved(): void;
+    reset(contents: string): void | Promise<void>;
+    resetSaved?(contents: string): void;
+};
+export type FileTextPersistenceOptions = {
+    vault: Pick<Vault, "read" | "modifyIfUnchanged">;
+    file: TFile;
+    baseline: string | null;
+    conflicts: FileTextConflictRegistry;
+    local(): string;
+    /** Acquire editing protection synchronously, before asynchronous admission. */
+    protect(): FileTextRecoveryLease | Promise<FileTextRecoveryLease>;
+    settle?(): Promise<void>;
+    serialize(run: () => Promise<void>): Promise<void>;
+    /** State restoration may itself write other owned files; revalidate afterward. */
+    recoverOutsideQueue?: boolean;
+};
+/** A single captured document's baseline and explicit text-conflict recovery. */
+export declare class FileTextPersistence {
+    #private;
+    private readonly options;
+    constructor(options: FileTextPersistenceOptions);
+    get hasConflict(): boolean;
+    get baseline(): string | null;
+    acceptBaseline(contents: string | null): void;
+    updateLocal(contents: string): void;
+    /** Retain a computed draft and authoritative disk snapshot before rejecting. */
+    rejectPersistence(error?: unknown): Promise<never>;
+    persist(contents: string): Promise<void>;
+}

package/dist/file-text-persistence.js

@@ -0,0 +1,234 @@
+function hasCode(error, code) {
+    return (!!error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+/** A single captured document's baseline and explicit text-conflict recovery. */
+export class FileTextPersistence {
+    options;
+    #id = crypto.randomUUID();
+    #path;
+    #error;
+    #baseline;
+    #conflict;
+    constructor(options) {
+        this.options = options;
+        this.#path = options.file.path;
+        this.#baseline = options.baseline;
+        this.#error = Object.assign(new Error(`File changed on disk: ${this.#path}`), { code: "ECONFLICT" });
+    }
+    get hasConflict() {
+        return !!this.#conflict;
+    }
+    get baseline() {
+        return this.#baseline;
+    }
+    acceptBaseline(contents) {
+        if (!this.#conflict)
+            this.#baseline = contents;
+    }
+    updateLocal(contents) {
+        if (this.#conflict && this.#conflict.local !== contents)
+            this.#publish(this.#conflict.external, this.#conflict.readError);
+    }
+    /** Retain a computed draft and authoritative disk snapshot before rejecting. */
+    async rejectPersistence(error = this.#error) {
+        this.#assertTarget();
+        await this.#captureExternal();
+        throw error;
+    }
+    async persist(contents) {
+        this.#assertTarget();
+        if (this.#conflict) {
+            this.updateLocal(this.options.local());
+            throw this.#error;
+        }
+        try {
+            await this.options.vault.modifyIfUnchanged(this.options.file, contents, this.#baseline);
+            this.#baseline = contents;
+        }
+        catch (error) {
+            if (hasCode(error, "ECONFLICT")) {
+                await this.#captureExternal();
+                throw this.#error;
+            }
+            throw error;
+        }
+    }
+    #assertTarget() {
+        if (this.options.file.path !== this.#path)
+            throw new Error("File text persistence target changed");
+    }
+    #assertCurrent(conflict) {
+        this.#assertTarget();
+        if (this.#conflict !== conflict)
+            throw new Error("Conflict changed; review the latest versions");
+    }
+    async #read() {
+        this.#assertTarget();
+        try {
+            return await this.options.vault.read(this.options.file);
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+    }
+    async #captureExternal() {
+        try {
+            this.#publish(await this.#read());
+        }
+        catch (error) {
+            this.#publish(undefined, error instanceof Error ? error.message : String(error));
+        }
+    }
+    #publish(external, readError) {
+        const conflict = {
+            id: this.#id,
+            path: this.#path,
+            baseline: this.#baseline,
+            local: this.options.local(),
+            external,
+            ...(readError === undefined ? {} : { readError }),
+            resolve: (choice) => this.#recover(conflict, choice),
+            resolveMerged: (contents) => typeof contents === "string"
+                ? this.#recover(conflict, "keep-local", contents)
+                : Promise.reject(new Error("Merged file contents must be text")),
+            refresh: () => this.#recover(conflict),
+        };
+        this.#conflict = conflict;
+        this.options.conflicts.publish(conflict);
+    }
+    async #recover(conflict, choice, merged) {
+        this.#assertCurrent(conflict);
+        if (choice !== undefined &&
+            choice !== "keep-local" &&
+            choice !== "use-external")
+            throw new Error("Invalid text conflict resolution");
+        if (merged !== undefined && typeof merged !== "string")
+            throw new Error("Merged file contents must be text");
+        const lease = await this.options.protect();
+        try {
+            await this.options.settle?.();
+            if (this.options.recoverOutsideQueue && choice !== undefined) {
+                await this.#recoverState(conflict, choice, lease, merged);
+                return;
+            }
+            await this.options.serialize(async () => {
+                this.#assertCurrent(conflict);
+                if (choice === undefined) {
+                    await this.#captureExternal();
+                    return;
+                }
+                if (conflict.external === undefined)
+                    throw new Error("Read the disk version before resolving this conflict");
+                if (choice === "keep-local") {
+                    const contents = merged ?? this.options.local();
+                    try {
+                        await this.options.vault.modifyIfUnchanged(this.options.file, contents, conflict.external);
+                    }
+                    catch (error) {
+                        if (hasCode(error, "ECONFLICT")) {
+                            await this.#captureExternal();
+                            throw this.#error;
+                        }
+                        throw error;
+                    }
+                    const previousBaseline = this.#baseline;
+                    this.#baseline = contents;
+                    if (merged !== undefined) {
+                        try {
+                            await lease.reset(contents);
+                        }
+                        catch (error) {
+                            this.#baseline = previousBaseline;
+                            throw error;
+                        }
+                        lease.resetSaved?.(contents);
+                    }
+                    else
+                        lease.saved();
+                    this.#clear();
+                }
+                else {
+                    let external;
+                    try {
+                        external = await this.#read();
+                    }
+                    catch (error) {
+                        await this.#captureExternal();
+                        throw error;
+                    }
+                    if (external !== conflict.external) {
+                        this.#publish(external);
+                        throw this.#error;
+                    }
+                    const previousBaseline = this.#baseline;
+                    this.#baseline = external;
+                    try {
+                        await lease.reset(external ?? "");
+                    }
+                    catch (error) {
+                        this.#baseline = previousBaseline;
+                        throw error;
+                    }
+                    this.#clear();
+                    lease.resetSaved?.(external ?? "");
+                }
+            });
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async #recoverState(conflict, choice, lease, merged) {
+        let selected = "";
+        await this.options.serialize(async () => {
+            this.#assertCurrent(conflict);
+            if (conflict.external === undefined)
+                throw new Error("Read the disk version before resolving this conflict");
+            const actual = await this.#read();
+            if (actual !== conflict.external) {
+                this.#publish(actual);
+                throw this.#error;
+            }
+            selected =
+                merged ??
+                    (choice === "keep-local" ? this.options.local() : (actual ?? ""));
+        });
+        // The owner lease remains held, but other owned files can use the queue.
+        await lease.reset(selected);
+        await this.options.serialize(async () => {
+            this.#assertCurrent(conflict);
+            if (choice === "keep-local") {
+                try {
+                    await this.options.vault.modifyIfUnchanged(this.options.file, selected, conflict.external);
+                }
+                catch (error) {
+                    if (hasCode(error, "ECONFLICT"))
+                        await this.#captureExternal();
+                    throw error;
+                }
+            }
+            else {
+                const actual = await this.#read();
+                if (actual !== conflict.external) {
+                    this.#publish(actual);
+                    throw this.#error;
+                }
+            }
+            this.#baseline = choice === "keep-local" ? selected : conflict.external;
+            this.#clear();
+            if (choice === "keep-local" && merged === undefined)
+                lease.saved();
+            else
+                lease.resetSaved?.(selected);
+        });
+    }
+    #clear() {
+        this.#conflict = undefined;
+        this.options.conflicts.clear(this.#id);
+    }
+}

package/dist/file-text-state-writer.d.ts

@@ -0,0 +1,34 @@
+import type { App } from "./context.svelte";
+import type { FileEditingSession } from "./file-editing-sessions";
+import type { TFile } from "./storage/fs";
+/**
+ * App-owned mutable text state using the same persistence contract as
+ * documents.
+ */
+export declare class FileTextStateWriter implements FileEditingSession {
+    #private;
+    private readonly app;
+    private readonly file;
+    private readonly reset;
+    private readonly options;
+    constructor(app: App, file: TFile, baseline: string | null | undefined, reset: (text: string) => void | Promise<void>, options?: {
+        recoverOutsideQueue?: boolean;
+    });
+    get dirty(): boolean;
+    readonly native: {
+        lifetime: "operation";
+        hold: () => () => void;
+        savedText: () => string | null | undefined;
+    };
+    acceptBaseline(contents: string | null): boolean;
+    assertEditable(): void;
+    set(contents: string): Promise<void>;
+    /** Calculate a logical change only after every earlier change is acknowledged. */
+    update(calculate: () => {
+        contents: string;
+        onSaved(): void;
+    } | undefined): Promise<void>;
+    flush(): Promise<void>;
+    protect(): Promise<() => void>;
+    dispose(): void;
+}

package/dist/file-text-state-writer.js

@@ -0,0 +1,183 @@
+import { FileTextPersistence } from "./file-text-persistence";
+import { dirname } from "./storage/path";
+/**
+ * App-owned mutable text state using the same persistence contract as
+ * documents.
+ */
+export class FileTextStateWriter {
+    app;
+    file;
+    reset;
+    options;
+    #path;
+    #persistence;
+    #unregister;
+    #contents;
+    #dirty = false;
+    #locks = 0;
+    #disposed = false;
+    #onSaved;
+    constructor(app, file, baseline, reset, options = {}) {
+        this.app = app;
+        this.file = file;
+        this.reset = reset;
+        this.options = options;
+        this.#path = file.path;
+        this.#contents = baseline ?? "";
+        if (baseline !== undefined)
+            this.#persistence = this.#createPersistence(baseline);
+        this.#unregister = app.fileEditingSessions.register(file.path, this);
+    }
+    #createPersistence(baseline) {
+        return new FileTextPersistence({
+            vault: this.app.vault,
+            file: this.file,
+            baseline,
+            conflicts: this.app.fileEditingSessions.textConflicts,
+            local: () => this.#contents,
+            protect: () => {
+                const release = this.#protect();
+                return {
+                    release,
+                    saved: () => {
+                        this.#dirty = false;
+                        const notify = this.#onSaved;
+                        this.#onSaved = undefined;
+                        notify?.();
+                    },
+                    reset: (text) => this.reset(text),
+                    resetSaved: (text) => {
+                        this.#contents = text;
+                        this.#dirty = false;
+                        this.#onSaved = undefined;
+                    },
+                };
+            },
+            serialize: (run) => this.app.fileEditingSessions.recover(this, async () => {
+                const result = await run();
+                await this.#unregister.idle();
+                return result;
+            }),
+            recoverOutsideQueue: this.options.recoverOutsideQueue,
+        });
+    }
+    get dirty() {
+        return this.#dirty || !!this.#persistence?.hasConflict;
+    }
+    native = {
+        lifetime: "operation",
+        hold: () => this.#protect(),
+        savedText: () => this.#persistence?.baseline,
+    };
+    acceptBaseline(contents) {
+        if (this.dirty || this.#locks || this.#disposed)
+            return false;
+        if (this.#persistence)
+            this.#persistence.acceptBaseline(contents);
+        else
+            this.#persistence = this.#createPersistence(contents);
+        return true;
+    }
+    assertEditable() {
+        if (this.#disposed || this.app.fileEditingSessions.closed)
+            throw new Error("File state writer is closed");
+        if (this.#locks)
+            throw new Error(`File editing is protected: ${this.#path}`);
+        if (this.file.path !== this.#path)
+            throw new Error("File state target changed");
+    }
+    set(contents) {
+        return this.#unregister.native
+            ? this.app.fileEditingSessions.track(() => this.app.fileEditingSessions.recover(this, async () => {
+                await this.#unregister.ready();
+                this.#captureContents(contents);
+                await this.flush();
+            }))
+            : this.#setContents(contents);
+    }
+    #captureContents(contents) {
+        this.assertEditable();
+        this.#contents = contents;
+        this.#dirty = true;
+        this.#unregister.changed();
+        this.#persistence?.updateLocal(contents);
+    }
+    #setContents(contents) {
+        this.#captureContents(contents);
+        return this.app.fileEditingSessions.recover(this, () => this.flush());
+    }
+    /** Calculate a logical change only after every earlier change is acknowledged. */
+    update(calculate) {
+        if (!this.#unregister.native)
+            this.assertEditable();
+        return this.app.fileEditingSessions.recover(this, async () => {
+            await this.flush();
+            if (this.#unregister.native) {
+                await this.#unregister.ready();
+                this.assertEditable();
+            }
+            const change = calculate();
+            if (!change) {
+                await this.#unregister.idle();
+                return;
+            }
+            this.#contents = change.contents;
+            this.#dirty = true;
+            this.#unregister.changed();
+            this.#onSaved = change.onSaved;
+            await this.flush();
+        });
+    }
+    async flush() {
+        if (!this.#dirty) {
+            await this.#unregister.idle();
+            return;
+        }
+        if (this.#unregister.native)
+            await this.#unregister.ready();
+        const contents = this.#contents;
+        const notify = this.#onSaved;
+        try {
+            if (!this.#persistence) {
+                const adapter = this.app.vault.adapter;
+                const baseline = (await adapter.exists(this.#path))
+                    ? await adapter.read(this.#path)
+                    : null;
+                this.#persistence = this.#createPersistence(baseline);
+            }
+            await this.app.vault.mkpath(dirname(this.#path));
+            await this.#persistence.persist(contents);
+        }
+        catch (error) {
+            if (this.#persistence && !this.#persistence.hasConflict)
+                await this.#persistence.rejectPersistence(error);
+            throw error;
+        }
+        this.#dirty = this.#contents !== contents;
+        if (!this.#dirty)
+            this.#onSaved = undefined;
+        notify?.();
+        if (!this.#dirty)
+            await this.#unregister.idle();
+    }
+    #protect() {
+        this.#locks++;
+        let held = true;
+        return () => {
+            if (held) {
+                held = false;
+                this.#locks--;
+            }
+        };
+    }
+    async protect() {
+        // All persistence is on the registry queue; no queued guard is re-entered here.
+        return this.#protect();
+    }
+    dispose() {
+        if (this.dirty)
+            throw new Error(`File state remains dirty: ${this.#path}`);
+        this.#disposed = true;
+        this.#unregister();
+    }
+}

package/dist/files-configuration.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceSettingsController } from "@lapismd/design-core/workspace/settings";
+/** Core application settings; no plugin owns file discovery policy. */
+export declare const FILES_CONFIGURATION_SCHEMA: {
+    readonly id: "files";
+    readonly title: "Files";
+    readonly type: "object";
+    readonly properties: {
+        readonly exclude: {
+            readonly type: "array";
+            readonly title: "Excluded paths";
+            readonly description: "Glob patterns hidden from vault file and folder listings. Matching folders hide their contents at any depth. Explicit metadata access and backup exclusions are separate.";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly default: readonly string[];
+        };
+    };
+};
+/** Register core discovery policy beside the shell's existing Workspace fields. */
+export declare function registerWorkspaceFileSettings(settings: WorkspaceSettingsController): void;

package/dist/files-configuration.js

@@ -0,0 +1,47 @@
+import { DEFAULT_VAULT_EXCLUDES } from "./storage/vault-listing";
+/** Core application settings; no plugin owns file discovery policy. */
+export const FILES_CONFIGURATION_SCHEMA = {
+    id: "files",
+    title: "Files",
+    type: "object",
+    properties: {
+        exclude: {
+            type: "array",
+            title: "Excluded paths",
+            description: "Glob patterns hidden from vault file and folder listings. Matching folders hide their contents at any depth. Explicit metadata access and backup exclusions are separate.",
+            items: { type: "string" },
+            default: [...DEFAULT_VAULT_EXCLUDES],
+        },
+    },
+};
+/** Register core discovery policy beside the shell's existing Workspace fields. */
+export function registerWorkspaceFileSettings(settings) {
+    const workspace = settings.sections.find((section) => section.id === "workspace") ?? {
+        id: "workspace",
+        title: "Workspace",
+        navigationGroupId: "options",
+        order: 10,
+    };
+    settings.registerSection({
+        ...workspace,
+        fields: [
+            ...(workspace.fields ?? []).filter((field) => field.id !== "workspace.files"),
+            {
+                id: "workspace.files",
+                type: "group",
+                title: "File discovery",
+                description: "Choose which paths appear in file and folder lists.",
+                fields: [
+                    {
+                        id: "files.exclude",
+                        type: "list",
+                        itemType: "string",
+                        title: "Excluded paths",
+                        description: "Glob patterns hidden from file and folder lists. Folder names apply at any depth. Clear the list to show all paths. This does not change backups or delete files.",
+                        default: [...DEFAULT_VAULT_EXCLUDES],
+                    },
+                ],
+            },
+        ],
+    });
+}