@peers-app/peers-ui 0.25.8 → 0.25.10

package/src/screens/network-viewer/sync-recovery.test.tsx

@@ -0,0 +1,114 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { SyncRecoveryScreen } from "./sync-recovery";
+
+const mockResolveSyncRecovery = jest.fn(async () => ({
+  success: false,
+  message: "Permission denied for Shared Group: requires Owner",
+}));
+
+jest.mock("./network-viewer-ipc", () => ({
+  getNetworkDiagnosticsConsumer: async () => ({
+    tools: {
+      getSyncRecoveryEntries: async () => ({
+        entries: [
+          {
+            dataContextId: "personal",
+            dataContextName: "Personal",
+            syncRecoveryId: "queue-1",
+            tableName: "Messages",
+            recordId: "00mflddy2sbk393s47smn4tgl",
+            firstFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            lastFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            attemptCount: 3,
+            latestError:
+              'Validation on insert failed for Messages: [{"code":"custom","message":"assistant id was empty","path":["assistantId"]}]',
+            status: "parked",
+            parkedReason: "schema",
+            stuck: true,
+            localRowExists: false,
+            recordSummary: "hello from the stored message",
+            queuedRecordPreview: '{\n  "message": "hello from the stored message"\n}',
+            recordPreview: '{\n  "message": "hello from the stored message"\n}',
+            changeCreatedAt: Date.parse("2026-09-10T17:16:02Z"),
+          },
+          {
+            dataContextId: "personal",
+            dataContextName: "Personal",
+            syncRecoveryId: "queue-2",
+            tableName: "UniqueNames",
+            recordId: "00mflddy2sbk393s47smn4tgm",
+            firstFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            lastFailedAt: Date.parse("2026-09-10T17:16:02Z"),
+            attemptCount: 1,
+            latestError: "UNIQUE constraint failed: UniqueNames.name",
+            status: "parked",
+            parkedReason: "unique-conflict",
+            stuck: true,
+            localRowExists: true,
+            conflictingRecordId: "00mflddy2sbk393s47smn4tgn",
+            tombstoneRecordId: "00mflddy2sbk393s47smn4tgm",
+            recordSummary: "shared",
+            keptRecordPreview: '{\n  "name": "shared",\n  "value": "local"\n}',
+            queuedRecordPreview: '{\n  "name": "shared",\n  "value": "rejected"\n}',
+            recordPreview: '{\n  "name": "shared",\n  "value": "local"\n}',
+          },
+        ],
+      }),
+    },
+    observables: {
+      status: {
+        subscribe: () => ({ dispose() {} }),
+      },
+    },
+  }),
+  getNetworkControlConsumer: async () => ({
+    tools: {
+      resolveSyncRecovery: () => mockResolveSyncRecovery(),
+    },
+  }),
+}));
+
+describe("SyncRecoveryScreen", () => {
+  it("shows the full error, status help, action help, and stored record", async () => {
+    render(<SyncRecoveryScreen onBack={() => undefined} />);
+
+    expect(await screen.findByText("hello from the stored message")).toBeTruthy();
+    expect(screen.getByText(/Validation on insert failed/)).toBeTruthy();
+    expect(screen.queryByText(/assistant id was empty/)).toBeNull();
+
+    fireEvent.click(screen.getAllByRole("button", { name: "Show error details" })[0]);
+    const error = screen.getByText(/assistant id was empty/);
+    expect(error.tagName).toBe("PRE");
+
+    fireEvent.click(screen.getByRole("button", { name: "About status Parked, schema" }));
+    expect(screen.getByText(/does not match this device's rules/)).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "About these actions" }));
+    expect(screen.getByText(/only the other row is stored/)).toBeTruthy();
+
+    fireEvent.click(screen.getAllByRole("button", { name: "Show record details" })[0]);
+    expect(screen.getByText(/Change written/)).toBeTruthy();
+    expect(screen.getByText("Queued change")).toBeTruthy();
+    expect(screen.getByText(/"message": "hello from the stored message"/)).toBeTruthy();
+  });
+
+  it("labels the row Keep will snapshot separately from a different queued change", async () => {
+    render(<SyncRecoveryScreen onBack={() => undefined} />);
+    fireEvent.click((await screen.findAllByRole("button", { name: "Show record details" }))[1]);
+    expect(screen.getByText("This device's version")).toBeTruthy();
+    expect(screen.getByText(/"value": "local"/)).toBeTruthy();
+    expect(screen.getByText("Queued change")).toBeTruthy();
+    expect(screen.getByText(/"value": "rejected"/)).toBeTruthy();
+    expect(screen.getByText(/tombstones this queued id/)).toBeTruthy();
+    expect(screen.queryByText(/Keep deletes/)).toBeNull();
+  });
+
+  it("keeps a failed action message after the list reloads", async () => {
+    render(<SyncRecoveryScreen onBack={() => undefined} />);
+    fireEvent.click((await screen.findAllByRole("button", { name: "Ignore on this device" }))[0]);
+    expect(
+      await screen.findByText("Permission denied for Shared Group: requires Owner"),
+    ).toBeTruthy();
+    expect(screen.getByText("hello from the stored message")).toBeTruthy();
+  });
+});

package/src/screens/network-viewer/sync-recovery.tsx

@@ -0,0 +1,461 @@
+import type { INetworkSyncRecoveryEntry, SyncRecoveryResolution } from "@peers-app/peers-sdk";
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
+import { Popover } from "react-tiny-popover";
+import { LoadingIndicator } from "../../components/loading-indicator";
+import { getNetworkControlConsumer, getNetworkDiagnosticsConsumer } from "./network-viewer-ipc";
+
+/** Props for {@link SyncRecoveryScreen}. */
+interface ISyncRecoveryScreenProps {
+  /** Return to the Network Viewer overview. */
+  onBack: () => void;
+}
+
+function formatWhen(timestamp: number): string {
+  return new Date(timestamp).toLocaleString();
+}
+
+function statusLabel(entry: INetworkSyncRecoveryEntry): string {
+  if (entry.status === "retrying") {
+    return "Retrying";
+  }
+  if (entry.parkedReason === "schema") {
+    return "Parked, schema";
+  }
+  if (entry.parkedReason === "unique-conflict") {
+    return "Parked, conflict";
+  }
+  if (entry.parkedReason === "unresolvable") {
+    return "Parked, needs a decision";
+  }
+  return "Parked";
+}
+
+function statusExplanation(entry: INetworkSyncRecoveryEntry): string {
+  if (entry.status === "retrying") {
+    return "This device is still asking others for a copy it can write. The wait starts at one minute and doubles after each try, up to one hour. It is marked as needing attention after 5 tries spanning at least 10 minutes.";
+  }
+  if (entry.parkedReason === "schema") {
+    return "The saved change does not match this device's rules for the table — a missing field, an empty id, or an id in the wrong format. Every device has the same change, so asking them again will not help. It is tried again from history once each time this device starts, when a newer change arrives, and when you press Retry. After an upgrade that accepts the row, the next startup or Retry can write it.";
+  }
+  if (entry.parkedReason === "unique-conflict") {
+    return "Two records want the same unique value, such as one variable name. This table has no automatic way to choose a winner, so nothing is deleted until you pick an action.";
+  }
+  if (entry.parkedReason === "unresolvable") {
+    return "An automatic fix could not be applied safely — the other record was missing, more than one row matched, or the write failed. The rows were left as they are. Choose an action when you know which version should remain.";
+  }
+  return "This entry is waiting and is not being sent to other devices. Retry tries it again. The other actions clear it.";
+}
+
+/** Show a validation payload as indented JSON when the error ends with one. */
+function formatError(error: string): string {
+  const marker = error.search(/[[{]/);
+  if (marker < 0) {
+    return error;
+  }
+  const head = error.slice(0, marker).trimEnd();
+  try {
+    return `${head}\n${JSON.stringify(JSON.parse(error.slice(marker)), null, 2)}`;
+  } catch {
+    return error;
+  }
+}
+
+const detailsBlockStyle = {
+  maxHeight: "16.8em",
+  lineHeight: 1.4,
+  overflow: "auto",
+  whiteSpace: "pre-wrap",
+  wordBreak: "break-word",
+} as const;
+
+function errorSummary(error: string): string {
+  const line = error.split("\n")[0] ?? error;
+  return line.length > 80 ? `${line.slice(0, 77)}…` : line;
+}
+
+function InfoTip({ label, children }: { label: string; children: ReactNode }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Popover
+      isOpen={open}
+      positions={["bottom", "top", "left", "right"]}
+      align="start"
+      onClickOutside={() => setOpen(false)}
+      content={() => (
+        <div
+          className="card p-2 shadow small"
+          style={{ maxWidth: 420, zIndex: 1000001, textAlign: "left" }}
+        >
+          {children}
+        </div>
+      )}
+    >
+      <button
+        type="button"
+        className="btn btn-link btn-sm p-0 ms-1 align-baseline text-info"
+        aria-label={label}
+        onClick={() => setOpen((current) => !current)}
+      >
+        <i className="bi bi-info-circle" />
+      </button>
+    </Popover>
+  );
+}
+
+function RecoveryRows({
+  entry,
+  busy,
+  onRun,
+}: {
+  entry: INetworkSyncRecoveryEntry;
+  busy: boolean;
+  onRun: (entry: INetworkSyncRecoveryEntry, action: "retry" | SyncRecoveryResolution) => void;
+}) {
+  const [recordOpen, setRecordOpen] = useState(false);
+  const [errorOpen, setErrorOpen] = useState(false);
+  return (
+    <>
+      <tr>
+        <td>{entry.tableName}</td>
+        <td>
+          <code title={entry.recordId}>{entry.recordId}</code>
+          {entry.recordSummary && (
+            <div className="small text-muted" style={{ maxWidth: 220 }}>
+              {entry.recordSummary}
+            </div>
+          )}
+          <button
+            type="button"
+            className="btn btn-link btn-sm p-0"
+            aria-label={recordOpen ? "Hide record details" : "Show record details"}
+            onClick={() => setRecordOpen((current) => !current)}
+          >
+            {recordOpen ? "Hide details" : "Details"}
+          </button>
+        </td>
+        <td className="text-nowrap small">{formatWhen(entry.firstFailedAt)}</td>
+        <td>{entry.attemptCount}</td>
+        <td className="text-nowrap">
+          {statusLabel(entry)}
+          <InfoTip label={`About status ${statusLabel(entry)}`}>{statusExplanation(entry)}</InfoTip>
+        </td>
+        <td>
+          <div className="small text-muted" style={{ maxWidth: 220 }}>
+            {errorSummary(entry.latestError)}
+          </div>
+          <button
+            type="button"
+            className="btn btn-link btn-sm p-0"
+            aria-label={errorOpen ? "Hide error details" : "Show error details"}
+            onClick={() => setErrorOpen((current) => !current)}
+          >
+            {errorOpen ? "Hide details" : "Details"}
+          </button>
+        </td>
+        <td>
+          <div className="d-flex flex-column gap-1">
+            <button
+              type="button"
+              className="btn btn-sm btn-outline-primary"
+              disabled={busy}
+              onClick={() => onRun(entry, "retry")}
+            >
+              Retry
+            </button>
+            <button
+              type="button"
+              className="btn btn-sm btn-outline-primary"
+              disabled={busy || !entry.localRowExists}
+              title={
+                entry.localRowExists
+                  ? "Write this device's row as a snapshot every device will adopt"
+                  : "This device has no row to keep"
+              }
+              onClick={() => onRun(entry, "keepLocal")}
+            >
+              Keep this device's version
+            </button>
+            <button
+              type="button"
+              className="btn btn-sm btn-outline-danger"
+              disabled={busy}
+              onClick={() => onRun(entry, "deleteEverywhere")}
+            >
+              Delete everywhere
+            </button>
+            <button
+              type="button"
+              className="btn btn-sm btn-outline-secondary"
+              disabled={busy}
+              title="Removes the entry on this device only. Other devices keep theirs."
+              onClick={() => onRun(entry, "ignoreLocal")}
+            >
+              Ignore on this device
+            </button>
+          </div>
+        </td>
+      </tr>
+      {(errorOpen || recordOpen) && (
+        <tr>
+          <td colSpan={7} className="bg-body-tertiary">
+            {errorOpen && (
+              <pre className="small mb-0 font-monospace" style={detailsBlockStyle}>
+                {formatError(entry.latestError)}
+              </pre>
+            )}
+            {recordOpen && (
+              <div className={errorOpen ? "mt-3" : undefined}>
+                {entry.changeCreatedAt != null && (
+                  <p className="small mb-2">Change written {formatWhen(entry.changeCreatedAt)}</p>
+                )}
+                {entry.conflictingRecordId && (
+                  <p className="small mb-2">
+                    Another record holds the same unique value:{" "}
+                    <code>{entry.conflictingRecordId}</code>
+                  </p>
+                )}
+                {entry.tombstoneRecordId &&
+                  entry.tombstoneRecordId === entry.conflictingRecordId && (
+                    <p className="small mb-2">
+                      Keep deletes <code>{entry.tombstoneRecordId}</code> on every device.
+                    </p>
+                  )}
+                {entry.tombstoneRecordId && entry.tombstoneRecordId === entry.recordId && (
+                  <p className="small mb-2">
+                    Keep snapshots the other record and tombstones this queued id.
+                  </p>
+                )}
+                {entry.keptRecordPreview && (
+                  <>
+                    <p className="small mb-1">This device's version</p>
+                    <pre className="small mb-2 font-monospace" style={detailsBlockStyle}>
+                      {entry.keptRecordPreview}
+                    </pre>
+                  </>
+                )}
+                {entry.queuedRecordPreview && (
+                  <>
+                    <p className="small mb-1">Queued change</p>
+                    <pre className="small mb-0 font-monospace" style={detailsBlockStyle}>
+                      {entry.queuedRecordPreview}
+                    </pre>
+                  </>
+                )}
+                {!entry.keptRecordPreview && !entry.queuedRecordPreview && entry.recordPreview && (
+                  <pre className="small mb-0 font-monospace" style={detailsBlockStyle}>
+                    {entry.recordPreview}
+                  </pre>
+                )}
+                {!entry.keptRecordPreview && !entry.queuedRecordPreview && !entry.recordPreview && (
+                  <p className="small text-muted mb-0">
+                    This device has no stored copy of the record. The latest error may still quote
+                    the rejected value.
+                  </p>
+                )}
+              </div>
+            )}
+          </td>
+        </tr>
+      )}
+    </>
+  );
+}
+
+/** Lists recovery-queue entries and the actions that resolve them. */
+export function SyncRecoveryScreen({ onBack }: ISyncRecoveryScreenProps) {
+  const [entries, setEntries] = useState<INetworkSyncRecoveryEntry[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [busyKey, setBusyKey] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const loadGeneration = useRef(0);
+
+  const load = useCallback(async (preserveError = false) => {
+    const generation = ++loadGeneration.current;
+    try {
+      const diagnostics = await getNetworkDiagnosticsConsumer();
+      const result = await diagnostics.tools.getSyncRecoveryEntries();
+      if (generation !== loadGeneration.current) {
+        return;
+      }
+      setEntries(result.entries);
+      if (!preserveError) {
+        setError(null);
+      }
+    } catch (loadError) {
+      if (generation !== loadGeneration.current) {
+        return;
+      }
+      setError(loadError instanceof Error ? loadError.message : String(loadError));
+    } finally {
+      if (generation === loadGeneration.current) {
+        setLoading(false);
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  useEffect(() => {
+    let active = true;
+    let subscription: { dispose(): void } | undefined;
+    void getNetworkDiagnosticsConsumer().then((diagnostics) => {
+      if (!active) {
+        return;
+      }
+      subscription = diagnostics.observables?.status.subscribe(() => {
+        void load();
+      });
+    });
+    return () => {
+      active = false;
+      subscription?.dispose();
+    };
+  }, [load]);
+
+  const run = async (
+    entry: INetworkSyncRecoveryEntry,
+    action: "retry" | SyncRecoveryResolution,
+  ) => {
+    if (action === "deleteEverywhere") {
+      const confirmed = window.confirm(
+        `Delete ${entry.tableName}/${entry.recordId} on every device? This writes a synced delete.`,
+      );
+      if (!confirmed) {
+        return;
+      }
+    }
+    const key = `${entry.dataContextId}:${entry.syncRecoveryId}:${action}`;
+    setBusyKey(key);
+    setError(null);
+    try {
+      const control = await getNetworkControlConsumer();
+      const result =
+        action === "retry"
+          ? await control.tools.retrySyncRecovery({
+              dataContextId: entry.dataContextId,
+              tableName: entry.tableName,
+              recordId: entry.recordId,
+              syncRecoveryId: entry.syncRecoveryId,
+            })
+          : await control.tools.resolveSyncRecovery({
+              dataContextId: entry.dataContextId,
+              tableName: entry.tableName,
+              recordId: entry.recordId,
+              resolution: action,
+              syncRecoveryId: entry.syncRecoveryId,
+            });
+      if (!result.success) {
+        setError(result.message);
+        await load(true);
+      } else {
+        setError(null);
+        await load();
+      }
+    } catch (actionError) {
+      setError(actionError instanceof Error ? actionError.message : String(actionError));
+    } finally {
+      setBusyKey(null);
+    }
+  };
+
+  if (loading) {
+    return <LoadingIndicator />;
+  }
+
+  const groups = new Map<string, INetworkSyncRecoveryEntry[]>();
+  for (const entry of entries) {
+    const group = groups.get(entry.dataContextId) ?? [];
+    group.push(entry);
+    groups.set(entry.dataContextId, group);
+  }
+
+  return (
+    <div className="container-fluid p-4">
+      <div className="d-flex justify-content-between align-items-center mb-3">
+        <div className="d-flex align-items-center gap-3">
+          <button type="button" className="btn btn-sm btn-outline-secondary" onClick={onBack}>
+            <i className="bi bi-arrow-left me-1" />
+            Back
+          </button>
+          <div>
+            <h2 className="mb-1">Sync recovery</h2>
+            <p className="text-muted small mb-0">
+              These records have change history, but this device could not write the row. Parked
+              entries are not asked of other devices until you retry them.
+            </p>
+          </div>
+        </div>
+        <button type="button" className="btn btn-sm btn-primary" onClick={() => void load()}>
+          Refresh
+        </button>
+      </div>
+      {error && <div className="alert alert-danger py-2 small">{error}</div>}
+      {entries.length === 0 ? (
+        <div className="alert alert-success">No records are waiting in the recovery queue.</div>
+      ) : (
+        [...groups.entries()].map(([dataContextId, groupEntries]) => (
+          <div key={dataContextId} className="card mb-3">
+            <div className="card-header">{groupEntries[0]?.dataContextName || dataContextId}</div>
+            <div className="table-responsive">
+              <table className="table table-sm align-middle mb-0">
+                <thead>
+                  <tr>
+                    <th>Table</th>
+                    <th>Record</th>
+                    <th>First failed</th>
+                    <th>Attempts</th>
+                    <th>Status</th>
+                    <th>Latest error</th>
+                    <th>
+                      Actions
+                      <InfoTip label="About these actions">
+                        <ul className="mb-0 ps-3">
+                          <li>
+                            <strong>Retry</strong> writes the record again from this device's
+                            history, then asks another device once. If a schema or unique-key entry
+                            is still queued after that, it is parked again. Use it after an upgrade
+                            that might accept a row this device rejected before.
+                          </li>
+                          <li>
+                            <strong>Keep this device's version</strong> snapshots the row this
+                            device will keep. That is the queued row when it is already stored here,
+                            and otherwise the other row that holds the same unique value. When both
+                            rows are stored, the other record is deleted everywhere. When only the
+                            other row is stored, that row is kept and this queued id is tombstoned.
+                            Disabled when this device has no row to keep.
+                          </li>
+                          <li>
+                            <strong>Delete everywhere</strong> deletes this record on every device,
+                            including devices that already have it.
+                          </li>
+                          <li>
+                            <strong>Ignore on this device</strong> removes the entry here only.
+                            Other devices keep their own copy of the problem.
+                          </li>
+                        </ul>
+                      </InfoTip>
+                    </th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {groupEntries.map((entry) => (
+                    <RecoveryRows
+                      key={entry.syncRecoveryId}
+                      entry={entry}
+                      busy={Boolean(
+                        busyKey?.startsWith(`${entry.dataContextId}:${entry.syncRecoveryId}:`),
+                      )}
+                      onRun={(item, action) => void run(item, action)}
+                    />
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}