Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

24.7 KB
Raw Blame
/**
 * Scoping browser-persisted UI state to the data root it was made against.
 *
 * The report this exists for: a user deleted their data files, restarted, and the app came
 * back with the old Workspace still selected. `localStorage` has no relationship to the
 * data root at all — in the desktop app it lives in Electron's userData directory, so no
 * amount of deleting `PENGUIN_HOME` touches it — and every key that names an entity names
 * it with a compile-time constant (`admin`, `default_project`). A wipe-and-restart
 * re-provisions the same user and the same Project, the keys line up again, and the old
 * draft, Workspace registry, pins and seen markers all come back.
 *
 * So the server names its root (`<root>/install-id`, served by `GET /api/install`) and this
 * module compares that name against the one this browser last saw. A DIFFERENT name means
 * the state here was made against a root that is gone, and the keys that reference server
 * entities are cleared. Same name — including every ordinary restart — clears nothing.
 *
 * Why one stored id and a sweep, rather than putting the id into every key name:
 *   - key names stay as they are, so no module that builds a key changes and there is no
 *     migration for keys already on disk;
 *   - a key carrying a dead install id would be an orphan nothing ever reads or deletes,
 *     and each wipe would leave another full set behind. The sweep is the one place
 *     orphans are collected, and it collects them by walking the store;
 *   - the classification below stays readable as a table instead of being spread across
 *     twenty call sites.
 *
 * TWO THINGS THE SWEEP ALONE DOES NOT COVER, both of them a live copy of state the store no
 * longer holds:
 *   - modules evaluated before the sweep ran (the whole static import graph finishes before
 *     main.tsx's first statement) — a swept boot RELOADS rather than renders, see
 *     bootInstallScope;
 *   - other tabs, still open against the root that is gone — see watchInstallScope.
 *
 * FIRST SIGHT (a browser with keys but no stored id — every user upgrading into this
 * release) is indistinguishable from a wiped root, so it ADOPTS the current id and sweeps
 * nothing. Destroying legitimate state on upgrade would be a far worse bug than the one
 * being fixed. The practical consequence, which the changelog states plainly: state that is
 * ALREADY stale when this ships stays stale; only wipes from here on are handled.
 */
import * as api from "../api/endpoints";

/** Where this browser records the data root it last saw. Never swept — it IS the marker. */
export const INSTALL_ID_KEY = "penguin.installId";

/**
 * What a stored key is tied to.
 *
 * - `install` — it references server-side entities (Session ids, Agent ids, Workspace
 *   paths, Project ids, terminal ids, provider group names) that a new data root does not
 *   have. Against a new root it is at best inert and at worst a lie, which is the bug.
 * - `browser` — a display or input preference of this browser. It names nothing on the
 *   server, so a new root can honour it exactly as the old one did, and wiping a data root
 *   is not a request to reset someone's theme.
 */
export type KeyScope = "install" | "browser";

/**
 * One classification rule. `kind: "exact"` matches the key itself; `kind: "family"` matches
 * a key prefix that ends in `.` and covers every id-suffixed key under it.
 *
 * Plain prefix matching would be wrong twice over, which is why the distinction exists:
 * `penguin.sidebarCollapsed` (a preference) is a prefix of
 * `penguin.sidebarCollapsedGroups.<projectId>` (install-scoped), and `penguin.terminal.`
 * covers both `penguin.terminal.theme` (a preference) and `penguin.terminal.page.id`
 * (a terminal id).
 */
export interface KeyRule {
  kind: "exact" | "family";
  key: string;
  scope: KeyScope;
  /** Why this scope — one line, kept next to the rule so the two cannot drift apart. */
  why: string;
}

