@buoy-gg/time-machine 7.0.17

package/src/store/snapshotVault.ts

@@ -0,0 +1,117 @@
+/**
+ * Snapshot persistence for Time Machine.
+ *
+ * Snapshots live ON-DEVICE in persistentStorage (FileSystem → AsyncStorage →
+ * localStorage → Memory fallback): no size caps, survives restarts, and never
+ * crosses the 2MB external-sync snapshot budget — only metadata does.
+ *
+ * Layout: ONE storage key per snapshot (persistentStorage's FileSystem
+ * backend writes one file per key, and its multiGet is sequential — a single
+ * big key beats many small ones), plus one index key holding the metadata
+ * list for cheap listing.
+ *
+ * Keys use the `@react_buoy` family so every tool's isDevToolsStorageKey
+ * filter (including our own storage provider) excludes the vault itself from
+ * snapshots — a snapshot must never contain snapshots.
+ */
+import {
+  persistentStorage,
+  type SuperJSONResult,
+} from "@buoy-gg/shared-ui";
+
+const INDEX_KEY = "@react_buoy_time_machine:index";
+const SNAP_PREFIX = "@react_buoy_time_machine:snap:";
+
+export interface SnapshotSourceMeta {
+  warnings: string[];
+}
+
+export interface SnapshotMeta {
+  id: string;
+  name: string;
+  createdAt: number;
+  /** Serialized size of the whole stored snapshot. */
+  sizeBytes: number;
+  /**
+   * A baseline snapshot has NO captured data — restoring it wipes to
+   * fresh-install state (clear + reload).
+   */
+  baseline?: boolean;
+  /** Source ids captured, with their capture warnings. */
+  sources: Record<string, SnapshotSourceMeta>;
+}
+
+export interface StoredSnapshot {
+  meta: SnapshotMeta;
+  /** Per-source superjson payloads (absent for baseline snapshots). */
+  data: Record<string, SuperJSONResult>;
+}
+
+export async function loadIndex(): Promise<SnapshotMeta[]> {
+  try {
+    const raw = await persistentStorage.getItem(INDEX_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as SnapshotMeta[];
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+async function saveIndex(metas: SnapshotMeta[]): Promise<void> {
+  await persistentStorage.setItem(INDEX_KEY, JSON.stringify(metas));
+}
+
+/** Persists the snapshot, stamps meta.sizeBytes, and updates the index. */
+export async function saveSnapshot(
+  snapshot: StoredSnapshot,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  const serialized = JSON.stringify(snapshot);
+  snapshot.meta.sizeBytes = serialized.length;
+  await persistentStorage.setItem(
+    SNAP_PREFIX + snapshot.meta.id,
+    // Re-stringify so the persisted copy carries the final sizeBytes.
+    JSON.stringify(snapshot)
+  );
+  const next = [
+    snapshot.meta,
+    ...metas.filter((m) => m.id !== snapshot.meta.id),
+  ];
+  await saveIndex(next);
+  return next;
+}
+
+export async function loadSnapshot(id: string): Promise<StoredSnapshot | null> {
+  try {
+    const raw = await persistentStorage.getItem(SNAP_PREFIX + id);
+    return raw ? (JSON.parse(raw) as StoredSnapshot) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function deleteSnapshot(
+  id: string,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  await persistentStorage.removeItem(SNAP_PREFIX + id);
+  const next = metas.filter((m) => m.id !== id);
+  await saveIndex(next);
+  return next;
+}
+
+export async function renameSnapshot(
+  id: string,
+  name: string,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  const next = metas.map((m) => (m.id === id ? { ...m, name } : m));
+  await saveIndex(next);
+  const stored = await loadSnapshot(id);
+  if (stored) {
+    stored.meta.name = name;
+    await persistentStorage.setItem(SNAP_PREFIX + id, JSON.stringify(stored));
+  }
+  return next;
+}

package/src/store/timeMachineStore.ts

@@ -0,0 +1,368 @@
+/**
+ * Time Machine orchestrator — snapshot CRUD + capture/restore across every
+ * registered StateSnapshotProvider (storage, redux, zustand, jotai, query,
+ * plus any custom providers the app registers).
+ *
+ * Restore ordering is fixed: persisted storage FIRST (so store persist
+ * middleware writing through after an in-memory restore converges with what
+ * we just wrote), then redux → zustand → jotai, query LAST (restored queries
+ * may derive from store state). Custom providers run after, in data order.
+ *
+ * Two restore modes:
+ * - "live":   in-place state replacement, capability-gated per source.
+ * - "reload": restore ONLY persisted storage, then reload the JS bundle —
+ *             in-memory stores rebuild themselves from the restored storage.
+ *             Baseline snapshots always use this path (clear + reload).
+ */
+import {
+  getStateSnapshotProvider,
+  getStateSnapshotProviders,
+  scheduleReloadApp,
+  superJsonDeserialize,
+  superJsonSerialize,
+  type StateSnapshotRestoreResult,
+  type SuperJSONResult,
+} from "@buoy-gg/shared-ui";
+import {
+  deleteSnapshot,
+  loadIndex,
+  loadSnapshot,
+  renameSnapshot,
+  saveSnapshot,
+  type SnapshotMeta,
+  type StoredSnapshot,
+} from "./snapshotVault";
+
+export const RESTORE_ORDER = ["storage", "redux", "zustand", "jotai", "query"];
+
+export type RestoreMode = "live" | "reload";
+
+export interface RestoreOutcome {
+  snapshotId: string;
+  snapshotName: string;
+  mode: RestoreMode;
+  at: number;
+  /** True when a JS reload was scheduled as part of this restore. */
+  willReload: boolean;
+  results: Record<string, StateSnapshotRestoreResult>;
+}
+
+/** Provider capability row as mirrored to a remote dashboard. */
+export interface RemoteProviderStatus {
+  id: string;
+  label: string;
+  canCapture: boolean;
+  canRestore: boolean;
+  detail?: string;
+}
+
+export interface TimeMachineState {
+  snapshots: SnapshotMeta[];
+  hasLoaded: boolean;
+  busy: "capture" | "restore" | null;
+  lastOutcome: RestoreOutcome | null;
+  /**
+   * Non-null when this store is a REMOTE MIRROR (Buoy Desktop): provider
+   * statuses come from the device's sync payload instead of the local
+   * registry, and every operation forwards over the socket.
+   */
+  remoteProviders: RemoteProviderStatus[] | null;
+}
+
+type RemoteHandler = (
+  action: string,
+  params?: Record<string, unknown>
+) => Promise<unknown>;
+
+let remoteHandler: RemoteHandler | null = null;
+
+function skippedResult(reason: string): StateSnapshotRestoreResult {
+  return { ok: false, applied: 0, skipped: [{ id: "*", reason }], warnings: [] };
+}
+
+let idCounter = 0;
+function nextId(): string {
+  idCounter += 1;
+  return `snap_${Date.now().toString(36)}_${idCounter.toString(36)}`;
+}
+
+class TimeMachineStore {
+  private state: TimeMachineState = {
+    snapshots: [],
+    hasLoaded: false,
+    busy: null,
+    lastOutcome: null,
+    remoteProviders: null,
+  };
+  private listeners = new Set<() => void>();
+  private loadPromise: Promise<void> | null = null;
+
+  getState(): TimeMachineState {
+    return this.state;
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    void this.ensureLoaded();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  private setState(patch: Partial<TimeMachineState>) {
+    this.state = { ...this.state, ...patch };
+    this.listeners.forEach((l) => {
+      try {
+        l();
+      } catch {
+        // listener errors must not break the store
+      }
+    });
+  }
+
+  ensureLoaded(): Promise<void> {
+    if (remoteHandler) return Promise.resolve(); // mirror mode — device owns the vault
+    if (!this.loadPromise) {
+      this.loadPromise = loadIndex().then((snapshots) => {
+        if (remoteHandler) return;
+        this.setState({ snapshots, hasLoaded: true });
+      });
+    }
+    return this.loadPromise;
+  }
+
+  /** @internal Buoy Desktop: mirror the device's synced metadata payload. */
+  replaceFromSnapshot(payload: {
+    snapshots?: SnapshotMeta[];
+    busy?: TimeMachineState["busy"];
+    lastOutcome?: RestoreOutcome | null;
+    providers?: RemoteProviderStatus[];
+  }): void {
+    this.setState({
+      snapshots: payload.snapshots ?? [],
+      busy: payload.busy ?? null,
+      lastOutcome: payload.lastOutcome ?? null,
+      remoteProviders: payload.providers ?? [],
+      hasLoaded: true,
+    });
+  }
+
+  /** Capture all capturable sources (or a subset) into a named snapshot. */
+  async capture(name: string, sourceIds?: string[]): Promise<SnapshotMeta> {
+    if (remoteHandler) {
+      const result = (await remoteHandler("capture", { name, sourceIds })) as {
+        snapshot: SnapshotMeta;
+      };
+      return result.snapshot;
+    }
+    await this.ensureLoaded();
+    this.setState({ busy: "capture" });
+    try {
+      const providers = getStateSnapshotProviders().filter(
+        (p) =>
+          p.status().canCapture && (!sourceIds || sourceIds.includes(p.id))
+      );
+      const data: Record<string, SuperJSONResult> = {};
+      const sources: SnapshotMeta["sources"] = {};
+      for (const provider of providers) {
+        try {
+          const captured = await provider.capture();
+          data[provider.id] = superJsonSerialize(captured.data);
+          sources[provider.id] = { warnings: captured.warnings };
+        } catch (e) {
+          sources[provider.id] = {
+            warnings: [`capture failed: ${String(e)}`],
+          };
+        }
+      }
+      const snapshot: StoredSnapshot = {
+        meta: {
+          id: nextId(),
+          name: name.trim() || "Untitled snapshot",
+          createdAt: Date.now(),
+          sizeBytes: 0,
+          sources,
+        },
+        data,
+      };
+      const snapshots = await saveSnapshot(snapshot, this.state.snapshots);
+      this.setState({ snapshots });
+      return snapshot.meta;
+    } finally {
+      this.setState({ busy: null });
+    }
+  }
+
+  /**
+   * Capture the fresh-install baseline: an EMPTY snapshot whose restore
+   * wipes app state (clear + reload) — regardless of what state the app is
+   * in when the button is pressed.
+   */
+  async captureBaseline(): Promise<SnapshotMeta> {
+    if (remoteHandler) {
+      const result = (await remoteHandler("captureBaseline", {})) as {
+        snapshot: SnapshotMeta;
+      };
+      return result.snapshot;
+    }
+    await this.ensureLoaded();
+    const snapshot: StoredSnapshot = {
+      meta: {
+        id: nextId(),
+        name: "Fresh install",
+        createdAt: Date.now(),
+        sizeBytes: 0,
+        baseline: true,
+        sources: {},
+      },
+      data: {},
+    };
+    const snapshots = await saveSnapshot(snapshot, this.state.snapshots);
+    this.setState({ snapshots });
+    return snapshot.meta;
+  }
+
+  async restore(id: string, mode: RestoreMode): Promise<RestoreOutcome> {
+    if (remoteHandler) {
+      const outcome = (await remoteHandler("restore", { id, mode })) as RestoreOutcome;
+      this.setState({ lastOutcome: outcome });
+      return outcome;
+    }
+    await this.ensureLoaded();
+    this.setState({ busy: "restore" });
+    try {
+      const stored = await loadSnapshot(id);
+      if (!stored) throw new Error(`No snapshot with id "${id}"`);
+
+      const outcome: RestoreOutcome = {
+        snapshotId: id,
+        snapshotName: stored.meta.name,
+        mode,
+        at: Date.now(),
+        willReload: false,
+        results: {},
+      };
+
+      if (stored.meta.baseline) {
+        // Fresh install: wipe every clearable source, then reload so all
+        // in-memory state rebuilds from nothing.
+        for (const provider of getStateSnapshotProviders()) {
+          if (provider.clear) {
+            try {
+              outcome.results[provider.id] = await provider.clear();
+            } catch (e) {
+              outcome.results[provider.id] = skippedResult(String(e));
+            }
+          }
+        }
+        outcome.willReload = this.scheduleReload("buoy time-machine baseline");
+        this.setState({ lastOutcome: outcome });
+        return outcome;
+      }
+
+      const sourceIds = [
+        ...RESTORE_ORDER.filter((sid) => sid in stored.data),
+        ...Object.keys(stored.data).filter((sid) => !RESTORE_ORDER.includes(sid)),
+      ];
+
+      if (mode === "reload") {
+        // Storage only; everything in-memory rebuilds after the reload.
+        if (stored.data.storage) {
+          outcome.results.storage = await this.restoreSource(
+            "storage",
+            stored.data.storage
+          );
+        }
+        outcome.willReload = this.scheduleReload("buoy time-machine restore");
+        this.setState({ lastOutcome: outcome });
+        return outcome;
+      }
+
+      for (const sid of sourceIds) {
+        outcome.results[sid] = await this.restoreSource(sid, stored.data[sid]);
+      }
+      this.setState({ lastOutcome: outcome });
+      return outcome;
+    } finally {
+      this.setState({ busy: null });
+    }
+  }
+
+  private async restoreSource(
+    sourceId: string,
+    payload: SuperJSONResult
+  ): Promise<StateSnapshotRestoreResult> {
+    const provider = getStateSnapshotProvider(sourceId);
+    if (!provider) {
+      return skippedResult("provider not available (package missing or not initialized)");
+    }
+    const status = provider.status();
+    if (!status.canRestore) {
+      return skippedResult(status.detail ?? "restore unavailable");
+    }
+    try {
+      return await provider.restore(superJsonDeserialize(payload));
+    } catch (e) {
+      return skippedResult(String(e));
+    }
+  }
+
+  private scheduleReload(reason: string): boolean {
+    try {
+      scheduleReloadApp({ reason });
+      return true;
+    } catch {
+      // No reload mechanism (bare production build?) — restore still stands.
+      return false;
+    }
+  }
+
+  async delete(id: string): Promise<void> {
+    if (remoteHandler) {
+      await remoteHandler("delete", { id });
+      return;
+    }
+    await this.ensureLoaded();
+    const snapshots = await deleteSnapshot(id, this.state.snapshots);
+    this.setState({ snapshots });
+  }
+
+  async rename(id: string, name: string): Promise<void> {
+    if (remoteHandler) {
+      await remoteHandler("rename", { id, name });
+      return;
+    }
+    await this.ensureLoaded();
+    const snapshots = await renameSnapshot(id, name, this.state.snapshots);
+    this.setState({ snapshots });
+  }
+
+  clearLastOutcome(): void {
+    this.setState({ lastOutcome: null });
+  }
+}
+
+export const timeMachineStore = new TimeMachineStore();
+
+/**
+ * Buoy Desktop: route every Time Machine operation through a remote handler
+ * (the device's sync adapter actions) instead of running locally. Pass null
+ * to detach. While attached, feed device payloads to
+ * {@link replaceTimeMachineFromSnapshot}.
+ */
+export function setRemoteTimeMachineHandler(handler: RemoteHandler | null): void {
+  remoteHandler = handler;
+  if (!handler) {
+    timeMachineStore.replaceFromSnapshot({});
+  }
+}
+
+/** Buoy Desktop: mirror a device's synced Time Machine metadata payload. */
+export function replaceTimeMachineFromSnapshot(payload: {
+  snapshots?: SnapshotMeta[];
+  busy?: TimeMachineState["busy"];
+  lastOutcome?: RestoreOutcome | null;
+  providers?: RemoteProviderStatus[];
+}): void {
+  timeMachineStore.replaceFromSnapshot(payload);
+}

package/src/sync/timeMachineSyncAdapter.ts

@@ -0,0 +1,128 @@
+/**
+ * Sync adapter for the Time Machine tool, consumed by @buoy-gg/external-sync's
+ * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
+ * this package doesn't need a dependency on it).
+ *
+ * Snapshots stay ON-DEVICE — getSnapshot ships METADATA only (list, provider
+ * statuses, last restore outcome), far under the 2MB per-tool budget. Payload
+ * inspection goes through the `inspect` action (8MB action-result budget).
+ *
+ * The `restore` action uses the store's scheduleReloadApp path for reload
+ * mode, so the action RESULT is flushed to the broker before the JS realm
+ * dies — a remote caller always gets its answer.
+ */
+import {
+  getStateSnapshotProviders,
+  subscribeToStateSnapshotProviders,
+  superJsonDeserialize,
+} from "@buoy-gg/shared-ui";
+import { timeMachineStore, type RestoreMode } from "../store/timeMachineStore";
+import { loadSnapshot } from "../store/snapshotVault";
+
+interface CaptureParams {
+  name?: string;
+  sourceIds?: string[];
+}
+interface RestoreParams {
+  id: string;
+  mode?: RestoreMode;
+}
+interface IdParams {
+  id: string;
+}
+interface RenameParams {
+  id: string;
+  name: string;
+}
+interface InspectParams {
+  id: string;
+  sourceId: string;
+}
+
+function providerStatuses() {
+  return getStateSnapshotProviders().map((p) => {
+    const s = p.status();
+    return {
+      id: p.id,
+      label: p.label,
+      canCapture: s.canCapture,
+      canRestore: s.canRestore,
+      detail: s.detail,
+    };
+  });
+}
+
+function metadata() {
+  const { snapshots, busy, lastOutcome } = timeMachineStore.getState();
+  return { snapshots, busy, lastOutcome, providers: providerStatuses() };
+}
+
+export const timeMachineSyncAdapter = {
+  version: 1,
+  getSnapshot: () => metadata(),
+  subscribe: (onChange: () => void) => {
+    const unsubStore = timeMachineStore.subscribe(onChange);
+    const unsubProviders = subscribeToStateSnapshotProviders(onChange);
+    return () => {
+      unsubStore();
+      unsubProviders();
+    };
+  },
+  actions: {
+    list: () => metadata(),
+
+    capture: async (params: unknown) => {
+      const { name = "", sourceIds } = (params as CaptureParams) ?? {};
+      const meta = await timeMachineStore.capture(name, sourceIds);
+      return { captured: true, snapshot: meta };
+    },
+
+    captureBaseline: async () => {
+      const meta = await timeMachineStore.captureBaseline();
+      return { captured: true, snapshot: meta };
+    },
+
+    /** mode "live" (default) replaces state in place; "reload" restores
+     * persisted storage then reloads the JS bundle (always the path for
+     * baseline snapshots). */
+    restore: async (params: unknown) => {
+      const { id, mode = "live" } = (params as RestoreParams) ?? {};
+      if (!id) throw new Error("restore requires a snapshot `id`");
+      return await timeMachineStore.restore(id, mode);
+    },
+
+    delete: async (params: unknown) => {
+      const { id } = (params as IdParams) ?? {};
+      if (!id) throw new Error("delete requires a snapshot `id`");
+      await timeMachineStore.delete(id);
+      return { deleted: true, id };
+    },
+
+    rename: async (params: unknown) => {
+      const { id, name } = (params as RenameParams) ?? {};
+      if (!id || !name) throw new Error("rename requires `id` and `name`");
+      await timeMachineStore.rename(id, name);
+      return { renamed: true, id, name };
+    },
+
+    /** One source's captured payload, deserialized — for remote inspection. */
+    inspect: async (params: unknown) => {
+      const { id, sourceId } = (params as InspectParams) ?? {};
+      if (!id || !sourceId) {
+        throw new Error("inspect requires `id` and `sourceId`");
+      }
+      const stored = await loadSnapshot(id);
+      if (!stored) throw new Error(`No snapshot with id "${id}"`);
+      const payload = stored.data[sourceId];
+      if (!payload) {
+        throw new Error(`Snapshot "${id}" has no "${sourceId}" source`);
+      }
+      return {
+        id,
+        sourceId,
+        warnings: stored.meta.sources[sourceId]?.warnings ?? [],
+        data: superJsonDeserialize(payload),
+      };
+    },
+  },
+};