@lapis-notes/history 0.1.2 → 0.2.0

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

@@ -0,0 +1,62 @@
+import type { BackupCheckpoint } from "./backup.js";
+import type { VaultRestorePreview, VaultRestoreRequest } from "./restore.js";
+export type SyncProposal = {
+    local: BackupCheckpoint;
+    incoming: BackupCheckpoint;
+    candidate: BackupCheckpoint | null;
+    conflicts: string[];
+};
+export type SyncConflict = {
+    path: string;
+    terms: {
+        id: number;
+        role: string;
+        kind: string;
+        text: string | null;
+        executable?: boolean | null;
+    }[];
+};
+export type SyncResolution = {
+    kind: "term";
+    id: number;
+} | {
+    kind: "text";
+    text: string;
+    executable: boolean;
+} | {
+    kind: "delete";
+};
+export interface SyncService {
+    prepare(revision: number): Promise<SyncProposal | null>;
+    preview(candidate: string, revision: number): Promise<VaultRestorePreview>;
+    apply(request: VaultRestoreRequest, revision: number): Promise<unknown>;
+    conflict(candidate: string, path: string, revision: number): Promise<SyncConflict>;
+    resolve(candidate: string, path: string, resolution: SyncResolution, revision: number): Promise<BackupCheckpoint>;
+    publish(revision: number, requestId: string): Promise<"complete" | "unknown" | "stale" | "stopped">;
+}
+export type PendingSync = {
+    version: 1;
+    revision: number;
+    request: VaultRestoreRequest;
+};
+export declare function pendingSync(value: unknown): PendingSync | undefined;
+export type SyncAction = "sync" | "fetch" | "pull" | "push" | "status";
+export type SyncState = {
+    upstream?: import("./remote.js").RemoteSnapshot;
+    busy: boolean;
+    phase: "ready" | "fetching" | "applying" | "publishing" | "conflicts" | "attention" | "paused";
+    proposal?: SyncProposal;
+    enabled: boolean;
+    conflict?: SyncConflict;
+    lastSuccess?: number;
+    recovery: boolean;
+};
+export declare function idleSyncPhase(state: SyncState): SyncState["phase"];
+/** Keep one notification episode across retries until a successful outcome. */
+export declare function syncFeedback(feedback: {
+    report(error: unknown): void;
+    recovered(): void;
+}): {
+    report(error: unknown): void;
+    recovered(): void;
+};

package/dist/repository/controllers/sync.js