/**
 * Every `penguin.*` key the web app persists in `localStorage`, classified.
 *
 * ADDING A KEY: add it here too. An unclassified key is left alone by the sweep (never
 * deleting something we do not understand is the safe default), so a forgotten
 * install-scoped key silently reintroduces the bug this module fixes. That is enforced
 * rather than asked for: install-scope.test.ts scans `packages/web/src` for key literals and
 * fails on any this table does not cover.
 *
 * Two `penguin.*` strings in the source are NOT here on purpose:
 *   - `penguin.chatRouteApplied.<field>` (features/chat/draft-view.tsx) is `sessionStorage`,
 *     not `localStorage`: it is scoped to one tab's history and dies with the tab, so it
 *     cannot outlive a data root.
 *   - `penguin.ooo` (the shared UI package's remark-autolink-boundary.ts) is the product's
 *     domain inside an example URL in a doc comment. It is not a storage key.
 */
export const KEY_RULES: readonly KeyRule[] = [
  // ---------------------------------------------------------------- browser preferences
  {
    kind: "exact",
    key: "penguin.theme",
    scope: "browser",
    why: "Colour-scheme choice for this browser; names nothing on the server.",
  },
  {
    kind: "exact",
    key: "penguin.themeId",
    scope: "browser",
    why: "Which theme renders the app (the key lives in @adelie/ui/boot); pure appearance.",
  },
  {
    kind: "exact",
    key: "penguin.textSize",
    scope: "browser",
    why: "Root text size (five steps) — a readability preference of this display.",
  },
  {
    kind: "exact",
    key: "penguin.fontScale",
    scope: "browser",
    why: "The three-step text size of earlier releases; read once, migrated to penguin.textSize and removed.",
  },
  {
    kind: "exact",
    key: "penguin.fontLatin",
    scope: "browser",
    why: "Latin font face chosen over the theme's own; pure appearance.",
  },
  {
    kind: "exact",
    key: "penguin.fontCjk",
    scope: "browser",
    why: "CJK font face chosen over the theme's own; pure appearance.",
  },
  {
    kind: "exact",
    key: "penguin.accent",
    scope: "browser",
    why: "Accent colour; pure appearance.",
  },
  {
    kind: "exact",
    key: "penguin.currency",
    scope: "browser",
    why: "Display currency for prices; a formatting choice, prices are stored in USD either way.",
  },
  {
    kind: "exact",
    key: "penguin.toolAliases",
    scope: "browser",
    why: "Whether tool cards name the built-in tools by their short alias; a display choice of this browser, naming nothing on the server.",
  },
  {
    kind: "exact",
    key: "penguin.sseFrames",
    scope: "browser",
    why: "Whether the Trace panel's Transport view records SSE frames; a debugging instrument of this browser, naming nothing on the server.",
  },
  {
    kind: "exact",
    key: "penguin.terminal.theme",
    scope: "browser",
    why: "Terminal appearance pin (light/dark/follow-app); appearance only.",
  },
  {
    kind: "exact",
    key: "penguin.lang",
    scope: "browser",
    why: "UI language — the one preference a user would be most annoyed to lose.",
  },
  {
    kind: "exact",
    key: "penguin.sidebarCollapsed",
    scope: "browser",
    why: "Whether the sidebar is a narrow rail; chrome layout, holds no entity.",
  },
  {
    kind: "exact",
    key: "penguin.panelWidth",
    scope: "browser",
    why: "Side-panel width in px; its own module calls it a layout preference, not session data.",
  },
  {
    kind: "exact",
    key: "penguin.dock.launcherY",
    scope: "browser",
    why: "Where the floating dock launcher rests along the chat body's edge; chrome layout, holds no entity.",
  },
  {
    kind: "exact",
    key: "penguin.dock.launcherHidden",
    scope: "browser",
    why: "Whether the floating dock launcher shows at all; an appearance choice of this browser, and losing it would put a dismissed button back.",
  },
  {
    kind: "exact",
    key: "penguin.files.treeVisible",
    scope: "browser",
    why: "Whether the Files panel shows its directory tree beside the preview; chrome layout, holds no entity.",
  },
  {
    kind: "exact",
    key: "penguin.files.treeWidth",
    scope: "browser",
    why: "How wide that tree pane was dragged, in px; the same layout preference, one axis over.",
  },
  {
    kind: "exact",
    key: "penguin.files.editorWrap",
    scope: "browser",
    why: "Whether the Files panel's editor soft-wraps long lines; a reading habit, valid against any root.",
  },
  {
    kind: "exact",
    key: "penguin.sidebarGroupMode",
    scope: "browser",
    why: "Group sessions by Workspace/Agent/time — the MODE, not the groups; valid against any root.",
  },
  {
    kind: "exact",
    key: "penguin.sidebarSortMode",
    scope: "browser",
    why: "Recent vs manual ordering — again the mode; the manual order itself is separate and install-scoped.",
  },
  {
    kind: "exact",
    key: "penguin.sidebarNavGroupCollapsed",
    scope: "browser",
    why: "Whether the static page-nav group is folded; the nav is built from a compile-time manifest.",
  },
  {
    kind: "exact",
    key: "penguin.sidebarNavPinned",
    scope: "browser",
    why: "Which nav entries stay out of the fold; keyed by the compile-time manifest, names nothing on the server.",
  },
  {
    kind: "exact",
    key: "penguin.steerMode",
    scope: "browser",
    why: "Steer vs queue-as-follow-up when sending mid-run; a per-user input habit.",
  },
  {
    kind: "exact",
    key: "penguin.notifications",
    scope: "browser",
    why: "Whether task-completion notifications were asked for; it pairs with an OS permission that belongs to this browser rather than to any data root, and clearing it would silently stop notifications the user opted into.",
  },

  // --------------------------------------------------------------- install-scoped state
  {
    kind: "family",
    key: "penguin.chatDraft.",
    scope: "install",
    why: "The new-chat and per-Session drafts: Workspace path, Agent id, model ref, Session id in the key. The reported bug.",
  },
  {
    kind: "family",
    key: "penguin.chatDrafts.",
    scope: "install",
    why: "Parked draft conversations — the same contents as an active draft, kept as a list.",
  },
  {
    kind: "family",
    key: "penguin.channelDraft.",
    scope: "install",
    why: "A channel composer's unsent text, keyed by user, Project, organization and channel — all four name things that live in one data root.",
  },
  {
    kind: "family",
    key: "penguin.sidebarWorkspaces.",
    scope: "install",
    why: "Manually registered Workspace paths per Project; a new root has no such Project.",
  },
  {
    kind: "family",
    key: "penguin.finderQuickAccess.",
    scope: "install",
    why: "Folders added to and removed from the Workspace finder's Quick access, keyed by machine id and holding paths on the machines of this root — the same kind of state as the registered Workspace paths.",
  },
  {
    kind: "family",
    key: "penguin.pinnedSessions.",
    scope: "install",
    why: "Pinned Session ids.",
  },
  {
    kind: "family",
    key: "penguin.machineSessions.",
    scope: "install",
    why: "The Sessions each machine was last seen holding, shown until its connection is held again. Project id and machine id in the key, Session ids in the value — a new root knows none of them.",
  },
  {
    kind: "exact",
    key: "penguin.sandboxBackendPromptDismissed",
    scope: "install",
    why: "The machines whose Sandbox card no longer offers to install a backend — machine ids of this root.",
  },
  {
    kind: "family",
    key: "penguin.machineAgents.",
    scope: "install",
    why: "The Agents each machine was last seen running, offered by the composer until its connection is held again. Keyed by the same Project and machine a new root would not have.",
  },
  {
    kind: "family",
    key: "penguin.sessionOrder.",
    scope: "install",
    why: "Manual Session order — an array of Session ids.",
  },
  {
    kind: "family",
    key: "penguin.sessionSeen.",
    scope: "install",
    why: "Read markers keyed by Session id; against a new root every Session is new by definition.",
  },
  {
    kind: "family",
    key: "penguin.groupOrder.",
    scope: "install",
    why: "Manual group order — group keys are Agent ids and Workspace paths.",
  },
  {
    kind: "family",
    key: "penguin.sidebarCollapsedGroups.",
    scope: "install",
    why: "Collapsed sidebar groups, keyed by those same Agent ids and Workspace paths.",
  },
  {
    kind: "family",
    key: "penguin.sidebarExpandedFolderGroups.",
    scope: "install",
    why: "Folder-only sidebar groups the user opened, keyed by those same Agent ids and Workspace paths.",
  },
  {
    kind: "family",
    key: "penguin.sidebarPinnedGroups.",
    scope: "install",
    why: "Pinned sidebar groups, same key space.",
  },
  {
    kind: "exact",
    key: "penguin.lastProjectId",
    scope: "install",
    why: "The Project id last selected.",
  },
  {
    kind: "exact",
    key: "penguin.workMode",
    scope: "browser",
    why: "Development vs company mode — the MODE, mirrored from ui_prefs; valid against any root.",
  },
  {
    kind: "exact",
    key: "penguin.keybindings",
    scope: "browser",
    why: "The account's shortcut overrides, mirrored from ui_prefs for the first keystroke and for cross-tab sync; names nothing on the server, and the server copy is the truth.",
  },
  {
    kind: "exact",
    key: "penguin.companyBetaNoticeShown",
    scope: "browser",
    why: "That company mode's beta notice has been shown in this browser; it names nothing on the server, and a wipe is not a request to show it again.",
  },
  {
    kind: "exact",
    key: "penguin.lastOrgKey",
    scope: "install",
    why: "The organization last opened in company mode, as <projectId>/<orgId> of this root.",
  },
  {
    kind: "family",
    key: "penguin.orgCreateDraft.",
    scope: "install",
    why: "An unsubmitted create-organization form, keyed by user and Project id and holding a Workspace path and model ref of this root.",
  },
  {
    kind: "family",
    key: "penguin.orgPageHint.",
    scope: "install",
    why: "A dismissed empty-page note, keyed by user, Project and organization id of this root.",
  },
  {
    kind: "family",
    key: "penguin.orgTempSessions.",
    scope: "install",
    why: "The company sidebar's Temporary group of ticket sessions, keyed by user, Project and organization id and naming Sessions and Agents of this root.",
  },
  {
    kind: "family",
    key: "penguin.lastAgentId.",
    scope: "install",
    why: "The Agent id last selected, per Project.",
  },
  {
    kind: "family",
    key: "penguin.memoryCollapsed.",
    scope: "install",
    why: "Collapsed Memory scopes, keyed by user x Project x Agent and holding scope keys.",
  },
  {
    kind: "family",
    key: "penguin.modelsExpandedGroups.",
    scope: "install",
    why: "Expanded provider groups of a Project's model table; includes user-defined group names that live in that Project's config.",
  },
  {
    kind: "family",
    key: "penguin.modelsGroupOrder.",
    scope: "install",
    why: "Manual order of those same per-Project provider groups.",
  },
  {
    kind: "exact",
    key: "penguin.dock.layout",
    scope: "install",
    why: "Dock tab arrangements keyed by conversation, holding Session ids and terminal ids.",
  },
  {
    kind: "exact",
    key: "penguin.terminal.page.id",
    scope: "install",
    why: "The terminal (shell) id the standalone terminal page reattaches to.",
  },
];

