@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/serve/entries/storage.ts

@@ -0,0 +1,92 @@
+/**
+ * The bundle the import map serves for `firebase/storage`.
+ *
+ * Served apps keep their normal Firebase Storage imports. In worker mode, browse
+ * and metadata reads use the shared worker-hosted object store; operations that
+ * still lack a worker protocol fail loudly. In in-page fallback mode, the entry
+ * delegates to `pyric/storage` against the page sandbox.
+ */
+import * as ip from 'pyric/storage';
+import {
+  getStorage as pyricGetStorage,
+  type FirebaseStorage,
+} from 'pyric/storage';
+import {
+  getStorage as workerGetStorage,
+  getBlob as workerGetBlob,
+  getBytes as workerGetBytes,
+  getDownloadURL as workerGetDownloadURL,
+  getMetadata as workerGetMetadata,
+  listAll as workerListAll,
+  ref as workerRef,
+  uploadBytes as workerUploadBytes,
+  deleteObject as workerDeleteObject,
+} from '../worker/client.js';
+import { useWorker } from './worker-runtime.js';
+import { getApp, type FirebaseApp } from 'pyric/app';
+import { workerClientForApp } from './app-client.js';
+
+const workerStorageByApp = new WeakMap<FirebaseApp, FirebaseStorage>();
+
+export function getStorage(app?: FirebaseApp, _bucketUrl?: string): FirebaseStorage {
+  const resolved = app ?? getApp();
+  if (!useWorker) return pyricGetStorage(resolved, _bucketUrl);
+  const existing = workerStorageByApp.get(resolved);
+  if (existing) return existing;
+  const client = workerClientForApp(resolved);
+  const handle = Object.assign(workerGetStorage(client), { app: resolved }) as unknown as FirebaseStorage;
+  workerStorageByApp.set(resolved, handle);
+  return handle;
+}
+
+export const ref = (useWorker ? workerRef : ip.ref) as typeof ip.ref;
+export const listAll = (useWorker ? workerListAll : ip.listAll) as typeof ip.listAll;
+export const getMetadata = (
+  useWorker ? workerGetMetadata : ip.getMetadata
+) as typeof ip.getMetadata;
+export const getBlob = (useWorker ? workerGetBlob : ip.getBlob) as typeof ip.getBlob;
+export const getDownloadURL = (
+  useWorker ? workerGetDownloadURL : ip.getDownloadURL
+) as typeof ip.getDownloadURL;
+
+export const StorageError = ip.StorageError;
+
+// pyric replaces the Firebase emulator; connectStorageEmulator is a
+// no-op. Served apps are already talking to the pyric sandbox (or the
+// SharedWorker's shared store), which IS the local emulator — pointing
+// it at a `firebase-tools` emulator host would be a step backward, not
+// forward, so the call is logged and swallowed rather than forwarded.
+export function connectStorageEmulator(
+  storage: unknown,
+  _host: string,
+  _port: number,
+  _options?: unknown,
+): void {
+  console.info(
+    '[pyric dev] pyric replaces the Firebase emulator; connectStorageEmulator is a no-op.',
+  );
+  if (!useWorker) ip.connectStorageEmulator(storage as FirebaseStorage, _host, _port, _options as never);
+}
+
+function unsupportedWorkerApi(name: string): never {
+  throw new Error(
+    `firebase/storage ${name}() is not supported over the pyric SharedWorker yet. ` +
+      'Use the in-page fallback for this operation.',
+  );
+}
+
+function workerOrInPage<T extends (...args: any[]) => unknown>(name: string, fn: T): T {
+  return (useWorker ? (() => unsupportedWorkerApi(name)) : fn) as T;
+}
+
+// Byte ops use the worker protocol (base64 `storage.putBytes` /
+// `storage.getBytes` / `storage.deleteObject`) and the initiating app port's
+// authenticated session. All app ports reach the same object store and
+// ruleset; only their active Auth sessions differ. Payloads are capped at
+// 8 MiB per op.
+export const uploadBytes = (useWorker ? workerUploadBytes : ip.uploadBytes) as typeof ip.uploadBytes;
+export const getBytes = (useWorker ? workerGetBytes : ip.getBytes) as typeof ip.getBytes;
+export const deleteObject = (useWorker ? workerDeleteObject : ip.deleteObject) as typeof ip.deleteObject;
+
+export const uploadString = workerOrInPage('uploadString', ip.uploadString);
+export const updateMetadata = workerOrInPage('updateMetadata', ip.updateMetadata);

