@lapis-notes/history 0.1.2 → 0.2.0

package/dist/repository/controllers/storage-controller.js

@@ -0,0 +1,130 @@
+/** An advanced move is explicit and retains native recovery until reload. */
+export class StorageController {
+    service;
+    feedback;
+    guard;
+    #state = { busy: false, phase: "ready", needsReload: false };
+    #closed = false;
+    #listeners = new Set();
+    #activity = new Set();
+    #pending = new Set();
+    constructor(service, feedback, guard = (action) => action()) {
+        this.service = service;
+        this.feedback = feedback;
+        this.guard = guard;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#state);
+        return () => this.#listeners.delete(listener);
+    }
+    subscribeActivity(listener) {
+        this.#activity.add(listener);
+        listener({ busy: this.#pending.size > 0, phase: this.#state.phase });
+        return () => this.#activity.delete(listener);
+    }
+    #set(patch) {
+        if (this.#closed)
+            return;
+        this.#state = { ...this.#state, ...patch };
+        for (const listener of this.#listeners)
+            listener(this.#state);
+    }
+    #announce() {
+        for (const listener of this.#activity)
+            listener({ busy: this.#pending.size > 0, phase: this.#state.phase });
+    }
+    #run(phase, action, mutate = false) {
+        if (this.#closed || this.#state.busy)
+            return Promise.resolve(false);
+        this.#set({ busy: true, phase });
+        let attempted = false;
+        const job = (async () => {
+            try {
+                const data = mutate
+                    ? await this.guard(async () => {
+                        if (this.#closed)
+                            return undefined;
+                        attempted = true;
+                        return action();
+                    })
+                    : await action();
+                if (!data)
+                    return false;
+                this.#set({ data, needsReload: this.#state.needsReload || mutate });
+                if (mutate)
+                    await this.service.reload();
+                if (!this.#closed)
+                    this.feedback.recovered();
+                return true;
+            }
+            catch (error) {
+                if (attempted) {
+                    // A lost response may already have installed the selected layout.
+                    // Observe native recovery; never invent a second move request.
+                    try {
+                        this.#set({ data: await this.service.status(), needsReload: true });
+                    }
+                    catch {
+                        this.#set({ needsReload: true });
+                    }
+                }
+                if (!this.#closed)
+                    this.feedback.report(error);
+                return false;
+            }
+            finally {
+                this.#set({ busy: false, phase: "ready" });
+            }
+        })();
+        const tracked = job.finally(() => {
+            this.#pending.delete(tracked);
+            this.#announce();
+        });
+        this.#pending.add(tracked);
+        this.#announce();
+        return tracked;
+    }
+    refresh() {
+        return this.#run("loading", () => this.service.status());
+    }
+    reveal() {
+        const data = this.#state.data;
+        if (!data?.canReveal ||
+            data.pending ||
+            this.#state.needsReload ||
+            !this.service.reveal)
+            return Promise.resolve(false);
+        return this.#run("revealing", () => this.service.reveal(data.revision));
+    }
+    change(location) {
+        const data = this.#state.data;
+        if (!data || data.pending || data.location === location)
+            return Promise.resolve(false);
+        const id = crypto.randomUUID();
+        return this.#run("moving", () => this.service.change(data.revision, location, id), true);
+    }
+    recover() {
+        return this.#run("recovering", () => this.service.recover(), true);
+    }
+    rollback() {
+        const pending = this.#state.data?.pending;
+        if (!pending)
+            return Promise.resolve(false);
+        return this.#run("recovering", () => this.service.rollback(pending.request_id), true);
+    }
+    reload() {
+        return this.#run("reloading", async () => {
+            await this.service.reload();
+            return this.#state.data ?? (await this.service.status());
+        });
+    }
+    close() {
+        this.#closed = true;
+        this.#listeners.clear();
+    }
+    async drained() {
+        while (this.#pending.size)
+            await Promise.allSettled([...this.#pending]);
+    }
+}

package/dist/repository/controllers/storage.d.ts

@@ -0,0 +1,26 @@
+export type StorageLocation = "external" | "colocated";
+export type StorageStatus = {
+    repositoryPath?: string;
+    canReveal?: boolean;
+    revision: number;
+    location: StorageLocation;
+    pending: {
+        request_id: string;
+        location: StorageLocation;
+        phase: string;
+    } | null;
+};
+export interface StorageService {
+    status(): Promise<StorageStatus>;
+    change(revision: number, location: StorageLocation, requestId: string): Promise<StorageStatus>;
+    recover(): Promise<StorageStatus>;
+    rollback(requestId: string): Promise<StorageStatus>;
+    reveal?(revision: number): Promise<StorageStatus>;
+    reload(): Promise<void>;
+}
+export type StorageState = {
+    busy: boolean;
+    phase: string;
+    data?: StorageStatus;
+    needsReload: boolean;
+};

package/dist/repository/controllers/storage.js

@@ -0,0 +1 @@
+export {};

package/dist/repository/controllers/sync-application.d.ts

@@ -0,0 +1,17 @@
+import type { RemoteService } from "./remote.js";
+import type { PendingSync, SyncService } from "./sync.js";
+/** Guard and persist the original apply identity before any physical writes. */
+export declare function applyCandidate(options: {
+    candidate: string;
+    revision: number;
+    service: SyncService;
+    remote: RemoteService;
+    recovery: {
+        save(pending?: PendingSync): Promise<void>;
+    };
+    guard: <T>(action: () => Promise<T>) => Promise<T>;
+    cancelled(): boolean;
+    closed(): boolean;
+    pending(value?: PendingSync): void;
+    applying(): void;
+}): Promise<void>;

package/dist/repository/controllers/sync-application.js

@@ -0,0 +1,45 @@
+/** Guard and persist the original apply identity before any physical writes. */
+export async function applyCandidate(options) {
+    const { service, revision, candidate } = options;
+    const pending = await options.guard(async () => {
+        if (options.cancelled())
+            return;
+        const current = await options.remote.status();
+        if (options.cancelled())
+            return;
+        if (current.revision !== revision)
+            throw new Error("Backup connection changed; synchronize again");
+        const preview = await service.preview(candidate, revision);
+        if (options.cancelled())
+            return;
+        const pending = {
+            version: 1,
+            revision,
+            request: {
+                request_id: crypto.randomUUID(),
+                checkpoint: preview.checkpoint,
+                expected: preview.expected,
+            },
+        };
+        return pending;
+    });
+    if (!pending || options.cancelled())
+        return;
+    options.pending(pending);
+    // App recovery files have their own writers. Persist before reacquiring
+    // protection; native apply rejects any changed expected tree or connection.
+    await options.recovery.save(pending);
+    if (options.closed())
+        return;
+    const applied = await options.guard(async () => {
+        if (options.closed())
+            return false;
+        options.applying();
+        await service.apply(pending.request, revision);
+        return true;
+    });
+    if (!applied || options.closed())
+        return;
+    await options.recovery.save(undefined);
+    options.pending(undefined);
+}

package/dist/repository/controllers/sync-controller.d.ts

@@ -0,0 +1,31 @@
+import type { RemoteService } from "./remote.js";
+import { type PendingSync, type SyncResolution, type SyncService, type SyncState, type SyncAction } from "./sync.js";
+export declare class SyncController {
+    #private;
+    readonly remote: RemoteService;
+    readonly service: SyncService;
+    readonly guard: <T>(action: () => Promise<T>) => Promise<T>;
+    readonly feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    };
+    readonly recovery: {
+        load(): Promise<unknown>;
+        save(pending?: PendingSync): Promise<void>;
+    };
+    constructor(remote: RemoteService, service: SyncService, guard: <T>(action: () => Promise<T>) => Promise<T>, feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    }, recovery: {
+        load(): Promise<unknown>;
+        save(pending?: PendingSync): Promise<void>;
+    });
+    subscribe(listener: (state: SyncState) => void): () => boolean;
+    setEnabled(enabled: boolean): void;
+    run(action?: SyncAction): Promise<void>;
+    inspect(path: string): Promise<void>;
+    resolve(path: string, resolution: SyncResolution): Promise<void>;
+    keepCurrent(): Promise<void>;
+    close(): void;
+    drained(): Promise<void>;
+}

package/dist/repository/controllers/sync-controller.js

@@ -0,0 +1,300 @@
+import { applyCandidate } from "./sync-application.js";
+import { observePublication, publishSync, refreshPublished, } from "./sync-publication.js";
+import { pendingSync, syncFeedback, idleSyncPhase, } from "./sync.js";
+export class SyncController {
+    remote;
+    service;
+    guard;
+    feedback;
+    recovery;
+    #state = {
+        busy: false,
+        phase: "ready",
+        enabled: true,
+        recovery: false,
+    };
+    #listeners = new Set();
+    #closed = false;
+    #job;
+    #pending;
+    #revision = 0;
+    #resumeAction = "sync";
+    #feedback;
+    #conflictKey;
+    #operations = new Set();
+    constructor(remote, service, guard, feedback, recovery) {
+        this.remote = remote;
+        this.service = service;
+        this.guard = guard;
+        this.feedback = feedback;
+        this.recovery = recovery;
+        this.#feedback = syncFeedback(feedback);
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#state);
+        return () => this.#listeners.delete(listener);
+    }
+    #set(patch) {
+        if (this.#closed)
+            return;
+        this.#state = { ...this.#state, ...patch };
+        for (const listener of this.#listeners)
+            listener(this.#state);
+    }
+    setEnabled(enabled) {
+        if (this.#state.enabled === enabled)
+            return;
+        this.#set({ enabled, phase: enabled ? "ready" : "paused" });
+    }
+    run(action = "sync") {
+        if (this.#closed ||
+            (action === "sync" && !this.#state.enabled) ||
+            (this.#state.busy && !this.#job))
+            return Promise.resolve();
+        return (this.#job ??= this.#track(this.#execute(action)).finally(() => {
+            this.#job = undefined;
+        }));
+    }
+    async #applyPending() {
+        if (!this.#pending)
+            return;
+        const original = this.#pending;
+        this.#set({ phase: "applying", recovery: true });
+        await this.guard(async () => {
+            if (!this.#closed)
+                await this.service.apply(original.request, original.revision);
+        });
+        if (this.#closed)
+            return;
+        await this.recovery.save(undefined);
+        if (this.#pending === original)
+            this.#pending = undefined;
+        this.#set({ recovery: false });
+    }
+    #cancelled(action) {
+        return this.#closed || (action === "sync" && !this.#state.enabled);
+    }
+    async #execute(action) {
+        this.#set({
+            busy: true,
+            phase: action === "status" ? this.#state.phase : "fetching",
+        });
+        try {
+            if (action === "fetch" || action === "status") {
+                let upstream = await this.remote.status();
+                if (this.#closed)
+                    return;
+                this.#set({ upstream });
+                if (action === "fetch") {
+                    if (!upstream.configuration)
+                        throw new Error("Connect an upstream repository first");
+                    upstream = await this.remote.fetch(upstream.revision);
+                }
+                if (this.#closed)
+                    return;
+                this.#set({ upstream, phase: idleSyncPhase(this.#state) });
+                if (action === "fetch")
+                    this.#feedback.recovered();
+                return;
+            }
+            if (!this.#pending) {
+                const stored = await this.recovery.load();
+                this.#pending = pendingSync(stored);
+                if (stored != null && !this.#pending) {
+                    this.#set({ recovery: true });
+                    throw new Error("Saved synchronization recovery is invalid; keep current files before synchronizing again");
+                }
+            }
+            if (this.#closed)
+                return;
+            if (action === "push" &&
+                (this.#pending ||
+                    this.#state.recovery ||
+                    this.#state.proposal?.conflicts.length))
+                throw new Error("Review pending synchronization before pushing");
+            await this.#applyPending();
+            if (this.#cancelled(action))
+                return;
+            let remote = await this.remote.status();
+            this.#set({ upstream: remote });
+            if (this.#cancelled(action))
+                return;
+            if (!remote.configuration) {
+                if (action !== "sync")
+                    throw new Error("Connect an upstream repository first");
+                this.#set({ phase: "ready" });
+                this.#feedback.recovered();
+                return;
+            }
+            remote = await observePublication(this.remote, remote);
+            if (this.#cancelled(action))
+                return;
+            this.#set({ upstream: remote });
+            if (!remote.configuration)
+                return;
+            this.#revision = remote.revision;
+            if (action === "push") {
+                if (!remote.configuration.canPush)
+                    throw new Error("This account cannot push to the upstream repository");
+                const captured = await this.guard(async () => {
+                    if (this.#cancelled(action))
+                        return false;
+                    await this.remote.keepCurrent();
+                    return true;
+                });
+                if (!captured || this.#cancelled(action))
+                    return;
+                this.#set({ phase: "publishing" });
+                await publishSync(this.service, remote.revision);
+                if (this.#closed)
+                    return;
+                this.#set({ upstream: await refreshPublished(this.remote, remote) });
+                this.#set({ phase: idleSyncPhase(this.#state) });
+                this.#feedback.recovered();
+                return;
+            }
+            this.#resumeAction = action;
+            const proposal = await this.service.prepare(remote.revision);
+            if (this.#cancelled(action))
+                return;
+            this.#set({ proposal: proposal ?? undefined, conflict: undefined });
+            if (proposal?.conflicts.length) {
+                this.#set({ phase: "conflicts" });
+                if (this.#conflictKey !== proposal.candidate?.commit) {
+                    this.#conflictKey = proposal.candidate?.commit;
+                    this.#feedback.report(new Error("Backup has conflicts. Open Backup settings to review them."));
+                }
+                return;
+            }
+            if (proposal?.candidate) {
+                await applyCandidate({
+                    candidate: proposal.candidate.commit,
+                    revision: remote.revision,
+                    service: this.service,
+                    remote: this.remote,
+                    recovery: this.recovery,
+                    guard: this.guard,
+                    cancelled: () => this.#cancelled(action),
+                    closed: () => this.#closed,
+                    pending: (next) => {
+                        this.#pending = next;
+                        if (!next)
+                            this.#set({ recovery: false });
+                    },
+                    applying: () => this.#set({ phase: "applying", recovery: true }),
+                });
+            }
+            if (this.#cancelled(action))
+                return;
+            if (action === "sync" && remote.configuration.canPush) {
+                this.#set({ phase: "publishing" });
+                await publishSync(this.service, remote.revision);
+                remote = await refreshPublished(this.remote, remote);
+            }
+            if (!this.#closed) {
+                this.#set({
+                    upstream: action === "sync" ? remote : await this.remote.status(),
+                });
+                this.#set({
+                    phase: this.#state.enabled ? "ready" : "paused",
+                    proposal: undefined,
+                    ...(action === "sync" ? { lastSuccess: Date.now() } : {}),
+                });
+                this.#feedback.recovered();
+            }
+        }
+        catch (error) {
+            if (!this.#closed) {
+                this.#set({
+                    phase: "attention",
+                    recovery: this.#state.recovery || !!this.#pending,
+                });
+                this.#feedback.report(error);
+            }
+        }
+        finally {
+            this.#set({ busy: false });
+        }
+    }
+    async inspect(path) {
+        const proposal = this.#state.proposal;
+        if (this.#closed || this.#state.busy || !proposal?.candidate)
+            return;
+        this.#set({ busy: true });
+        try {
+            const conflict = await this.#track(this.service.conflict(proposal.candidate.commit, path, this.#revision));
+            this.#set({ conflict });
+        }
+        catch (error) {
+            if (!this.#closed)
+                this.#feedback.report(error);
+        }
+        finally {
+            this.#set({ busy: false });
+        }
+    }
+    async resolve(path, resolution) {
+        const proposal = this.#state.proposal;
+        if (this.#closed || this.#state.busy || !proposal?.candidate)
+            return;
+        this.#set({ busy: true });
+        try {
+            const candidate = await this.#track(this.service.resolve(proposal.candidate.commit, path, resolution, this.#revision));
+            if (this.#closed)
+                return;
+            this.#set({
+                proposal: {
+                    ...proposal,
+                    candidate,
+                    conflicts: proposal.conflicts.filter((value) => value !== path),
+                },
+                conflict: undefined,
+            });
+            this.#feedback.recovered();
+        }
+        catch (error) {
+            if (!this.#closed)
+                this.#feedback.report(error);
+        }
+        finally {
+            this.#set({ busy: false });
+        }
+        if (!this.#state.proposal?.conflicts.length)
+            await this.run(this.#resumeAction);
+    }
+    async keepCurrent() {
+        if (this.#closed || this.#state.busy)
+            return;
+        this.#set({ busy: true });
+        try {
+            await this.#track(this.guard(() => this.remote.keepCurrent()));
+            if (this.#closed)
+                return;
+            await this.recovery.save(undefined);
+            this.#pending = undefined;
+            this.#set({ recovery: false, phase: "ready" });
+            this.#feedback.recovered();
+        }
+        catch (error) {
+            if (!this.#closed)
+                this.#feedback.report(error);
+        }
+        finally {
+            this.#set({ busy: false });
+        }
+    }
+    close() {
+        this.#closed = true;
+        this.#listeners.clear();
+    }
+    #track(job) {
+        this.#operations.add(job);
+        void job.finally(() => this.#operations.delete(job)).catch(() => { });
+        return job;
+    }
+    async drained() {
+        while (this.#operations.size)
+            await Promise.allSettled([...this.#operations]);
+    }
+}

package/dist/repository/controllers/sync-publication.d.ts

@@ -0,0 +1,7 @@
+import type { RemoteService, RemoteSnapshot } from "./remote.js";
+import type { SyncService } from "./sync.js";
+/** Observe the retained intent before allowing any new publication request. */
+export declare function observePublication(service: RemoteService, snapshot: RemoteSnapshot): Promise<RemoteSnapshot>;
+export declare function publishSync(service: SyncService, revision: number): Promise<void>;
+/** A proven push stays successful even if refreshing its optional counts fails. */
+export declare function refreshPublished(service: RemoteService, previous: RemoteSnapshot): Promise<RemoteSnapshot>;

package/dist/repository/controllers/sync-publication.js

@@ -0,0 +1,29 @@
+/** Observe the retained intent before allowing any new publication request. */
+export async function observePublication(service, snapshot) {
+    if (!snapshot.publication || !service.publication)
+        return snapshot;
+    const current = await service.publication.observe(snapshot.revision, snapshot.publication.request_id);
+    if (current.publication &&
+        (current.publication.outcome !== "prepared" ||
+            !current.configuration?.canPush))
+        throw new Error("The original push still needs observation; local history is safe");
+    return current;
+}
+export async function publishSync(service, revision) {
+    const result = await service.publish(revision, crypto.randomUUID());
+    if (result !== "complete")
+        throw new Error(result === "unknown"
+            ? "The original push still needs observation; local history is safe"
+            : result === "stopped"
+                ? "The original push stopped tracking; synchronize again to create a new request"
+                : "The remote advanced; synchronization will fetch and merge again");
+}
+/** A proven push stays successful even if refreshing its optional counts fails. */
+export async function refreshPublished(service, previous) {
+    try {
+        return await service.fetch(previous.revision);
+    }
+    catch {
+        return { ...previous, divergence: null };
+    }
+}

package/dist/repository/controllers/sync-recovery.d.ts

@@ -0,0 +1,7 @@
+import { updateRepositoryData } from "./plugin-data.js";
+import { type PendingSync } from "./sync.js";
+/** The completing command can clear only the record that it loaded or saved. */
+export declare function syncRecovery(owner: Parameters<typeof updateRepositoryData>[0]): {
+    load(): Promise<unknown>;
+    save(pending?: PendingSync): Promise<void>;
+};

package/dist/repository/controllers/sync-recovery.js

@@ -0,0 +1,27 @@
+import { updateRepositoryData } from "./plugin-data.js";
+import { pendingSync } from "./sync.js";
+/** The completing command can clear only the record that it loaded or saved. */
+export function syncRecovery(owner) {
+    let original;
+    return {
+        async load() {
+            original = (await owner.loadData())?.pendingSync;
+            return original;
+        },
+        async save(pending) {
+            if (pending)
+                original = pending;
+            const own = original;
+            await updateRepositoryData(owner, (current) => {
+                if (pending)
+                    return { pendingSync: pending };
+                const selected = pendingSync(current.pendingSync);
+                const expected = pendingSync(own);
+                const matches = expected
+                    ? selected?.request.request_id === expected.request.request_id
+                    : JSON.stringify(current.pendingSync) === JSON.stringify(own);
+                return matches ? { pendingSync: null } : {};
+            });
+        },
+    };
+}