/**
 * The scope of a stored key, or null when no rule covers it. Exact rules are consulted
 * first so a preference is never captured by a family it merely shares a stem with.
 */
export function scopeOfKey(key: string): KeyScope | null {
  for (const rule of KEY_RULES) {
    if (rule.kind === "exact" && rule.key === key) return rule.scope;
  }
  for (const rule of KEY_RULES) {
    if (rule.kind === "family" && key.startsWith(rule.key)) return rule.scope;
  }
  return null;
}

/**
 * The subset of `localStorage` this module uses. Enumeration (`length` + `key`) is what
 * lets one rule cover every id-suffixed key under it and clean up orphans left by earlier
 * roots. Tests inject an in-memory implementation — vitest runs in Node, with no DOM
 * (the model-group-expansion.ts convention).
 */
export interface InstallScopeStorage {
  readonly length: number;
  key(index: number): string | null;
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
}

/**
 * What one boot's comparison did.
 *
 * - `unknown` — no id to compare (the server could not establish one, or the request
 *   failed). Nothing read, nothing written, nothing removed.
 * - `adopted` — this browser had no id recorded. First sight; the id is stored and nothing
 *   is swept.
 * - `unchanged` — same root as last time. The ordinary case, including every restart.
 * - `swept` — a different root. Install-scoped keys removed, preferences kept, and the new
 *   id recorded, so the next load is an ordinary `unchanged` one.
 * - `swept-unrecorded` — the same removal, except the new id could not be written back
 *   (quota, blocked site data), so the next load compares and sweeps again. Split from
 *   `swept` for one reason: `swept` reloads the page (bootInstallScope) and this one must
 *   not, or every pass would sweep, fail to record, and reload again.
 */
