@lapis-notes/history 0.1.2 → 0.2.0

package/dist/repository/controllers/operation-parent.js

@@ -0,0 +1,46 @@
+import { check } from "./history-selection.js";
+/** Resolve metadata through the desktop's qualified immutable graph profile. */
+export async function operationParents(reader, handle, pin, selected, parents, known, current) {
+    const result = new Map(known
+        .filter((node) => parents.includes(node.id))
+        .map((node) => [node.id, node]));
+    if (new Set(parents.filter((id) => !result.has(id))).size > 64)
+        throw new Error("Parent details exceed the preview limit");
+    let after = selected;
+    const seen = new Set([after]);
+    for (let page = 0; page < 4 && parents.some((id) => !result.has(id)); page++) {
+        const response = await reader.read(handle, {
+            kind: "graph",
+            query: [
+                { graph: "operations" },
+                { limit: 50, after: { kind: "operation", id: after } },
+            ],
+        });
+        if (!current())
+            return;
+        check(response.kind === "graph" &&
+            response.data.operation === pin &&
+            response.data.data.graph === "operations");
+        const { nodes } = response.data.data;
+        check(nodes.length <= 50);
+        for (const node of nodes)
+            if (parents.includes(node.id))
+                result.set(node.id, node);
+        if (parents.every((id) => result.has(id)))
+            break;
+        const next = response.data.next;
+        if (!next)
+            break;
+        check(next.kind === "operation" && !seen.has(next.id));
+        after = next.id;
+        seen.add(after);
+    }
+    if (!current())
+        return;
+    if (parents.some((id) => !result.has(id)))
+        throw new Error("The parent operation is outside the bounded history page");
+    return [...new Set(parents)].map((id) => result.get(id));
+}
+export async function operationParent(reader, handle, pin, selected, parent, current) {
+    return (await operationParents(reader, handle, pin, selected, [parent], [], current))?.[0];
+}

package/dist/repository/controllers/operation-state.d.ts

@@ -0,0 +1,28 @@
+import { type OperationFilesState } from "./operation-files.js";
+import type { LocalGraphCommit, LocalCodeSnapshot, LocalCodeObjectKey, LocalGraphOperationNode, LocalOperationDiffData } from "@lapismd/jj-history";
+export interface OperationState {
+    phase: "idle" | "loading" | "ready" | "unavailable";
+    busy: boolean;
+    workspace: string | null;
+    workspaceCommits: LocalGraphCommit[];
+    commits: LocalGraphCommit[];
+    heads: string[];
+    headsReady: boolean;
+    operation?: string;
+    snapshot?: LocalCodeSnapshot;
+    nodes: LocalGraphOperationNode[];
+    ready: boolean;
+    next?: LocalCodeObjectKey | null;
+    selected?: LocalGraphOperationNode;
+    parentNodes: LocalGraphOperationNode[];
+    parent?: string;
+    detail?: LocalOperationDiffData;
+    files: OperationFilesState;
+}
+export declare const initialOperationState: () => OperationState;
+export declare const resetOperationSelection: () => {
+    selected: undefined;
+    parent: undefined;
+    detail: undefined;
+    parentNodes: never[];
+};

package/dist/repository/controllers/operation-state.js

@@ -0,0 +1,26 @@
+import { initialOperationFiles, } from "./operation-files.js";
+export const initialOperationState = () => ({
+    files: initialOperationFiles(),
+    phase: "idle",
+    busy: false,
+    workspace: null,
+    workspaceCommits: [],
+    commits: [],
+    heads: [],
+    headsReady: false,
+    nodes: [],
+    ready: false,
+    operation: undefined,
+    snapshot: undefined,
+    next: undefined,
+    selected: undefined,
+    parentNodes: [],
+    parent: undefined,
+    detail: undefined,
+});
+export const resetOperationSelection = () => ({
+    selected: undefined,
+    parent: undefined,
+    detail: undefined,
+    parentNodes: [],
+});

package/dist/repository/controllers/parent-candidates.d.ts

@@ -0,0 +1,4 @@
+import type { Handle, LocalGraphCommit } from "@lapismd/jj-history";
+import type { HistoryReader } from "./history-reader.js";
+/** Parent cards use the existing exact-commit read, never a revset substitution. */
+export declare function parentCandidates(reader: HistoryReader, handle: Handle, parents: readonly string[], known: readonly LocalGraphCommit[], current: () => boolean): Promise<LocalGraphCommit[] | undefined>;

package/dist/repository/controllers/parent-candidates.js