package/src/serve/entries/tab-sync-wiring.ts

@@ -0,0 +1,274 @@
+/**
+ * Cross-tab realtime sync wiring for `pyric dev`.
+ *
+ * Two independent channels carry two independent kinds of state:
+ *
+ *   1. Firestore data   — delegated entirely to `sandbox.enableTabSync()`.
+ *      That call attaches a BroadcastChannel-based write-propagation and
+ *      late-join handshake (hello/state) internally; we just supply the
+ *      channel so the name is under our control.
+ *
+ *   2. Auth state       — `enableTabSync` only carries Firestore write events;
+ *      auth sign-in / sign-out lives entirely outside the Firestore environment.
+ *      We bridge it on a SECOND channel using a simple full-state protocol:
+ *      any auth change broadcasts the complete user DB + current UID; a new tab
+ *      announces itself with `hello` and receives the current state in reply.
+ *
+ * Why full-state instead of deltas?
+ *   Auth payloads are tiny (a handful of users). Broadcasting the entire user DB
+ *   + current UID on every change avoids ordering bugs where a `seedUsers` arrives
+ *   before a `restoreSession` (or vice versa) and leaves the receiving tab in an
+ *   inconsistent partial state. One atomic message = one safe apply.
+ *
+ * Echo-loop prevention (load-bearing):
+ *   Applying a received auth state calls `seedUsers` + `restoreSession`, which
+ *   fire `subscribeUsers` / `onAuthStateChanged` callbacks — the same callbacks
+ *   that trigger outbound broadcasts. Without a guard this creates an infinite
+ *   cross-tab loop. The `applyingRemoteAuth` boolean breaks it: set to `true`
+ *   immediately before the apply and `false` in the `finally` block; both
+ *   broadcast callbacks check the flag and no-op while it is set.
+ *   JavaScript is single-threaded, and `seedUsers` + `restoreSession` are
+ *   synchronous (they resolve before any pending microtask can enter), so the
+ *   boolean is collision-free.
+ *
+ * Late-join (hello/state):
+ *   A tab that opens AFTER others have already signed in broadcasts `hello` on
+ *   init. Any peer that receives it replies with `state` (full user DB +
+ *   currentUid). The joining tab receives that `state` and calls
+ *   `seedUsers` + `restoreSession` to catch up — same as if those ops had
+ *   happened locally. The existing tabs' `onAuthStateChanged` listeners in the
+ *   joining tab fire as a result, exactly as they would in production.
+ *
+ * Origin tagging:
+ *   Every message carries an `origin` equal to the sending tab's random ID.
+ *   Receiving tabs drop messages whose `origin` equals their own ID — both to
+ *   comply with the echo guard and to be correct on injected test channels that
+ *   may deliver messages back to the sender (the real BroadcastChannel spec does
+ *   NOT deliver to the sender, but test stubs may differ).
+ */
+
+import type { Auth, SeedUser } from 'pyric/auth';
+
+// ─── Auth channel message shapes ─────────────────────────────────────────────
+
+/** Full auth state broadcast whenever auth changes or in response to a hello. */
+interface AuthStateMessage {
+  kind: 'state';
+  /** Sending tab's random ID — used for echo suppression. */
+  origin: string;
+  /** Complete user DB snapshot in the shape `seedUsers` accepts. */
+  users: SeedUser[];
+  /** UID of the signed-in user, or null when signed out. */
+  currentUid: string | null;
+}
+
+/** Sent by a new tab on init to request the current auth state from peers. */
+interface AuthHelloMessage {
+  kind: 'hello';
+  /** Sending tab's random ID. */
+  origin: string;
+}
+
+type AuthSyncMessage = AuthStateMessage | AuthHelloMessage;
+
+/** Loose type guard — checks the discriminant fields only. */
+function isAuthSyncMessage(v: unknown): v is AuthSyncMessage {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    typeof (v as Record<string, unknown>).kind === 'string' &&
+    typeof (v as Record<string, unknown>).origin === 'string'
+  );
+}
+
+// ─── Auth ops interface (injected to keep this module testable) ───────────────
+
+/**
+ * The subset of `pyric/auth`'s `sandbox` namespace that we need.
+ * Injected so tests can stub without a real sandbox.
+ */
+export interface AuthOps {
+  exportUsers(auth: Auth): SeedUser[];
+  seedUsers(auth: Auth, users: ReadonlyArray<SeedUser>): void;
+  restoreSession(auth: Auth, uid: string): void;
+  subscribeUsers(auth: Auth, callback: () => void): () => void;
+}
+
+// ─── Public entry point ───────────────────────────────────────────────────────
+
+/**
+ * Wire cross-tab auth synchronization.
+ *
+ * Call once, after the sandbox and auth are initialised, near the END of
+ * `runtime.ts` init. The function is a no-op when `BroadcastChannel` is
+ * not available (SSR / old Node environments stay inert).
+ *
+ * @param auth        The `Auth` handle for this page (from `getAuth(sandbox)`).
+ * @param authOps     The `sandbox` namespace from `pyric/auth`.
+ * @param onAuthStateChanged  `onAuthStateChanged` from `pyric/auth`.
+ * @param signOut     `signOut` from `pyric/auth`.
+ * @param channel     Optional injected channel (omit in production — a real
+ *                    `BroadcastChannel('pyric:serve:auth-sync')` is created).
+ * @param originId    Optional injected origin ID (omit in production).
+ *
+ * @returns A disable function that removes all listeners and closes the channel.
+ *          Safe to ignore in `pyric dev` — the tab is the lifetime.
+ */
+export function wireAuthTabSync(
+  auth: Auth,
+  authOps: AuthOps,
+  onAuthStateChanged: (auth: Auth, cb: (user: unknown) => void) => () => void,
+  signOut: (auth: Auth) => Promise<void>,
+  channel?: { postMessage(msg: unknown): void; addEventListener(type: 'message', l: (ev: { data: unknown }) => void): void; removeEventListener(type: 'message', l: (ev: { data: unknown }) => void): void; close(): void },
+  originId?: string,
+): () => void {
+  // Guard: BroadcastChannel is browser-only. Non-browser imports (SSR, bundler
+  // tree-shaking analysis) must stay inert.
+  if (!channel && typeof BroadcastChannel === 'undefined') {
+    return () => { /* no-op: BroadcastChannel unavailable */ };
+  }
+
+  const bc = channel ?? new BroadcastChannel('pyric:serve:auth-sync');
+  const ownedByUs = !channel;
+
+  const origin: string =
+    originId ??
+    (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : `auth-tab-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+
+  // ── Echo / loop guard ────────────────────────────────────────────────────
+  //
+  // WHY: applying a received `state` calls `seedUsers` (fires `subscribeUsers`
+  // callbacks) and `restoreSession` (fires `onAuthStateChanged` callbacks).
+  // Both of those callbacks are hooked to broadcast the current state outward.
+  // Without this guard, the sequence would loop: Tab A signs in → broadcasts →
+  // Tab B receives → applies → subscribeUsers/onAuthStateChanged fire in Tab B
+  // → Tab B broadcasts → Tab A receives → applies → loops.
+  //
+  // Setting this flag to `true` around the synchronous apply block prevents
+  // the outbound broadcast callbacks from posting. Both `seedUsers` and
+  // `restoreSession` are synchronous; JS is single-threaded — the flag is
+  // reset to `false` before any micro/macrotask can re-enter.
+  let applyingRemoteAuth = false;
+
+  // ── Debounced outbound broadcast ─────────────────────────────────────────
+  //
+  // We debounce (~100ms) to coalesce a `seedUsers` + `restoreSession` pair
+  // (which fires both subscribeUsers AND onAuthStateChanged in quick succession)
+  // into a single outbound message. Without debounce the two callbacks could
+  // send two rapid-fire broadcasts to peers, causing redundant double-applies.
+  let broadcastTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function scheduleBroadcast(): void {
+    // Skip if we're currently applying a remote state — that would echo.
+    if (applyingRemoteAuth) return;
+    if (broadcastTimer !== null) clearTimeout(broadcastTimer);
+    broadcastTimer = setTimeout(() => {
+      broadcastTimer = null;
+      if (applyingRemoteAuth) return; // double-check after the debounce delay
+      broadcastCurrentState();
+    }, 100);
+  }
+
+  function broadcastCurrentState(): void {
+    const msg: AuthStateMessage = {
+      kind: 'state',
+      origin,
+      users: authOps.exportUsers(auth),
+      currentUid: auth.currentUser?.uid ?? null,
+    };
+    bc.postMessage(msg);
+  }
+
+  // ── Subscribe to local auth changes ──────────────────────────────────────
+  //
+  // Two hooks cover the two dimensions of auth state:
+  //   - `subscribeUsers` fires when the user DB changes (new user created,
+  //     user properties changed, user deleted). This carries the FULL user DB.
+  //   - `onAuthStateChanged` fires when the signed-in session changes (sign in,
+  //     sign out, session swap). This carries `currentUid`.
+  //
+  // Broadcasting on BOTH ensures sign-in (changes currentUid without touching
+  // users DB), sign-up (creates a user AND changes currentUid), and user-DB
+  // edits all propagate. They share the debounce so a sign-up that fires
+  // subscribeUsers first and onAuthStateChanged second sends one message, not two.
+
+  const unsubUsers = authOps.subscribeUsers(auth, scheduleBroadcast);
+  const unsubAuthState = onAuthStateChanged(auth, scheduleBroadcast);
+
+  // ── Receive remote auth state ─────────────────────────────────────────────
+
+  const handleMessage = async (ev: { data: unknown }): Promise<void> => {
+    if (!isAuthSyncMessage(ev.data)) return;
+    const msg = ev.data;
+
+    // Echo suppression: ignore messages from ourselves.
+    if (msg.origin === origin) return;
+
+    if (msg.kind === 'hello') {
+      // A new tab joined and wants the current state. Reply immediately (no
+      // debounce — this is a direct reply to a single event, not a user write).
+      broadcastCurrentState();
+      return;
+    }
+
+    if (msg.kind === 'state') {
+      // Apply received full auth state under the echo guard.
+      //
+      // Order is critical:
+      //   1. seedUsers FIRST — ensures the uid in `currentUid` exists in the DB.
+      //      restoreSession throws 'user-not-found' if the uid is absent, which
+      //      would leave the tab signed out even though the peer is signed in.
+      //   2. restoreSession SECOND — re-establishes the signed-in session.
+      //      If `currentUid` is null, sign out instead (sign-out in Tab A must
+      //      flow through to Tab B).
+      applyingRemoteAuth = true;
+      try {
+        authOps.seedUsers(auth, msg.users);
+        if (msg.currentUid) {
+          try {
+            authOps.restoreSession(auth, msg.currentUid);
+          } catch {
+            // uid was in the exported list but restoreSession still failed
+            // (e.g. user disabled between export and apply). Sign out to stay
+            // consistent with the peer's next broadcast rather than silently
+            // leaving the tab in a stale signed-in state.
+            await signOut(auth).catch(() => {});
+          }
+        } else {
+          // Peer signed out — mirror that here.
+          await signOut(auth).catch(() => {});
+        }
+      } finally {
+        applyingRemoteAuth = false;
+      }
+    }
+  };
+
+  bc.addEventListener('message', handleMessage);
+
+  // ── Late-join hello ───────────────────────────────────────────────────────
+  //
+  // Post a `hello` AFTER wiring the message listener so we don't miss a `state`
+  // reply that arrives while still setting up (relevant on injected synchronous
+  // test channels). Peers reply with their current auth state; we apply it in
+  // `handleMessage` above. This lets a freshly-opened tab immediately inherit
+  // the signed-in user from an already-open tab without waiting for the next
+  // user-driven auth change.
+  const helloMsg: AuthHelloMessage = { kind: 'hello', origin };
+  bc.postMessage(helloMsg);
+
+  // ── Disable ───────────────────────────────────────────────────────────────
+
+  return () => {
+    if (broadcastTimer !== null) {
+      clearTimeout(broadcastTimer);
+      broadcastTimer = null;
+    }
+    unsubUsers();
+    unsubAuthState();
+    bc.removeEventListener('message', handleMessage);
+    if (ownedByUs) bc.close();
+  };
+}

package/src/serve/entries/worker-runtime.ts

@@ -0,0 +1,135 @@
+/** SharedWorker availability, control-port ownership, presence, and staleness. */
+import {
+  getFirestore,
+  getWorkerVersion,
+  startPresence,
+  subscribeEvents,
+  subscribePresence,
+  type ClientDb,
+} from '../worker/client.js';
+import { getServiceWorkerFirestore } from '../worker/client/service-worker-connection.js';
+import { isServiceWorkerRealm } from '../worker/service-worker-channel.js';
+import {
+  PYRIC_WORKER_NAME,
+  PYRIC_WORKER_URL,
+} from '../runtime/manifest.js';
+import { getPyricRuntimeStatus } from '../runtime/status.js';
+import { connectRuntimeWorker } from '../runtime/worker-connection.js';
+import { createWorkerReplacement } from '../runtime/worker-replacement.js';
+import {
+  preflightWorkerEpochStorage,
+  rememberWorkerEpoch,
+  workerNameForEpoch,
+} from '../runtime/worker-generation.js';
+import {
+  onWorkerRuntimeReload,
+  retireWorkerRuntime,
+} from '../worker/client/runtime-control.js';
+
+const hasSharedWorker = typeof SharedWorker !== 'undefined';
+const runtimeStatus = getPyricRuntimeStatus();
+
+const workerRequested =
+  (hasSharedWorker || (isServiceWorkerRealm() && typeof BroadcastChannel !== 'undefined'))
+  && !(globalThis as { __PYRIC_FORCE_INPAGE__?: boolean }).__PYRIC_FORCE_INPAGE__;
+
+export const WORKER_URL = PYRIC_WORKER_URL;
+let epochStorage: Storage | undefined;
+try {
+  epochStorage = typeof localStorage === 'undefined' ? undefined : localStorage;
+} catch {
+  epochStorage = undefined;
+}
+export const WORKER_NAME = workerNameForEpoch(
+  runtimeStatus.getSnapshot().servedEpoch,
+  epochStorage,
+);
+
+/** Control traffic only; Firebase apps receive independent app-owned ports. */
+export const workerDb: ClientDb | null = workerRequested
+  ? hasSharedWorker
+    ? connectRuntimeWorker(
+        () => getFirestore(WORKER_URL, WORKER_NAME, {
+          onError: (error) => runtimeStatus.reportError(error, 'worker'),
+        }),
+        (error) => runtimeStatus.reportError(error, 'worker'),
+      )
+    : null
+  : null;
+
+export const useWorker = workerRequested && (!hasSharedWorker || workerDb !== null);
+
+export function openWorkerDb(appName: string): ClientDb {
+  if (hasSharedWorker) return getFirestore(WORKER_URL, WORKER_NAME);
+  if (isServiceWorkerRealm()) return getServiceWorkerFirestore(appName);
+  throw new Error('No Pyric worker transport is available in this browser context.');
+}
+
+export const presenceSession = useWorker && workerDb
+  ? startPresence({ db: workerDb, kind: 'app' })
+  : null;
+
+runtimeStatus.setWorker({
+  mode: useWorker ? 'shared-worker' : 'in-page',
+  runningEpoch: null,
+});
+
+const workerReplacement = useWorker && workerDb && typeof window !== 'undefined'
+  ? createWorkerReplacement({
+      targetEpoch: runtimeStatus.getSnapshot().servedEpoch!,
+      retire: () => retireWorkerRuntime(
+        workerDb,
+        runtimeStatus.getSnapshot().servedEpoch!,
+      ),
+      subscribeReload: onWorkerRuntimeReload,
+      preflight: () => preflightWorkerEpochStorage(epochStorage),
+      commitGeneration: (epoch) => rememberWorkerEpoch(epoch, epochStorage),
+      onPreparationError: (error) => runtimeStatus.reportError(error, 'worker'),
+      reload: () => window.location.reload(),
+    })
+  : null;
+runtimeStatus.setWorkerUpdater(
+  workerReplacement ? () => workerReplacement.request() : null,
+);
+
+if (useWorker && workerDb) {
+  subscribeEvents(workerDb, (events) => runtimeStatus.recordSandboxEvents(events));
+}
+
+if (useWorker && typeof document !== 'undefined') {
+  const servedVersion = runtimeStatus.getSnapshot().servedEpoch;
+  void getWorkerVersion(workerDb!)
+    .then(async (runningVersion) => {
+      runtimeStatus.setWorker({ mode: 'shared-worker', runningEpoch: runningVersion });
+      if (
+        !servedVersion
+        || !runningVersion
+        || runningVersion === 'dev'
+        || servedVersion === runningVersion
+      ) return;
+      const otherPages = await new Promise<number>((resolve) => {
+        const unsubscribe = subscribePresence(workerDb!, (snapshot) => {
+          unsubscribe();
+          resolve(snapshot.clients.filter(
+            (client) => client.clientId !== presenceSession?.clientId,
+          ).length);
+        });
+        setTimeout(() => {
+          unsubscribe();
+          resolve(-1);
+        }, 2_000);
+      });
+      const othersHint = otherPages > 0
+        ? ` ${otherPages} other page${otherPages === 1 ? '' : 's'} must disconnect before the worker can restart.`
+        : otherPages === 0
+          ? ' This is the only connected page — reload it to pick up the new worker.'
+          : '';
+      console.warn(
+        `[pyric dev] the SharedWorker is running OLDER code (build ${runningVersion}) than what is now `
+          + `served (build ${servedVersion}). A SharedWorker can't hot-update — CLOSE ALL TABS of this origin `
+          + 'and reopen to load the new worker. (All tabs share one worker, so a partial reload leaves '
+          + `the old code running for everyone.)${othersHint}`,
+      );
+    })
+    .catch((error) => runtimeStatus.reportError(error, 'worker'));
+}