export type InstallScopeResult = "unknown" | "adopted" | "unchanged" | "swept" | "swept-unrecorded";

/** Reads one key, treating a throwing store as empty (blocked site data, partitioned iframe). */
function read(storage: InstallScopeStorage, key: string): string | null {
  try {
    return storage.getItem(key);
  } catch {
    return null;
  }
}

/**
 * Removes every install-scoped key. Keys are collected before anything is removed:
 * `removeItem` renumbers the store, so deleting during the walk would skip entries.
 * Returns the keys removed (the caller logs the count; tests assert on it).
 */
function sweep(storage: InstallScopeStorage): string[] {
  const doomed: string[] = [];
  try {
    for (let i = 0; i < storage.length; i += 1) {
      const key = storage.key(i);
      if (key !== null && scopeOfKey(key) === "install") doomed.push(key);
    }
  } catch {
    return [];
  }
  const removed: string[] = [];
  for (const key of doomed) {
    try {
      storage.removeItem(key);
      removed.push(key);
    } catch {
      /* best-effort: a key that refuses to go is swept again on the next load */
    }
  }
  return removed;
}

/**
 * Compares the server's install id against the one this browser recorded, and acts on the
 * difference. Pure with respect to everything but the store, so the whole decision table is
 * testable without a DOM.
 *
 * `installId` of null means the server could not establish one; that is "unknown", never
 * "new", so nothing is touched. The sweep runs BEFORE the id is stored: if the write fails
 * (quota, private browsing) the next load repeats the comparison and sweeps again, which is
 * idempotent — whereas recording an id we had not finished acting on would not be.
 */