@@ -0,0 +1,27 @@
+import { check } from "./history-selection.js";
+/** Parent cards use the existing exact-commit read, never a revset substitution. */
+export async function parentCandidates(reader, handle, parents, known, current) {
+    const result = [
+        ...new Map(known
+            .filter((commit) => parents.includes(commit.id))
+            .map((commit) => [commit.id, commit])).values(),
+    ];
+    const missing = [...new Set(parents)].filter((id) => !result.some((commit) => commit.id === id));
+    if (missing.length > 64)
+        throw new Error("Parent details exceed the preview limit");
+    for (const id of missing) {
+        const response = await reader.read(handle, {
+            kind: "commit",
+            query: { commit: id },
+        });
+        if (!current())
+            return;
+        check(response.kind === "commit" &&
+            response.data.commit.id === id &&
+            response.data.object.key.kind === "commit" &&
+            response.data.object.key.id === id &&
+            response.data.object.data.kind === "commit");
+        result.push(response.data.commit);
+    }
+    return current() ? result : undefined;
+}

package/dist/repository/controllers/plugin-data.d.ts

@@ -0,0 +1,9 @@
+type Owner = {
+    app?: object;
+    id?: string;
+    loadData(): Promise<Record<string, unknown> | null>;
+    saveData(value: Record<string, unknown>): Promise<void>;
+};
+/** Merge plugin-owned settings/recovery fields without losing another command. */
+export declare function updateRepositoryData(owner: Owner, patch: Record<string, unknown> | ((current: Record<string, unknown>) => Record<string, unknown>)): Promise<Record<string, unknown>>;
+export {};

package/dist/repository/controllers/plugin-data.js

@@ -0,0 +1,33 @@
+const queues = new WeakMap();
+/** Merge plugin-owned settings/recovery fields without losing another command. */
+export function updateRepositoryData(owner, patch) {
+    const scope = owner.app ?? owner;
+    const id = owner.id ?? "";
+    let queue = queues.get(scope);
+    if (!queue) {
+        queue = new Map();
+        queues.set(scope, queue);
+    }
+    const pending = queue;
+    const job = (pending.get(id) ?? Promise.resolve())
+        .catch(() => { })
+        .then(async () => {
+        const current = (await owner.loadData()) ?? {};
+        const updates = typeof patch === "function" ? patch(current) : patch;
+        if (!Object.keys(updates).length)
+            return current;
+        const value = { ...current, ...updates };
+        await owner.saveData(value);
+        return value;
+    });
+    pending.set(id, job);
+    void job
+        .finally(() => {
+        if (pending.get(id) === job)
+            pending.delete(id);
+        if (!pending.size)
+            queues.delete(scope);
+    })
+        .catch(() => { });
+    return job;
+}

package/dist/repository/controllers/preparation-queue.d.ts

@@ -0,0 +1,9 @@
+import type { Handle, HistoryClient } from "@lapismd/jj-history";
+/** The native host deliberately admits only one preparation job at a time. */
+export declare class PreparationQueue {
+    #private;
+    constructor(reader: HistoryClient);
+    open(operation: string, reader?: HistoryClient): Promise<Handle>;
+    close(handle: Handle, reader?: HistoryClient): Promise<void>;
+    stop(): void;
+}

package/dist/repository/controllers/preparation-queue.js