@@ -0,0 +1,38 @@
+export function pendingSync(value) {
+    if (!value || typeof value !== "object")
+        return;
+    const saved = value;
+    if (saved.version === 1 &&
+        Number.isSafeInteger(saved.revision) &&
+        saved.revision >= 0 &&
+        typeof saved.request?.checkpoint === "string" &&
+        typeof saved.request?.expected === "string" &&
+        /^[a-zA-Z0-9-]{1,128}$/.test(saved.request?.request_id))
+        return saved;
+}
+export function idleSyncPhase(state) {
+    return state.recovery
+        ? "attention"
+        : state.proposal?.conflicts.length
+            ? "conflicts"
+            : state.enabled
+                ? "ready"
+                : "paused";
+}
+/** Keep one notification episode across retries until a successful outcome. */
+export function syncFeedback(feedback) {
+    let failure;
+    return {
+        report(error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (failure === message)
+                return;
+            failure = message;
+            feedback.report(error);
+        },
+        recovered() {
+            failure = undefined;
+            feedback.recovered();
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { LocalGraphCommit } from "@lapismd/jj-history";
+import type { TagListItem } from "@lapismd/design-core/shadcn/tag-list";
+import type { RepositoryLogRevision } from "./graph/model.js";
+/** Source-style display mapping; native metadata remains the authority. */
+export declare function repositoryCommitTags(commit?: LocalGraphCommit): TagListItem[];
+export declare function repositoryGraphTags(revision: RepositoryLogRevision, commit?: LocalGraphCommit): TagListItem[];
+export declare function repositoryCommitSearch(id: string, commit?: LocalGraphCommit): string;

package/dist/repository/controllers/tags.js

@@ -0,0 +1,71 @@
+import TriangleAlertIcon from "@lucide/svelte/icons/triangle-alert";
+import { commitCardSearch } from "./commit-cards.js";
+/** Source-style display mapping; native metadata remains the authority. */
+export function repositoryCommitTags(commit) {
+    if (!commit)
+        return [];
+    return [
+        ...(commit.parents.length > 1
+            ? [{ id: "merge", label: "Merge", variant: "secondary" }]
+            : []),
+        ...(commit.divergent
+            ? [{ id: "divergent", label: "Divergent", tone: "warning" }]
+            : []),
+        ...(commit.conflicted
+            ? [
+                {
+                    id: "conflicted",
+                    label: "Conflicted",
+                    tone: "danger",
+                    icon: TriangleAlertIcon,
+                },
+            ]
+            : []),
+        ...commit.bookmarks
+            .filter((bookmark) => bookmark.added && !bookmark.removed)
+            .map((bookmark) => ({
+            id: `bookmark:${JSON.stringify([bookmark.name, bookmark.remote])}`,
+            label: `${bookmark.name}${bookmark.remote ? `@${bookmark.remote}` : ""}`,
+            // Neutral bookmarks need an opaque chip on selected graph rows.
+            variant: "secondary",
+            tone: bookmark.conflicted
+                ? "danger"
+                : bookmark.remote
+                    ? "neutral"
+                    : "accent",
+        })),
+        ...commit.workspaces.map((workspace) => ({
+            id: `workspace:${workspace}`,
+            label: workspace === "default"
+                ? "Working copy"
+                : `Working copy · ${workspace}`,
+            tone: "success",
+        })),
+    ];
+}
+export function repositoryGraphTags(revision, commit) {
+    if (commit)
+        return repositoryCommitTags(commit);
+    return [
+        ...(revision.reason === "merge" ? [{ id: "merge", label: "Merge" }] : []),
+        ...(revision.conflicted
+            ? [
+                {
+                    id: "conflicted",
+                    label: "Conflicted",
+                    tone: "danger",
+                    icon: TriangleAlertIcon,
+                },
+            ]
+            : []),
+        ...revision.tags.map((label, index) => ({
+            id: `operation:${index}:${label}`,
+            label,
+        })),
+    ];
+}
+export function repositoryCommitSearch(id, commit) {
+    return `${commitCardSearch(id, commit)} ${repositoryCommitTags(commit)
+        .map((tag) => tag.label)
+        .join(" ")}`.toLocaleLowerCase();
+}

package/dist/repository/controllers/transcript-paths.d.ts

@@ -0,0 +1,2 @@
+export declare function transcriptFile(path: string): boolean;
+export declare function portableBackupFile(path: string): boolean;

package/dist/repository/controllers/transcript-paths.js

@@ -0,0 +1,17 @@
+// Mirror the native portable-content boundary; native admission stays authoritative.
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+export function transcriptFile(path) {
+    const parts = path.split("/");
+    const index = parts.indexOf(".lapis");
+    const tail = parts.slice(index + 1);
+    return (index >= 0 &&
+        parts.every((p) => !["", ".", "..", ".git", ".jj"].includes(p)) &&
+        tail.length === 4 &&
+        tail[0] === "agents" &&
+        tail[1] === "sessions" &&
+        UUID.test(tail[2]) &&
+        ["metadata.yaml", "agents.jsonl", "transcript.jsonl"].includes(tail[3]));
+}
+export function portableBackupFile(path) {
+    return !path.split("/").includes(".lapis") || transcriptFile(path);
+}

package/dist/repository/controllers/transcript-writers.d.ts

@@ -0,0 +1,9 @@
+import type { App } from "@lapis-notes/api";
+type Guard = <T>(path: string | undefined, apply: () => Promise<T>) => Promise<T>;
+type GuardObserver = (path: string | undefined) => () => void;
+/** Observe protection already acquired by the shared controller; grants no authority. */
+export declare function bindReplacementGuardObserver(app: App, enter: GuardObserver): () => void;
+/** Optional AI writer admission augments replacement, not ordinary App teardown. */
+export declare function bindTranscriptWriters(app: App, guard: Guard): () => void;
+export declare function guardTranscriptReplacement<T>(app: App, path: string | undefined, apply: () => Promise<T>): Promise<T>;
+export {};

package/dist/repository/controllers/transcript-writers.js

@@ -0,0 +1,37 @@
+const writers = new WeakMap();
+const observers = new WeakMap();
+/** Observe protection already acquired by the shared controller; grants no authority. */
+export function bindReplacementGuardObserver(app, enter) {
+    if (observers.has(app))
+        throw new Error("Replacement observer is already bound");
+    const lease = { enter };
+    observers.set(app, lease);
+    return () => {
+        if (observers.get(app) === lease)
+            observers.delete(app);
+    };
+}
+/** Optional AI writer admission augments replacement, not ordinary App teardown. */
+export function bindTranscriptWriters(app, guard) {
+    if (writers.has(app))
+        throw new Error("Transcript writers are already bound");
+    const lease = { guard };
+    writers.set(app, lease);
+    return () => {
+        if (writers.get(app) === lease)
+            writers.delete(app);
+    };
+}
+export function guardTranscriptReplacement(app, path, apply) {
+    const guard = writers.get(app)?.guard;
+    const run = async () => {
+        const leave = observers.get(app)?.enter(path);
+        try {
+            return await apply();
+        }
+        finally {
+            leave?.();
+        }
+    };
+    return guard ? guard(path, run) : app.fileEditingSessions.guard(path, run);
+}

package/dist/repository/controllers/working-copy-controller.d.ts

@@ -0,0 +1,22 @@
+import type { WorkingCopyStatus } from "./working-copy-status.js";
+export type WorkingCopyState = {
+    busy: boolean;
+    status: "loading" | "ready" | "unavailable";
+    value?: WorkingCopyStatus;
+};
+/** Coalesces refresh and fences results immediately on hide/plugin teardown. */
+export declare class WorkingCopyController {
+    #private;
+    readonly read: () => Promise<WorkingCopyStatus>;
+    readonly feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    };
+    constructor(read: () => Promise<WorkingCopyStatus>, feedback: {
+        report(error: unknown): void;
+        recovered(): void;
+    });
+    subscribe(listener: (state: WorkingCopyState) => void): () => void;
+    refresh(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/repository/controllers/working-copy-controller.js

@@ -0,0 +1,58 @@
+/** Coalesces refresh and fences results immediately on hide/plugin teardown. */
+export class WorkingCopyController {
+    #state = { busy: false, status: "loading" };
+    #listeners = new Set();
+    #job;
+    #closed = false;
+    read;
+    feedback;
+    constructor(read, feedback) {
+        this.read = read;
+        this.feedback = feedback;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#state);
+        return () => this.#listeners.delete(listener);
+    }
+    #set(state) {
+        this.#state = state;
+        for (const listener of this.#listeners)
+            listener(state);
+    }
+    refresh() {
+        if (this.#closed)
+            return Promise.resolve();
+        if (this.#job)
+            return this.#job;
+        this.#set({ ...this.#state, busy: true });
+        const job = (async () => {
+            try {
+                const value = await this.read();
+                if (this.#closed)
+                    return;
+                this.feedback.recovered();
+                this.#set({ busy: false, status: "ready", value });
+            }
+            catch (error) {
+                if (this.#closed)
+                    return;
+                // Never display old counts as current after a failed observation.
+                this.#set({ busy: false, status: "unavailable" });
+                this.feedback.report(error);
+            }
+        })();
+        this.#job = job;
+        void job.finally(() => {
+            if (this.#job === job)
+                this.#job = undefined;
+        });
+        return job;
+    }
+    async close() {
+        this.#closed = true;
+        await this.#job;
+        this.#set({ busy: false, status: "unavailable" });
+        this.#listeners.clear();
+    }
+}

package/dist/repository/controllers/working-copy-status.d.ts

@@ -0,0 +1,16 @@
+import type { LocalGraphCommit } from "@lapismd/jj-history";
+export type WorkingCopyStatus = {
+    operation: string;
+    revision: string;
+    changeId: string;
+    workspace: string;
+    description: string;
+    author: LocalGraphCommit["author"];
+    files: number;
+    lines: {
+        additions: number;
+        deletions: number;
+    } | null;
+    uncounted: number;
+};
+export declare function parseWorkingCopyStatus(frame: string): WorkingCopyStatus;

package/dist/repository/controllers/working-copy-status.js

@@ -0,0 +1,57 @@
+const record = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid working copy status");
+    return value;
+};
+const text = (value, limit) => {
+    if (typeof value !== "string" || value.length > limit)
+        throw new Error("Invalid working copy status text");
+    return value;
+};
+const count = (value) => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        throw new Error("Invalid working copy count");
+    return value;
+};
+const id = (value, width) => {
+    const result = text(value, width);
+    if (!new RegExp(`^[a-f0-9]{${width}}$`, "u").test(result))
+        throw new Error("Invalid working copy identity");
+    return result;
+};
+export function parseWorkingCopyStatus(frame) {
+    if (frame.length > 1_048_576)
+        throw new Error("Working copy status exceeds limit");
+    const value = record(JSON.parse(frame));
+    if (value.version !== 1)
+        throw new Error("Unsupported working copy status");
+    const commit = record(value.commit), author = record(commit.author);
+    const timestamp = record(author.timestamp);
+    const millis = text(timestamp.millis, 24);
+    if (!/^-?\d+$/u.test(millis) || !Number.isFinite(Number(millis)))
+        throw new Error("Invalid working copy timestamp");
+    const lines = value.lines === null ? null : record(value.lines);
+    const files = count(value.files), uncounted = count(value.uncounted);
+    if (uncounted > files || uncounted > 0 !== (lines === null))
+        throw new Error("Incomplete working copy totals");
+    return {
+        operation: id(value.operation, 128),
+        revision: id(value.working_copy, 40),
+        changeId: id(commit.change_id, 32),
+        workspace: text(value.workspace, 256),
+        description: text(commit.description, 262144),
+        author: {
+            name: text(author.name, 4096),
+            email: text(author.email, 4096),
+            timestamp: {
+                millis: BigInt(millis),
+                offset_minutes: Number(timestamp.offset_minutes),
+            },
+        },
+        files,
+        uncounted,
+        lines: lines
+            ? { additions: count(lines.additions), deletions: count(lines.deletions) }
+            : null,
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { LocalGraphCommit } from "@lapismd/jj-history";
+export type RepositoryWorkspace = {
+    name: string;
+    commit: LocalGraphCommit;
+};
+/** Only explicitly recorded native workspaces are offered. */
+export declare function repositoryWorkspaces(commits: readonly LocalGraphCommit[]): RepositoryWorkspace[];

package/dist/repository/controllers/workspaces.js

@@ -0,0 +1,4 @@
+/** Only explicitly recorded native workspaces are offered. */
+export function repositoryWorkspaces(commits) {
+    return commits.flatMap((commit) => commit.workspaces.map((name) => ({ name, commit })));
+}

package/dist/repository/index.d.ts

@@ -0,0 +1,9 @@
+export { RepositoryPlugin } from "./components/repository-plugin.js";
+export { bindRepository, prepareRepositoryLeave, } from "./controllers/services.js";
+export type { RepositoryFactory } from "./controllers/services.js";
+export type { RepositoryServices, HistoryReader, RepositoryLeaveMode, } from "./controllers/history-reader.js";
+export { bindTranscriptWriters } from "./controllers/transcript-writers.js";
+export { ownedAiHistory } from "./controllers/ai-history.js";
+export { nativeIndexedHistory } from "./controllers/native-indexed-search.js";
+export { HistoryIndexController } from "./controllers/history-index-controller.js";
+export type { IndexedHistoryService } from "./controllers/indexed-search.js";

package/dist/repository/index.js

@@ -0,0 +1,6 @@
+export { RepositoryPlugin } from "./components/repository-plugin.js";
+export { bindRepository, prepareRepositoryLeave, } from "./controllers/services.js";
+export { bindTranscriptWriters } from "./controllers/transcript-writers.js";
+export { ownedAiHistory } from "./controllers/ai-history.js";
+export { nativeIndexedHistory } from "./controllers/native-indexed-search.js";
+export { HistoryIndexController } from "./controllers/history-index-controller.js";

package/manifest.json

@@ -1,10 +1,12 @@
 {
   "id": "history",
   "name": "History",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "minAppVersion": "0.1.0",
-  "description": "File history",
+  "description": "Browse, compare, and restore saved file revisions",
   "author": "Lapis Notes",
+  "authorAvatarUrl": "https://gravatar.com/avatar/f7226d5f9cf07af2a6a60d3ab11413abb9d2e2eb60f2d5cce17356845a166155?size=256&d=initials",
+  "isDesktopOnly": false,
   "lapis": {
     "manifestVersion": 1,
     "source": "official",
@@ -17,7 +19,14 @@
           "format": "esm",
           "sharedDependencies": [
             "@lapis-notes/api",
-            "@lapis-notes/api/workspace-host"
+            "@lapis-notes/api/workspace-host",
+            "svelte/renderer/5.56.10",
+            "svelte/renderer/5.56.10/attachments",
+            "svelte/renderer/5.56.10/events",
+            "svelte/renderer/5.56.10/internal/client",
+            "svelte/renderer/5.56.10/internal/disclose-version",
+            "svelte/renderer/5.56.10/reactivity",
+            "svelte/renderer/5.56.10/store"
           ],
           "requiresReloadOnUpdate": false
         }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@lapis-notes/history",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Lapis Notes file history plugin",
-  "license": "AGPL-3.0-or-later",
+  "license": "Apache-2.0",
   "type": "module",
   "files": [
     "dist",
     "manifest.json",
     "registry.json",
+    "registry-content",
     "styles.css",
     "README.md",
     "CHANGELOG.md",
@@ -29,26 +30,52 @@
     },
     "./manifest.json": "./manifest.json",
     "./styles.css": "./styles.css",
-    "./registry.json": "./registry.json"
+    "./registry.json": "./registry.json",
+    "./repository": {
+      "types": "./dist/repository/index.d.ts",
+      "svelte": "./dist/repository/index.js",
+      "import": "./dist/repository/index.js",
+      "default": "./dist/repository/index.js"
+    },
+    "./repository/controllers/*": {
+      "types": "./dist/repository/controllers/*.d.ts",
+      "import": "./dist/repository/controllers/*.js",
+      "default": "./dist/repository/controllers/*.js"
+    },
+    "./repository/components/*": {
+      "types": "./dist/repository/components/*.d.ts",
+      "import": "./dist/repository/components/*.js",
+      "default": "./dist/repository/components/*.js"
+    },
+    "./repository/components/*.svelte": {
+      "types": "./dist/repository/components/*.svelte.d.ts",
+      "svelte": "./dist/repository/components/*.svelte",
+      "default": "./dist/repository/components/*.svelte"
+    },
+    "./repository/styles/*.css": "./dist/repository/components/*.css"
   },
   "dependencies": {
-    "@lapismd/design-core": "^0.1.0",
-    "@lucide/svelte": "^0.523.0"
+    "@lapismd/design-core": "^0.7.4",
+    "@lucide/svelte": "^1.57.0",
+    "@tanstack/svelte-virtual": "^3.13.46"
   },
   "peerDependencies": {
-    "@lapis-notes/api": "^0.1.0",
+    "@lapis-notes/api": "^0.2.0",
+    "@lapismd/jj-history": "^0.1.0",
     "svelte": "^5.0.0"
   },
   "devDependencies": {
+    "@lapismd/jj-history": "0.1.0",
     "@sveltejs/package": "^2.5.0",
     "@sveltejs/vite-plugin-svelte": "^5.1.1",
     "@tsconfig/svelte": "^5.0.5",
     "publint": "^0.3.12",
     "svelte": "^5.38.2",
     "svelte-check": "^4.3.1",
+    "tsx": "^4.23.1",
     "typescript": "~5.8.3",
-    "vite": "^6.4.2",
-    "vitest": "^4.1.8"
+    "vite": "^6.4.4",
+    "vitest": "^4.1.12"
   },
   "repository": {
     "type": "git",
@@ -62,13 +89,19 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependenciesMeta": {
+    "@lapismd/jj-history": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "pnpm run prepack",
     "check": "pnpm check:svelte && pnpm check:types",
     "check:svelte": "svelte-check --tsconfig ./tsconfig.app.json --fail-on-warnings --output human",
     "check:types": "tsc -p tsconfig.node.json --noEmit",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run --passWithNoTests && pnpm test:repository",
     "publint": "publint",
-    "pack": "pnpm pack --pack-destination ../../.release/npm"
+    "pack": "pnpm pack --pack-destination ../../.release/npm",
+    "test:repository": "node --import tsx --test test/repository/*.test.mjs"
   }
 }

package/registry-content/overview.md

@@ -0,0 +1,10 @@
+# History
+
+History keeps a bounded, local timeline of meaningful file revisions as notes
+change. Select the active note to browse timestamped snapshots in the sidebar,
+then open any revision in a clear comparison against the document you have now.
+
+When an earlier version contains something worth recovering, restore it through
+the normal vault write path so every other Lapis view observes the update. The
+retention limit and ignored paths remain configurable per vault, and revision
+content never needs to leave the workspace.