export function reconcileInstallScope(
  installId: string | null,
  storage: InstallScopeStorage,
): InstallScopeResult {
  if (installId === null) return "unknown";
  const stored = read(storage, INSTALL_ID_KEY);
  if (stored === installId) return "unchanged";

  const swept = stored !== null;
  if (swept) sweep(storage);
  try {
    storage.setItem(INSTALL_ID_KEY, installId);
  } catch {
    /* best-effort: unrecorded means the next load compares again, which is harmless */
  }
  if (!swept) return "adopted";
  // Read the marker BACK rather than trust the write: a swept boot reloads, and a sweep
  // whose marker did not stick would sweep, fail to record and reload again on every pass.
  return read(storage, INSTALL_ID_KEY) === installId ? "swept" : "swept-unrecorded";
}

/** How long to wait for the identity before rendering anyway — see syncInstallScope. */
const INSTALL_ID_TIMEOUT_MS = 3000;

/**
 * Asks the server for this data root's identity and reconciles the browser's state against
 * it. Never rejects and never throws: a boot step that can break the whole app is worse
 * than the surprise it prevents.
 *
 * Bounded by a timeout because the caller renders nothing until this settles. The page's
 * own HTML came from this same server milliseconds earlier, so an answer that takes longer
 * than three seconds means something is badly wrong — and in that state showing the app
 * with unswept state beats showing a blank page. Giving up resolves to `unknown`, which
 * changes nothing; the next load tries again.
 */