@@ -0,0 +1,55 @@
+import { pause } from "./history-selection.js";
+/** The native host deliberately admits only one preparation job at a time. */
+export class PreparationQueue {
+    #reader;
+    #abort = new AbortController();
+    #tail = Promise.resolve();
+    #previous;
+    constructor(reader) {
+        this.#reader = reader;
+    }
+    open(operation, reader = this.#reader) {
+        const job = this.#tail.then(async () => {
+            this.#abort.signal.throwIfAborted();
+            const previous = this.#previous;
+            if (previous)
+                await this.#available(previous);
+            this.#abort.signal.throwIfAborted();
+            const handle = await reader.open(operation);
+            this.#previous = { handle, reader };
+            return handle;
+        });
+        this.#tail = job.catch(() => { });
+        return job;
+    }
+    close(handle, reader = this.#reader) {
+        const job = reader.close(handle);
+        if (this.#previous?.handle === handle)
+            this.#previous.closing = job;
+        return job;
+    }
+    stop() {
+        this.#abort.abort(new Error("Repository history is closed"));
+    }
+    async #available(previous) {
+        for (let attempt = 0; attempt < 100; attempt++) {
+            this.#abort.signal.throwIfAborted();
+            if (previous.closing)
+                return previous.closing;
+            try {
+                const status = await previous.reader.status(previous.handle);
+                if (previous.closing)
+                    return previous.closing;
+                if (status.state !== "preparing")
+                    return;
+            }
+            catch (error) {
+                if (previous.closing)
+                    return previous.closing;
+                throw error;
+            }
+            await pause(this.#abort.signal);
+        }
+        throw new Error("Repository preparation is still running; try again shortly");
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { RemoteService, RemoteViewState } from "./remote.js";
+export declare class RemoteController {
+    #private;
+    readonly service: RemoteService;
+    readonly feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    };
+    constructor(service: RemoteService, feedback: RemoteController["feedback"]);
+    subscribe(listener: (state: RemoteViewState) => void): () => boolean;
+    subscribeActivity(listener: (state: {
+        busy: boolean;
+        phase: string;
+    }) => void): () => boolean;
+    refresh(): Promise<boolean>;
+    configure(account: string, project: string, branch?: string): Promise<boolean>;
+    fetch(): Promise<boolean>;
+    disconnect(): Promise<boolean>;
+    observePublication(requestId: string): Promise<boolean>;
+    stopPublication(requestId: string): Promise<boolean>;
+    close(): void;
+    drained(): Promise<void>;
+}

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

@@ -0,0 +1,98 @@
+export class RemoteController {
+    service;
+    feedback;
+    #state = { busy: false, phase: "ready" };
+    #closed = false;
+    #listeners = new Set();
+    #activity = new Set();
+    #pending = new Set();
+    constructor(service, feedback) {
+        this.service = service;
+        this.feedback = feedback;
+    }
+    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) {
+        if (this.#closed || this.#state.busy)
+            return Promise.resolve(false);
+        this.#set({ busy: true, phase });
+        const job = (async () => {
+            try {
+                const data = await action();
+                if (this.#closed)
+                    return false;
+                this.#set({ data });
+                this.feedback.recovered();
+                return true;
+            }
+            catch (error) {
+                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());
+    }
+    configure(account, project, branch) {
+        return this.#run("connecting", () => this.service.configure(this.#state.data?.revision ?? 0, account, project.trim(), branch?.trim()));
+    }
+    fetch() {
+        if (!this.#state.data?.configuration)
+            return Promise.resolve(false);
+        return this.#run("fetching", () => this.service.fetch(this.#state.data.revision));
+    }
+    disconnect() {
+        if (!this.#state.data?.configuration)
+            return Promise.resolve(false);
+        return this.#run("disconnecting", () => this.service.disconnect(this.#state.data.revision));
+    }
+    observePublication(requestId) {
+        if (!this.service.publication || !this.#state.data)
+            return Promise.resolve(false);
+        return this.#run("observing", () => this.service.publication.observe(this.#state.data.revision, requestId));
+    }
+    stopPublication(requestId) {
+        if (!this.service.publication || !this.#state.data)
+            return Promise.resolve(false);
+        return this.#run("stopping", () => this.service.publication.stop(this.#state.data.revision, requestId));
+    }
+    close() {
+        this.#closed = true;
+        this.#listeners.clear();
+    }
+    async drained() {
+        while (this.#pending.size)
+            await Promise.allSettled([...this.#pending]);
+    }
+}

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

@@ -0,0 +1,48 @@
+import type { BackupCheckpoint } from "./backup.js";
+import type { RestoreService, VaultRestorePreview, VaultRestoreRequest } from "./restore.js";
+export type RemoteConfiguration = {
+    account: string;
+    project: string;
+    target: {
+        url: string;
+        branch: string;
+    };
+    canPush: boolean;
+};
+export type PendingPublication = {
+    request_id: string;
+    before: string | null;
+    after: string;
+    outcome: "prepared" | "unknown" | "complete" | "stale" | "stopped";
+};
+export type RemoteSnapshot = {
+    divergence?: {
+        local_commit: string;
+        remote_commit: string;
+        incoming: number;
+        outgoing: number;
+    } | null;
+    revision: number;
+    configuration: RemoteConfiguration | null;
+    checkpoint: BackupCheckpoint | null;
+    publication?: PendingPublication | null;
+};
+export interface RemoteService {
+    publication?: {
+        observe(revision: number, requestId: string): Promise<RemoteSnapshot>;
+        stop(revision: number, requestId: string): Promise<RemoteSnapshot>;
+    };
+    status(): Promise<RemoteSnapshot>;
+    configure(revision: number, account: string, project: string, branch?: string): Promise<RemoteSnapshot>;
+    disconnect(revision: number): Promise<RemoteSnapshot>;
+    fetch(revision: number): Promise<RemoteSnapshot>;
+    preview(checkpoint: string): Promise<VaultRestorePreview>;
+    restore(request: VaultRestoreRequest): Promise<unknown>;
+    keepCurrent(): Promise<unknown>;
+}
+export declare function remoteRestore(service: RemoteService): RestoreService;
+export type RemoteViewState = {
+    busy: boolean;
+    phase: string;
+    data?: RemoteSnapshot;
+};

package/dist/repository/controllers/remote.js

@@ -0,0 +1,13 @@
+export function remoteRestore(service) {
+    return {
+        preview: async () => {
+            throw new Error("Choose a remote vault checkpoint");
+        },
+        apply: async () => {
+            throw new Error("Choose a remote vault checkpoint");
+        },
+        previewVault: (checkpoint) => service.preview(checkpoint),
+        applyVault: (request) => service.restore(request),
+        keepCurrent: () => service.keepCurrent(),
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { PendingRestore } from "./restore.js";
+/** Saved view/config state is input, never native authority. */
+export declare function restoreRecovery(value: unknown): PendingRestore | undefined;

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

@@ -0,0 +1,32 @@
+import { portableBackupFile } from "./transcript-paths.js";
+/** Saved view/config state is input, never native authority. */
+export function restoreRecovery(value) {
+    if (value == null)
+        return;
+    if (!value || typeof value !== "object")
+        throw new Error("Invalid interrupted restore record");
+    const saved = value;
+    const request = saved.request;
+    if (saved.version !== 1 ||
+        !["file", "vault"].includes(saved.scope) ||
+        !request ||
+        typeof request !== "object" ||
+        typeof request.request_id !== "string" ||
+        !/^[a-zA-Z0-9-]{1,128}$/.test(request.request_id) ||
+        typeof request.checkpoint !== "string" ||
+        !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(request.checkpoint) ||
+        typeof request.expected !== "string" ||
+        !/^(?:missing|[a-f0-9]{40}|[a-f0-9]{64})$/.test(request.expected))
+        throw new Error("Invalid interrupted restore record");
+    if (saved.scope === "file" &&
+        (typeof saved.request.path !== "string" ||
+            saved.request.path.length > 4096 ||
+            saved.request.path.includes("\\") ||
+            saved.request.path
+                .split("/")
+                .some((part) => ["", ".", "..", ".jj", ".git"].includes(part))))
+        throw new Error("Invalid interrupted file restore path");
+    if (saved.scope === "file" && !portableBackupFile(saved.request.path))
+        throw new Error("Invalid interrupted file restore path");
+    return saved;
+}

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

@@ -0,0 +1,66 @@
+export type RestorePreview = {
+    checkpoint: string;
+    path: string;
+    expected: string;
+    bytes: number;
+    deleted: boolean;
+};
+export type RestoreRequest = {
+    request_id: string;
+    checkpoint: string;
+    path: string;
+    expected: string;
+};
+export interface RestoreService {
+    preview(checkpoint: string, path: string): Promise<RestorePreview>;
+    apply(request: RestoreRequest): Promise<unknown>;
+    previewVault?(checkpoint: string): Promise<VaultRestorePreview>;
+    applyVault?(request: VaultRestoreRequest): Promise<unknown>;
+    keepCurrent?(): Promise<unknown>;
+}
+export type RestoreState = {
+    open: boolean;
+    busy: boolean;
+    preview?: RestorePreview;
+    request?: RestoreRequest;
+    scope?: "file" | "vault";
+    vault?: VaultRestorePreview;
+    vaultRequest?: VaultRestoreRequest;
+    recovery?: boolean;
+};
+export declare class RestoreController {
+    #private;
+    readonly service: RestoreService;
+    readonly guard: <T>(path: string | undefined, action: () => Promise<T>) => Promise<T>;
+    readonly feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    };
+    readonly persist: (pending?: PendingRestore) => Promise<void>;
+    constructor(service: RestoreService, guard: RestoreController["guard"], feedback: RestoreController["feedback"], persist?: RestoreController["persist"]);
+    subscribe(listener: (state: RestoreState) => void): () => boolean;
+    prepare(checkpoint: string, path: string): Promise<void>;
+    prepareVault(checkpoint: string): Promise<void>;
+    apply(): Promise<void>;
+    recover(pending: PendingRestore): void;
+    keepCurrent(): Promise<void>;
+    dismiss(): void;
+    close(): void;
+}
+export type VaultRestoreRequest = Omit<RestoreRequest, "path">;
+export type VaultRestorePreview = {
+    checkpoint: string;
+    expected: string;
+    added: number;
+    modified: number;
+    deleted: number;
+};
+export type PendingRestore = {
+    version: 1;
+    scope: "file";
+    request: RestoreRequest;
+} | {
+    version: 1;
+    scope: "vault";
+    request: VaultRestoreRequest;
+};