package/src/serve/init-payload.ts

@@ -0,0 +1,42 @@
+import type { AiEngineConfigWire } from './worker/protocol.js';
+
+/** Browser-safe wire contract served by `/__pyric/init.json`. */
+export interface InitPayload {
+  /** Per-server capability for the warning-only activity report endpoint. */
+  activityToken?: string;
+  rules: string | null;
+  rulesHash: string | null;
+  databaseRules?: { rules: Record<string, unknown> } | null;
+  databaseRulesHash?: string | null;
+  databaseUrl?: string | null;
+  /** Storage rules are installed once, before the first Storage operation. */
+  storageRules: string | null;
+  storageRulesHash: string | null;
+  /**
+   * Local project identity — the served project directory. Scopes the
+   * storage IndexedDB database name (`pyric-storage:<projectKey>`, issue
+   * #359): IndexedDB is origin-scoped, so without this every project served
+   * on one localhost port shared one storage database. Local-only (a dev
+   * server path never leaves the machine). Absent/null on older servers —
+   * consumers fall back to the legacy shared name.
+   */
+  projectKey?: string | null;
+  bridgeUrl: string | null;
+  seed: Record<string, Record<string, unknown>> | null;
+  persist?: boolean;
+  seedState?: unknown | null;
+  authUsers?: ReadonlyArray<Record<string, unknown>> | null;
+  capture?: boolean;
+  messaging?: boolean;
+  /**
+   * Plugin-level AI config (`@pyric/cli/vite`'s `ai.engine`). Only the ENGINE
+   * travels here — the OpenAI proxy upstream is a server-side namespace option
+   * that never reaches the page. The worker host reads `ai.engine` into
+   * `ctx.aiEngine`, which wins over any op-carried `engine` (see host-ai.ts).
+   * Absent under `pyric dev` (no CLI surface) and whenever the plugin sets no
+   * engine. The in-page fallback path receives the same engine synchronously
+   * via the injected `globalThis.__PYRIC_AI_ENGINE__` (init.json can't be read
+   * synchronously by the served `getAI`).
+   */
+  ai?: { engine?: AiEngineConfigWire } | null;
+}