export async function syncInstallScope(storage?: InstallScopeStorage): Promise<InstallScopeResult> {
  let installId: string | null = null;
  try {
    const timeout = new Promise<null>((resolve) => {
      setTimeout(() => resolve(null), INSTALL_ID_TIMEOUT_MS);
    });
    const answered = await Promise.race([api.getInstall().then((res) => res.installId), timeout]);
    installId = answered;
  } catch {
    // A server that cannot answer is one we cannot identify: sweep nothing.
    return "unknown";
  }
  try {
    // `localStorage` is resolved INSIDE the try, never as a default parameter: merely
    // touching it throws a SecurityError when site data is blocked (the convention every
    // storage module here follows).
    return reconcileInstallScope(installId, storage ?? localStorage);
  } catch {
    return "unknown";
  }
}

/** What the boot does with the page once this browser's state has been reconciled. */
export type BootAction = "mount" | "reload";

/**
 * The whole pre-mount step as one call: ask the server for the data root's identity,
 * reconcile this browser's stored state against it, and say whether the page may render or
 * has to start over.
 *
 * A RECORDED SWEEP RELOADS. ES module evaluation of the entire static import graph finishes
 * before main.tsx's first statement runs, so a module that reads `localStorage` at module
 * scope — features/dock/dock-state.ts parses `penguin.dock.layout` into module state there —
 * is already holding a copy of keys the sweep then deletes, and its first write puts the
 * whole map back. The id matches by then, so nothing ever sweeps it again and the
 * resurrection is permanent. A reload re-evaluates every module against the cleaned store
 * and the second pass reconciles to `unchanged`. Making that one module lazy would fix that
 * one module and leave the class open for the next one; this holds however the import graph
 * grows, and it costs one extra load only when the data root was actually replaced.
 *
 * `swept-unrecorded` deliberately mounts: reloading on a sweep whose marker did not stick
 * would sweep, fail to record and reload again, forever.
 */
export async function bootInstallScope(storage?: InstallScopeStorage): Promise<BootAction> {
  return (await syncInstallScope(storage)) === "swept" ? "reload" : "mount";
}

/** The `storage` event fields the cross-tab decision needs (tests pass a plain object). */
export interface InstallIdChange {
  key: string | null;
  oldValue: string | null;
  newValue: string | null;
}

/**
 * What another tab's `storage` event means here, and whether this tab must reload.
 *
 * The sweep runs once per page load, so a tab that was ALREADY open when a second tab
 * recognised the new root still holds the old root's state in module and component memory
 * and writes it back on the next pin, reorder or draft keystroke — restoring keys the other
 * tab removed, under an id that now matches and will never be swept again. A `storage` event
 * fires in every OTHER tab of this origin, which is exactly the set that has to hear about
 * it: sweep whatever this tab has already put back, and report that it must reload, so no
 * live copy survives to write it a second time.
 *
 * Only an id REPLACED by a different id is a root that was wiped. A first recording
 * (`oldValue` null) is that tab's adoption, which swept nothing; a removal (`newValue` null)
 * is site data being cleared, which the next load adopts from scratch. Neither concerns the
 * state held here.
 */
export function reactToInstallIdChange(
  change: InstallIdChange,
  storage: InstallScopeStorage,
): boolean {
  if (change.key !== INSTALL_ID_KEY) return false;
  if (change.oldValue === null || change.newValue === null) return false;
  if (change.oldValue === change.newValue) return false;
  sweep(storage);
  return true;
}

/**
 * Wires reactToInstallIdChange to this browser's cross-tab `storage` events for the life of
 * the page. A no-op where there is no window (tests, prerendering).
 */
export function watchInstallScope(storage?: InstallScopeStorage): void {
  if (typeof window === "undefined") return;
  window.addEventListener("storage", (event) => {
    let stale = false;
    try {
      // `localStorage` is resolved INSIDE the try for the same reason syncInstallScope does.
      stale = reactToInstallIdChange(event, storage ?? localStorage);
    } catch {
      return; // blocked site data: there was nothing readable to restore either
    }
    if (stale) location.reload();
  });
}