@hienlh/ppm 0.23.7 → 0.23.8

package/src/web/lib/browser-cache/idb-keyval-cache.ts

@@ -0,0 +1,249 @@
+/**
+ * Minimal key/value cache over IndexedDB, with an in-memory `Map` fallback
+ * for whenever IndexedDB is missing (module scope under `bun:test`, private
+ * browsing, storage disabled) or a call to it fails.
+ *
+ * One database (`ppm-cache`), one store (`kv`), a **fixed** version — this
+ * cache never needs a schema migration, because every value is wrapped in an
+ * envelope carrying its own `SCHEMA_VERSION`. An envelope written by an older
+ * build simply reads back as a miss and gets overwritten on the next write;
+ * the database itself is never deleted or reopened at a new version.
+ *
+ * Every export here is async and never throws — a caller that cannot read or
+ * write this cache should silently fall through to a network fetch, not
+ * break the feature it is speeding up.
+ */
+
+const DB_NAME = "ppm-cache";
+const STORE_NAME = "kv";
+const DB_VERSION = 1;
+
+/** Bump this when a cached value's shape changes. Older envelopes are then
+ * misses rather than being read (and possibly mis-parsed) as the new shape. */
+export const SCHEMA_VERSION = 1;
+
+interface Envelope<T> {
+  v: number;
+  at: number;
+  data: T;
+}
+
+/** Backing store used whenever IndexedDB is unavailable. Also the only store
+ * a `bun:test` process ever reaches, since no test runtime provides `indexedDB`. */
+const memoryStore = new Map<string, Envelope<unknown>>();
+
+/** How long an open may stay unanswered before this page gives up on
+ * IndexedDB and uses the memory store instead. An open that another tab
+ * blocks, or that a broken profile never settles, would otherwise hang every
+ * caller that awaits it — including the session list's first sync. */
+const OPEN_TIMEOUT_MS = 1500;
+let openTimeoutMs = OPEN_TIMEOUT_MS;
+
+let dbPromise: Promise<IDBDatabase | null> | null = null;
+
+/** Opens (once) and memoizes the database handle. Resolves `null` — never
+ * rejects, never hangs past `openTimeoutMs` — on any failure, so every
+ * operation below can treat "no IndexedDB" and "IndexedDB open failed" the
+ * same way: fall back to `memoryStore`.
+ *
+ * Even reading the `indexedDB` global sits inside the `try`: in a sandboxed or
+ * cookie-blocked context it is a getter that throws `SecurityError`, and a
+ * throw from the executor would reject — and memoize — the promise. */
+function openDb(): Promise<IDBDatabase | null> {
+  if (dbPromise) return dbPromise;
+  const attempt = new Promise<IDBDatabase | null>((resolve) => {
+    let settled = false;
+    const finish = (db: IDBDatabase | null) => {
+      if (settled) {
+        // Answered after the timeout already fell back — nobody holds this handle.
+        db?.close();
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve(db);
+    };
+    const timer = setTimeout(() => finish(null), openTimeoutMs);
+    try {
+      if (typeof indexedDB === "undefined" || !indexedDB) {
+        finish(null);
+        return;
+      }
+      const req = indexedDB.open(DB_NAME, DB_VERSION);
+      req.onupgradeneeded = () => {
+        try {
+          if (!req.result.objectStoreNames.contains(STORE_NAME)) {
+            req.result.createObjectStore(STORE_NAME);
+          }
+        } catch {
+          finish(null);
+        }
+      };
+      req.onsuccess = () => {
+        const db = req.result;
+        // A closed handle fails every later transaction, so forget it: the
+        // next call reopens (or falls back) instead of reusing a dead one.
+        const forget = () => { if (dbPromise === attempt) dbPromise = null; };
+        // Another tab upgraded (or deleted) the database — release it so that
+        // tab is not blocked, then let the next call reopen.
+        db.onversionchange = () => { db.close(); forget(); };
+        db.onclose = forget;
+        finish(db);
+      };
+      req.onerror = () => finish(null);
+      // Another tab holds the database open at an older version and will not
+      // let go; waiting on it would hang this page's first read indefinitely.
+      req.onblocked = () => finish(null);
+    } catch {
+      finish(null);
+    }
+  });
+  dbPromise = attempt;
+  return attempt;
+}
+
+/**
+ * Forgets the memoized handle so the next call reopens, optionally with a
+ * shorter open timeout. Tests only: each test installs its own fake
+ * `indexedDB` and needs this module to look at it afresh.
+ */
+export function __resetIdbForTest(timeoutMs: number = OPEN_TIMEOUT_MS): void {
+  dbPromise = null;
+  openTimeoutMs = timeoutMs;
+  memoryStore.clear();
+}
+
+/** A cached value together with when it was written (epoch ms). */
+export interface IdbEntry<T> {
+  data: T;
+  at: number;
+}
+
+function readEnvelope<T>(env: Envelope<T> | undefined): IdbEntry<T> | undefined {
+  if (!env || env.v !== SCHEMA_VERSION) return undefined;
+  return { data: env.data, at: typeof env.at === "number" ? env.at : 0 };
+}
+
+/** Like `idbGet`, but also says how old the value is — for a caller that shows
+ * cached data immediately yet must still know whether to refresh it. */
+export async function idbGetEntry<T>(key: string): Promise<IdbEntry<T> | undefined> {
+  const db = await openDb();
+  if (!db) return readEnvelope(memoryStore.get(key) as Envelope<T> | undefined);
+  try {
+    const env = await new Promise<Envelope<T> | undefined>((resolve) => {
+      const req = db.transaction(STORE_NAME, "readonly").objectStore(STORE_NAME).get(key);
+      req.onsuccess = () => resolve(req.result as Envelope<T> | undefined);
+      req.onerror = () => resolve(undefined);
+    });
+    return readEnvelope(env);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function idbGet<T>(key: string): Promise<T | undefined> {
+  return (await idbGetEntry<T>(key))?.data;
+}
+
+export async function idbSet<T>(key: string, data: T): Promise<void> {
+  const envelope: Envelope<T> = { v: SCHEMA_VERSION, at: Date.now(), data };
+  const db = await openDb();
+  if (!db) {
+    memoryStore.set(key, envelope as Envelope<unknown>);
+    return;
+  }
+  try {
+    await new Promise<void>((resolve) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      tx.objectStore(STORE_NAME).put(envelope, key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => resolve();
+      tx.onabort = () => resolve();
+    });
+  } catch {
+    // A write we cannot make durable is not worth surfacing — the next read
+    // just misses and falls back to a fresh fetch.
+  }
+}
+
+export async function idbDelete(key: string): Promise<void> {
+  const db = await openDb();
+  if (!db) {
+    memoryStore.delete(key);
+    return;
+  }
+  try {
+    await new Promise<void>((resolve) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      tx.objectStore(STORE_NAME).delete(key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => resolve();
+      tx.onabort = () => resolve();
+    });
+  } catch {
+    // ignore
+  }
+}
+
+/** Deletes every key that starts with `prefix` — how a project's cache
+ * entries (all sharing its `projectCacheId` prefix) are evicted together on
+ * rename/delete/wipe, without the caller enumerating individual keys. */
+export async function idbDeletePrefix(prefix: string): Promise<void> {
+  const db = await openDb();
+  if (!db) {
+    for (const key of [...memoryStore.keys()]) {
+      if (key.startsWith(prefix)) memoryStore.delete(key);
+    }
+    return;
+  }
+  try {
+    await new Promise<void>((resolve) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      const store = tx.objectStore(STORE_NAME);
+      // String keys sort by UTF-16 code unit in IndexedDB, same as JS — so a
+      // range bounded by the prefix and the prefix plus the highest BMP code
+      // unit covers exactly the keys that start with it.
+      const range = IDBKeyRange.bound(prefix, prefix + "￿");
+      const req = store.openCursor(range);
+      req.onsuccess = () => {
+        const cursor = req.result;
+        if (cursor) {
+          cursor.delete();
+          cursor.continue();
+        }
+      };
+      req.onerror = () => resolve();
+      tx.oncomplete = () => resolve();
+      tx.onabort = () => resolve();
+    });
+  } catch {
+    // ignore
+  }
+}
+
+export async function idbClearAll(): Promise<void> {
+  memoryStore.clear();
+  const db = await openDb();
+  if (!db) return;
+  try {
+    await new Promise<void>((resolve) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      tx.objectStore(STORE_NAME).clear();
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => resolve();
+      tx.onabort = () => resolve();
+    });
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Writes an envelope directly into the fallback store, bypassing
+ * `SCHEMA_VERSION` — the only way to reproduce "an older build's envelope"
+ * in a test, since two fresh module imports do not share `memoryStore`.
+ * Exported for tests only; production code always goes through `idbSet`.
+ */
+export function __setRawEnvelopeForTest(key: string, envelope: { v: number; at: number; data: unknown }): void {
+  memoryStore.set(key, envelope);
+}

package/src/web/lib/browser-cache/project-cache-hydration.ts

@@ -0,0 +1,98 @@
+/**
+ * Registry of per-project cache hydrators (slash items in
+ * `slash-items-cache.ts`, recent sessions and tags in `session-list-store.ts`)
+ * plus the dedupe that keeps one project's hydrators from re-running on every
+ * panel switch back to it.
+ */
+import { projectCacheId, type ProjectCacheRef } from "./cache-keys";
+
+export type ProjectHydrator = (project: ProjectCacheRef) => Promise<void>;
+
+const hydrators = new Set<ProjectHydrator>();
+
+/** Projects whose hydrators have already been started, keyed by
+ * `projectCacheId`. Cleared by `wipe-browser-caches.ts` so a wipe forces a
+ * fresh hydration next time. */
+const started = new Map<string, ProjectCacheRef>();
+
+function runHydrator(fn: ProjectHydrator, project: ProjectCacheRef): Promise<void> {
+  return fn(project).catch((err) => {
+    console.warn("[browser-cache] project hydrator failed", err);
+  });
+}
+
+/** Register a hydrator to run on every `hydrateProjectCache` call that is not
+ * deduped. Hydrators run in parallel and must not depend on each other.
+ *
+ * A hydrator can register after its project was already hydrated: modules that
+ * live in a lazy chunk (the chat tab's slash cache) load only once the tab
+ * mounts, long after boot started hydration. It is run for those projects on
+ * registration, or the cache it owns would never be read back after a reload. */
+export function registerProjectHydrator(fn: ProjectHydrator): void {
+  if (hydrators.has(fn)) return;
+  hydrators.add(fn);
+  for (const project of started.values()) void runHydrator(fn, project);
+}
+
+/**
+ * Runs every registered hydrator for `project`, once per `projectCacheId`.
+ * Safe to call on every project switch — a project switched back to does not
+ * re-fetch until the cache is wiped. Never throws: one hydrator failing must
+ * not block the others or the caller.
+ */
+export function hydrateProjectCache(project: ProjectCacheRef): Promise<void> {
+  rememberLastProject(project);
+  const id = projectCacheId(project);
+  if (started.has(id)) return Promise.resolve();
+  started.set(id, project);
+  return Promise.all([...hydrators].map((fn) => runHydrator(fn, project))).then(() => undefined);
+}
+
+/** Clears the dedupe so the next `hydrateProjectCache` call re-runs every
+ * hydrator for every project. Called by a full wipe. */
+export function resetHydrationDedupe(): void {
+  started.clear();
+}
+
+/** Drops one project's dedupe entry, e.g. after its cache keys were evicted
+ * on rename/delete — the retired id has nothing left to dedupe against. */
+export function forgetProjectHydration(projectId: string): void {
+  started.delete(projectId);
+}
+
+// ---------------------------------------------------------------------------
+// Last-active-project pointer
+// ---------------------------------------------------------------------------
+// `hydrateProjectCache` needs a project's `path`, which app boot does not yet
+// have when it wants to start hydration — that happens before `fetchProjects()`
+// resolves. This tiny pointer, written every time hydration actually runs,
+// lets the next page load warm the cache for the project it last had open
+// without waiting on the network first. A first-ever visit simply has none.
+
+/** Holds a project name and its absolute path, so a token drop wipes it
+ * along with the rest of the cache (`wipe-browser-caches.ts`). */
+export const LAST_PROJECT_REF_KEY = "ppm-last-project-ref";
+
+function rememberLastProject(project: ProjectCacheRef): void {
+  try {
+    localStorage.setItem(LAST_PROJECT_REF_KEY, JSON.stringify(project));
+  } catch {
+    // Storage blocked or unavailable — nothing to remember.
+  }
+}
+
+/** The project `hydrateProjectCache` last ran for, from a previous page
+ * load. Returns null on a first-ever visit or when storage is blocked. */
+export function peekLastProjectRef(): ProjectCacheRef | null {
+  try {
+    const raw = localStorage.getItem(LAST_PROJECT_REF_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<ProjectCacheRef>;
+    if (typeof parsed.name === "string" && typeof parsed.path === "string") {
+      return { name: parsed.name, path: parsed.path };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/web/lib/browser-cache/wipe-browser-caches.ts

@@ -0,0 +1,66 @@
+/**
+ * Wipes everything the browser cache layer holds: IndexedDB, the chat
+ * preparation localStorage keys, the last-project pointer, and every
+ * registered in-memory cache (the slash cache in `slash-items-cache.ts`, the
+ * session store in `session-list-store.ts`).
+ *
+ * Called on every token drop — a 401 response or a failed login (see
+ * `api-client.ts`, `login-screen.tsx`) — and never on a password change,
+ * which keeps the current session's token valid.
+ */
+import { idbClearAll } from "./idb-keyval-cache";
+import { LAST_PROJECT_REF_KEY, resetHydrationDedupe } from "./project-cache-hydration";
+import { CHAT_PROVIDERS_KEY_PREFIX } from "./cache-keys";
+import { CHAT_PREF_STORAGE_KEY } from "../chat-preference-local-cache";
+
+export type CacheResetCallback = () => void;
+
+const resetCallbacks = new Set<CacheResetCallback>();
+
+/** Register a callback that clears an in-memory cache. Every registered
+ * callback runs on every wipe. */
+export function registerCacheReset(fn: CacheResetCallback): void {
+  resetCallbacks.add(fn);
+}
+
+function removeCachedLocalStorageKeys(): void {
+  try {
+    const toRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key === CHAT_PREF_STORAGE_KEY || key === LAST_PROJECT_REF_KEY || key?.startsWith(CHAT_PROVIDERS_KEY_PREFIX)) {
+        toRemove.push(key);
+      }
+    }
+    for (const key of toRemove) localStorage.removeItem(key);
+  } catch {
+    // Storage blocked or unavailable — nothing to clear.
+  }
+}
+
+/**
+ * Never throws — a wipe that fails partway must not block the logout flow it
+ * runs inside of.
+ *
+ * Everything synchronous happens before the first `await`, so it is done by
+ * the time a caller that does not wait (`clearAuthToken()`, which a 401
+ * follows with an immediate reload) gets control back. Only the IndexedDB
+ * clear is left to finish in the background; if the page unloads first, the
+ * next load's first read still sees a cache nobody can reach without a token.
+ */
+export async function wipeBrowserCaches(): Promise<void> {
+  removeCachedLocalStorageKeys();
+  resetHydrationDedupe();
+  for (const fn of resetCallbacks) {
+    try {
+      fn();
+    } catch {
+      // One bad reset must not stop the others.
+    }
+  }
+  try {
+    await idbClearAll();
+  } catch {
+    // idbClearAll already swallows its own errors; belt and suspenders.
+  }
+}

package/src/web/lib/chat-preference-local-cache.ts

@@ -0,0 +1,97 @@
+/**
+ * localStorage cache for the settings a new chat tab needs before it can
+ * resolve its provider and permission mode.
+ *
+ * `/api/settings/ai` is global, not per project, so the settings subset is
+ * cached under one global key. The provider *list* (`/chat/providers`) is
+ * project-scoped, so it is cached per `projectCacheId` instead.
+ *
+ * Both are read synchronously so a tab can render before any network
+ * response arrives, and both are shape-validated on read: anything pulled
+ * back out of localStorage may be stale, hand-edited, or written by an
+ * older build. Only the fields a new tab needs are ever stored — never
+ * account ids, labels, API keys, or anything else from the full settings
+ * object (see `AISettings` in `api-settings.ts`).
+ */
+import { providers as providersKey } from "./browser-cache/cache-keys";
+import type { ChatPreparationProviderSettings, ChatPreparationSettings } from "../../shared/chat-preparation-settings";
+
+export const CHAT_PREF_STORAGE_KEY = "ppm-chat-pref";
+
+export interface CachedChatProvider {
+  id: string;
+  name: string;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Narrows an arbitrary settings-shaped value down to only the fields this
+ * cache is allowed to hold, dropping everything else even if the caller
+ * passed a full `AISettings` object. Returns null when the shape is unusable. */
+function sanitizeSettings(input: unknown): ChatPreparationSettings | null {
+  if (!isPlainObject(input) || typeof input.default_provider !== "string") return null;
+  const mode = input.new_chat_provider_mode;
+  if (mode !== undefined && mode !== "default" && mode !== "follow-focus") return null;
+
+  const providers: Record<string, ChatPreparationProviderSettings> = {};
+  if (isPlainObject(input.providers)) {
+    for (const [id, value] of Object.entries(input.providers)) {
+      if (!isPlainObject(value)) continue;
+      providers[id] = typeof value.permission_mode === "string"
+        ? { permission_mode: value.permission_mode }
+        : {};
+    }
+  }
+  return { default_provider: input.default_provider, new_chat_provider_mode: mode, providers };
+}
+
+export function readChatPreparationSettings(): ChatPreparationSettings | null {
+  try {
+    const raw = localStorage.getItem(CHAT_PREF_STORAGE_KEY);
+    return raw ? sanitizeSettings(JSON.parse(raw)) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeChatPreparationSettings(settings: ChatPreparationSettings): void {
+  const clean = sanitizeSettings(settings);
+  if (!clean) return;
+  try {
+    localStorage.setItem(CHAT_PREF_STORAGE_KEY, JSON.stringify(clean));
+  } catch {
+    // Storage full or blocked — the cache is best-effort.
+  }
+}
+
+function sanitizeProviders(input: unknown): CachedChatProvider[] | null {
+  if (!Array.isArray(input)) return null;
+  const out: CachedChatProvider[] = [];
+  for (const entry of input) {
+    if (isPlainObject(entry) && typeof entry.id === "string" && typeof entry.name === "string") {
+      out.push({ id: entry.id, name: entry.name });
+    }
+  }
+  return out;
+}
+
+export function readChatProviders(projectId: string): CachedChatProvider[] | null {
+  try {
+    const raw = localStorage.getItem(providersKey(projectId));
+    return raw ? sanitizeProviders(JSON.parse(raw)) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeChatProviders(projectId: string, list: CachedChatProvider[]): void {
+  const clean = sanitizeProviders(list);
+  if (!clean) return;
+  try {
+    localStorage.setItem(providersKey(projectId), JSON.stringify(clean));
+  } catch {
+    // ignore
+  }
+}

package/src/web/lib/chat-preparation-cache.ts

@@ -56,6 +56,12 @@ export function peekChatProviders(projectName: string): ChatProviderInfo[] | und
   return entry && entry.expires > Date.now() ? entry.value : undefined;
 }
 
+/** Seeds this in-memory cache from a `/chat/prepare` response, so `peekChatProviders`
+ * (the provider chip's instant-open path) sees a fresh list without its own fetch. */
+export function seedChatProviders(projectName: string, list: ChatProviderInfo[]): void {
+  providers.set(projectName, { value: list, expires: Date.now() + TTL_MS });
+}
+
 export function clearChatPreparationCache(): void {
   ++generation;
   settings.clear();