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

package/src/serve/worker/client/rules.ts

@@ -0,0 +1,63 @@
+/**
+ * Rules deployment + status over the worker port — Firestore and RTDB rulesets.
+ */
+
+import { nextId, rpc } from './core.js';
+import type { ClientDb, ClientRtdb } from './handles.js';
+
+// ─── setRules ────────────────────────────────────────────────────────────
+
+/**
+ * Deploy new rules to the worker's sandbox. Active onSnapshot listeners
+ * that were allowed by the old rules may start receiving error callbacks
+ * if the new rules deny them.
+ */
+export async function setRules(db: ClientDb, source: string): Promise<{ warnings: unknown[] }> {
+  const result = await rpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'setRules',
+    source,
+  });
+  return result as { warnings: unknown[] };
+}
+
+export async function setFirestoreRules(
+  db: ClientDb,
+  source: string,
+): Promise<{ ok: boolean; warnings: unknown[]; messages: unknown[] }> {
+  const result = await rpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'setFirestoreRules',
+    source,
+  });
+  return result as { ok: boolean; warnings: unknown[]; messages: unknown[] };
+}
+
+export async function setDatabaseRules(
+  db: ClientDb | ClientRtdb,
+  source: unknown,
+): Promise<{ ok: boolean; messages: unknown[] }> {
+  const result = await rpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'setDatabaseRules',
+    source,
+  });
+  return result as { ok: boolean; messages: unknown[] };
+}
+
+export async function getActiveRules(
+  db: ClientDb | ClientRtdb,
+  service?: 'firestore' | 'database',
+): Promise<unknown> {
+  return rpc(db.port, { t: 'op', id: nextId(), method: 'getActiveRules', service });
+}
+
+export async function getRulesStatus(
+  db: ClientDb | ClientRtdb,
+  service?: 'firestore' | 'database',
+): Promise<unknown> {
+  return rpc(db.port, { t: 'op', id: nextId(), method: 'getRulesStatus', service });
+}

package/src/serve/worker/client/runtime-control.ts

@@ -0,0 +1,22 @@
+import { nextId, rpcWithTimeout, subscribeRuntimeReload } from './core.js';
+import type { ClientDb } from './handles.js';
+
+/** Ask the current SharedWorker to drain accepted work and retire. */
+export async function retireWorkerRuntime(
+  db: ClientDb,
+  targetEpoch: string,
+  options: { timeoutMs?: number } = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 12_000;
+  await rpcWithTimeout(
+    db.port,
+    { t: 'op', id: nextId(), method: 'retireRuntime', targetEpoch },
+    timeoutMs,
+    `Timed out waiting for the Pyric worker to retire after ${timeoutMs}ms.`,
+  );
+}
+
+/** Observe the worker's all-pages reload signal. */
+export function onWorkerRuntimeReload(listener: (epoch: string) => void): () => void {
+  return subscribeRuntimeReload((message) => listener(message.epoch));
+}

package/src/serve/worker/client/service-worker-connection.ts

@@ -0,0 +1,59 @@
+/** MessagePort-shaped client transport from ServiceWorkerGlobalScope to the SharedWorker. */
+import { wirePort } from './core.js';
+import type { ClientDb, ClientPort } from './handles.js';
+import {
+  SERVICE_WORKER_CHANNEL,
+  type ServiceWorkerChannelMessage,
+} from '../service-worker-channel.js';
+
+function newSessionId(): string {
+  return typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function getServiceWorkerFirestore(appName: string): ClientDb {
+  if (typeof BroadcastChannel === 'undefined') {
+    throw new Error('BroadcastChannel is required to connect firebase/messaging/sw to the Pyric backend.');
+  }
+  const channel = new BroadcastChannel(SERVICE_WORKER_CHANNEL);
+  // Stable logical id + fresh realm id lets the host replace stale subscriptions
+  // without accepting late frames from the superseded Service Worker realm.
+  const clientId = `service-worker:${encodeURIComponent(appName)}`;
+  const sessionId = newSessionId();
+  channel.postMessage({
+    direction: 'host',
+    phase: 'attach',
+    clientId,
+    sessionId,
+  } satisfies ServiceWorkerChannelMessage);
+  const port: ClientPort = {
+    onmessage: null,
+    postMessage(message) {
+      channel.postMessage({
+        direction: 'host',
+        phase: 'message',
+        clientId,
+        sessionId,
+        message,
+      } satisfies ServiceWorkerChannelMessage);
+    },
+    start() {},
+    close() {
+      channel.close();
+      port.onmessage = null;
+    },
+  } satisfies ClientPort;
+  channel.onmessage = (event: MessageEvent<ServiceWorkerChannelMessage>) => {
+    const envelope = event.data;
+    if (
+      envelope.direction !== 'client'
+      || envelope.clientId !== clientId
+      || envelope.sessionId !== sessionId
+    ) return;
+    port.onmessage?.({ data: envelope.message } as MessageEvent);
+  };
+  const db = { __kind: 'client-db', port } satisfies ClientDb;
+  wirePort(db.port);
+  return db;
+}

package/src/serve/worker/client/snapshots.ts

@@ -0,0 +1,86 @@
+/**
+ * Firestore snapshot machinery for the worker client — wire-form document
+ * results rehydrated into the modular SDK's snapshot shapes. Shared by the
+ * read, listener, and transaction families.
+ */
+import type { SerializedDocData } from '../protocol.js';
+import { deserializeDocData } from '../protocol.js';
+import type { ClientPort, DocRefHandle } from './handles.js';
+
+// ─── Rehydration (class instance restoration) ─────────────────────────────
+
+/**
+ * Deserialize doc data from wire form to real class instances.
+ *
+ * `deserializeDocData` (protocol.ts) now calls `rehydrateDocValue` from
+ * pyric/sandbox, which reconstructs REAL Timestamp, Bytes, and LatLng
+ * instances — not plain-object look-alikes. This means:
+ *   - `snap.data().createdAt` is a real `Timestamp` with `.seconds`/`.nanos`
+ *   - `snap.data().blob` is a real `Bytes` with `.data` (Uint8Array)
+ *   - `snap.data().where` is a real `LatLng` with `.lat`/`.lng`
+ * Consumer code that uses `instanceof` checks or method calls will work
+ * correctly after deserialization.
+ */
+function rehydrateDocData(serialized: SerializedDocData): Record<string, unknown> {
+  return deserializeDocData(serialized) as Record<string, unknown>;
+}
+
+// ─── Snapshot deserialization helpers ────────────────────────────────────
+
+export interface RawDocResult {
+  id: string;
+  path?: string;
+  exists: boolean;
+  data?: SerializedDocData;
+}
+
+export function makeDocSnapshot(raw: RawDocResult, port: ClientPort): ClientDocSnapshot {
+  const data = raw.exists && raw.data ? rehydrateDocData(raw.data) : undefined;
+  const path = raw.path ?? raw.id;
+  const ref: DocRefHandle = {
+    __kind: 'doc-ref',
+    descriptor: { __ref: 'doc', path },
+    port,
+    id: raw.id,
+    path,
+  };
+  return {
+    id: raw.id,
+    path,
+    // Query snapshot refs are real worker handles, not path-only lookalikes:
+    // Firebase callers may pass `snapshot.ref` straight into deleteDoc/setDoc.
+    ref,
+    exists: () => raw.exists,
+    data: () => data,
+  };
+}
+
+export interface RawQueryResult {
+  docs: RawDocResult[];
+}
+
+export function makeQuerySnapshot(raw: RawQueryResult, port: ClientPort): ClientQuerySnapshot {
+  const docs = raw.docs.map((doc) => makeDocSnapshot(doc, port));
+  return {
+    size: docs.length,
+    empty: docs.length === 0,
+    docs,
+  };
+}
+
+// ─── Client snapshot types ────────────────────────────────────────────────
+
+export interface ClientDocSnapshot {
+  readonly id: string;
+  readonly path: string;
+  /** Full port-carrying reference, usable by write APIs. */
+  readonly ref: DocRefHandle;
+  exists(): boolean;
+  data(): Record<string, unknown> | undefined;
+}
+
+export interface ClientQuerySnapshot {
+  readonly size: number;
+  readonly empty: boolean;
+  readonly docs: ClientDocSnapshot[];
+}

package/src/serve/worker/client/storage.ts

@@ -0,0 +1,195 @@
+/**
+ * Worker-backed FirebaseStorage mirror (Pyric Studio data browse) — client-side
+ * ref path math plus `listAll`/`getMetadata`/`getBlob`/`getDownloadURL` reads and the base64
+ * byte ops (`uploadBytes`/`getBytes`/`deleteObject`) over the worker port.
+ */
+
+import { bytesToBase64, base64ToBytes, storagePayloadTooLarge, MAX_STORAGE_OP_BYTES } from '../protocol.js';
+import type { FullMetadata } from 'pyric/storage';
+import { dataRpc, nextId, wirePort } from './core.js';
+import { lastSegment } from './handles.js';
+import type { ClientDb, ClientPort } from './handles.js';
+
+// ─── Storage (Pyric Studio data browse) ───────────────────────────────────
+// A worker-backed `FirebaseStorage` mirror: `ref` is client-side (path math),
+// `listAll`/`getMetadata`/`getBlob`/`getDownloadURL` RPC to the host (which enforces rules).
+// Mutations are a follow-up.
+
+/** Worker-backed Storage handle (carries the shared `MessagePort`). */
+export interface ClientFirebaseStorage {
+  readonly __kind: 'client-storage';
+  readonly port: ClientPort;
+}
+
+/** Worker-backed Storage reference (path + name; carries the port for ops). */
+export interface ClientStorageReference {
+  readonly __kind: 'storage-ref';
+  readonly port: ClientPort;
+  readonly fullPath: string;
+  readonly name: string;
+}
+
+/** Strip leading/trailing slashes (the worker keyspace uses bare paths). */
+function normalizeStorageRefPath(path: string): string {
+  return path.replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * Get the worker-backed Storage handle. Like `getAuth`, accepts an existing
+ * `ClientDb` (reusing its port) or a worker URL (standalone).
+ */
+export function getStorage(source: ClientDb | string | URL, name?: string): ClientFirebaseStorage {
+  let port: ClientPort;
+  if (typeof source === 'object' && '__kind' in source && source.__kind === 'client-db') {
+    port = source.port;
+  } else {
+    if (typeof SharedWorker === 'undefined') {
+      throw new Error(
+        'SharedWorker is not available. ' +
+        'Open this page over http:// (not file://) and use a supported browser.',
+      );
+    }
+    const worker = new SharedWorker(source as string | URL, {
+      type: 'classic',
+      name: name ?? 'pyric-shared-worker',
+    });
+    port = worker.port;
+    port.start();
+    wirePort(port);
+  }
+  return { __kind: 'client-storage', port };
+}
+
+/** Build a Storage reference. Mirrors `pyric/storage`'s `ref(storage, path?)` /
+ *  `ref(parentRef, path)`. Client-side path math; no RPC. */
+export function ref(
+  parent: ClientFirebaseStorage | ClientStorageReference,
+  path?: string,
+): ClientStorageReference {
+  const rel = normalizeStorageRefPath(path ?? '');
+  let fullPath: string;
+  if (parent.__kind === 'client-storage') {
+    fullPath = rel;
+  } else {
+    const base = parent.fullPath;
+    fullPath = rel ? (base ? `${base}/${rel}` : rel) : base;
+  }
+  return { __kind: 'storage-ref', port: parent.port, fullPath, name: lastSegment(fullPath) };
+}
+
+/** Enumerate immediate child items + sub-prefixes under a ref (Pyric Studio
+ *  data browse). The host enforces `read` rules on the scanned prefix. */
+export async function listAll(
+  reference: ClientStorageReference,
+): Promise<{ items: ClientStorageReference[]; prefixes: ClientStorageReference[] }> {
+  const r = (await dataRpc(reference.port, {
+    t: 'op', id: nextId(), method: 'storage.listAll', path: reference.fullPath,
+  })) as { items: Array<{ fullPath: string; name: string }>; prefixes: Array<{ fullPath: string; name: string }> };
+  const mk = (e: { fullPath: string; name: string }): ClientStorageReference => ({
+    __kind: 'storage-ref', port: reference.port, fullPath: e.fullPath, name: e.name,
+  });
+  return { items: r.items.map(mk), prefixes: r.prefixes.map(mk) };
+}
+
+/** Read an object's metadata (Pyric Studio inspector). */
+export async function getMetadata(reference: ClientStorageReference): Promise<FullMetadata> {
+  return (await dataRpc(reference.port, {
+    t: 'op', id: nextId(), method: 'storage.getMetadata', path: reference.fullPath,
+  })) as FullMetadata;
+}
+
+/** Read an object's bytes as a Blob (Pyric Studio inspector preview).
+ *  MessagePort-only — a Blob cannot cross the JSON bridge relay. */
+export async function getBlob(reference: ClientStorageReference): Promise<Blob> {
+  return (await dataRpc(reference.port, {
+    t: 'op', id: nextId(), method: 'storage.getBlob', path: reference.fullPath,
+  })) as Blob;
+}
+
+/** Return a page-owned URL for an object read through the SharedWorker. */
+export async function getDownloadURL(reference: ClientStorageReference): Promise<string> {
+  return URL.createObjectURL(await getBlob(reference));
+}
+
+// ─── Storage mutations + JSON-safe reads (worker-mode byte ops) ───────────
+// Backed by the base64 `storage.putBytes` / `storage.getBytes` /
+// `storage.deleteObject` ops (remote sandbox, slice 2). Studio's data lens is
+// attached by `dataRpc`; ordinary served-app bundles have no default lens and
+// therefore remain app-session operations. Storage rules apply when the
+// HOST configured them on the sandbox's storage service — the served
+// worker's `applyServeInit` (serve-init.ts) does this at boot, before any op
+// can reach the host, so worker-mode storage enforces the project's
+// storage.rules the same as Firestore/RTDB (open only when the project has
+// none); the admin lens matters for embedding/test hosts that pre-open the
+// service with rules. Raw payloads are capped at 8 MiB
+// (`MAX_STORAGE_OP_BYTES`) — same cap the host enforces.
+
+/** Mirror of `pyric/storage`'s `SettableMetadata` (plain JSON on the wire). */
+export interface ClientSettableMetadata {
+  contentType?: string;
+  cacheControl?: string;
+  contentDisposition?: string;
+  contentEncoding?: string;
+  contentLanguage?: string;
+  customMetadata?: { [key: string]: string };
+}
+
+/** Upload bytes at the reference's path (replaces existing content).
+ *  Mirrors `pyric/storage`'s `uploadBytes` result shape. */
+export async function uploadBytes(
+  reference: ClientStorageReference,
+  data: Blob | Uint8Array | ArrayBuffer,
+  metadata?: ClientSettableMetadata,
+): Promise<{ ref: ClientStorageReference; metadata: FullMetadata }> {
+  const bytes =
+    data instanceof Blob
+      ? new Uint8Array(await data.arrayBuffer())
+      : data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : data;
+  if (bytes.byteLength > MAX_STORAGE_OP_BYTES) {
+    throw storagePayloadTooLarge(bytes.byteLength, `uploadBytes payload for '${reference.fullPath}'`);
+  }
+  // contentType precedence mirrors pyric/storage: caller metadata → Blob.type.
+  const contentType =
+    metadata?.contentType ?? (data instanceof Blob && data.type ? data.type : undefined);
+  const stored = (await dataRpc(reference.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'storage.putBytes',
+    path: reference.fullPath,
+    dataB64: bytesToBase64(bytes),
+    ...(contentType !== undefined ? { contentType } : {}),
+    ...(metadata !== undefined ? { metadata: metadata as Record<string, unknown> } : {}),
+  })) as FullMetadata;
+  return { ref: reference, metadata: stored };
+}
+
+/** Read an object's bytes (JSON-safe base64 op → `ArrayBuffer`). Mirrors
+ *  `pyric/storage`'s `getBytes`, including the optional client-side cap. */
+export async function getBytes(
+  reference: ClientStorageReference,
+  maxDownloadSizeBytes?: number,
+): Promise<ArrayBuffer> {
+  const res = (await dataRpc(reference.port, {
+    t: 'op', id: nextId(), method: 'storage.getBytes', path: reference.fullPath,
+  })) as { dataB64: string; size: number };
+  if (typeof maxDownloadSizeBytes === 'number' && res.size > maxDownloadSizeBytes) {
+    const err = new Error(
+      `storage/quota-exceeded: object at '${reference.fullPath}' is ${res.size} bytes — ` +
+        `over the requested maxDownloadSizeBytes (${maxDownloadSizeBytes}).`,
+    ) as Error & { code: string };
+    err.code = 'storage/quota-exceeded';
+    throw err;
+  }
+  const bytes = base64ToBytes(res.dataB64);
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+/** Delete the object at the reference's path (idempotent — missing = no-op,
+ *  matching the sandbox backend's delete semantics). */
+export async function deleteObject(reference: ClientStorageReference): Promise<void> {
+  await dataRpc(reference.port, {
+    t: 'op', id: nextId(), method: 'storage.deleteObject', path: reference.fullPath,
+  });
+}

package/src/serve/worker/client/studio.ts

@@ -0,0 +1,88 @@
+/**
+ * Pyric Studio cross-service surfaces over the worker port — the unified event
+ * stream (`subscribeEvents`/`eventHistory`) and the sandbox snapshot export
+ * used by the rules re-run flow.
+ */
+
+import type { InboundMessage } from '../protocol.js';
+import type { SandboxEvent, SandboxSnapshot } from 'pyric/sandbox';
+import { closeSubscription, nextId, nextSubId, openEventSubscription, rpc } from './core.js';
+import type { ClientDb, Unsubscribe } from './handles.js';
+
+// ════════════════════════════════════════════════════════════════════════
+//  EVENT STREAM (Pyric Studio keystone — onEvent/history over the port)
+// ════════════════════════════════════════════════════════════════════════
+//
+// Surfaces the worker sandbox's unified cross-service event stream to the page.
+// `subscribeEvents(db, cb)` registers a stream sub: the worker first delivers
+// `sandbox.history()` as one batch, then streams each live `SandboxEvent` as a
+// single-element batch. `eventHistory(db)` is a one-shot history fetch (a fresh
+// short-lived sub) for consumers that want a snapshot without staying live.
+//
+// These mirror `sandbox.onEvent(cb)` / `sandbox.history()` so a consumer can
+// adapt them into the same `{ onEvent, history }`-shaped source the in-process
+// sandbox exposes (e.g. Studio's `feedFromSandboxLike`).
+
+/**
+ * Subscribe to the worker sandbox's unified event stream. The callback fires
+ * with each delivered BATCH of events — the FIRST call carries the initial
+ * `history()` snapshot (possibly empty), each subsequent call carries one live
+ * event. Returns an unsubscribe that deregisters on the worker.
+ *
+ * This is the live counterpart to `sandbox.onEvent` + an initial `history()`
+ * fold, collapsed into one subscription so a late subscriber never misses the
+ * backlog.
+ */
+export function subscribeEvents(
+  db: ClientDb,
+  callback: (events: readonly SandboxEvent[]) => void,
+): Unsubscribe {
+  const subId = nextSubId();
+  const port = db.port;
+  openEventSubscription(
+    port,
+    subId,
+    callback,
+    { t: 'sub', subId, target: 'events' } satisfies InboundMessage,
+  );
+  return () => {
+    closeSubscription(port, subId);
+  };
+}
+
+/**
+ * Fetch the worker sandbox's event history as a one-shot snapshot (every event
+ * so far). Opens a transient stream sub, resolves with the initial history
+ * batch, and tears the sub down immediately — so it never holds a live
+ * subscription. Useful for a late, snapshot-only consumer.
+ */
+export function eventHistory(db: ClientDb): Promise<readonly SandboxEvent[]> {
+  return new Promise((resolve) => {
+    const unsub = subscribeEvents(db, (events) => {
+      // The first delivery is the history snapshot; resolve + unsubscribe.
+      unsub();
+      resolve(events);
+    });
+  });
+}
+
+/**
+ * Export the current sandbox snapshot (Pyric Studio rules re-run). Studio forks
+ * it locally to test a denied op against edited rules or re-issue it as the
+ * attempting user, on a throwaway branch (no live mutation).
+ */
+export async function getSnapshot(db: ClientDb): Promise<SandboxSnapshot> {
+  return (await rpc(db.port, { t: 'op', id: nextId(), method: 'getSnapshot' })) as SandboxSnapshot;
+}
+
+/**
+ * Sandbox-owned full reset (issue #359): `sandbox.resetAll()` on the worker.
+ * Clears the Firestore env, the signed-in session, and EVERY registered
+ * persistable service — auth users, the RTDB tree, storage objects. Resolves
+ * once the worker acks (all services finished clearing). This is the served
+ * counterpart of calling `sandbox.resetAll()` on an in-process sandbox.
+ */
+export async function resetAll(db: ClientDb): Promise<{ errors: string[] }> {
+  const reply = await rpc(db.port, { t: 'op', id: nextId(), method: 'resetAll' });
+  return (reply ?? { errors: [] }) as { errors: string[] };
+}

package/src/serve/worker/client.ts

@@ -0,0 +1,57 @@
+/**
+ * Worker client SDK — mirrors `pyric/firestore` (+ `pyric/auth`, `pyric/storage`,
+ * and the RTDB modular subset) for the SharedWorker data plane. App code can
+ * swap its `pyric/firestore` import for this module (via an import-map) and have
+ * every operation route to the single worker-hosted sandbox instead of an
+ * in-page one — same function names, same argument shapes, same return types.
+ *
+ * This module is a re-export barrel over the per-family modules under `client/`:
+ *   - `core`            transport singleton (RPC correlation, subscriber maps,
+ *                       port wiring, the Studio auth-lens + op-issuer stamp)
+ *   - `handles`         opaque port-carrying handle types + `Unsubscribe`
+ *   - `snapshots`       firestore snapshot rehydration + snapshot types
+ *   - `connection`      connect, worker version/instance, state/branches, relay
+ *   - `firestore-refs`  ref / query / sentinel descriptor factories (no RPC)
+ *   - `firestore-reads` read + aggregate execution + `onSnapshot`
+ *   - `firestore-writes` writes + `writeBatch` + `runTransaction`
+ *   - `rules`           Firestore/RTDB rules deploy + status
+ *   - `admin-firestore` admin-lens document ops
+ *   - `rtdb`            RTDB modular subset
+ *   - `studio`          event stream, confirm-policy, sandbox snapshot
+ *   - `auth`            per-port auth surface
+ *   - `storage`         worker-backed storage mirror
+ *   - `messaging`       token lifecycle + foreground/background subscriptions
+ *
+ * The barrel is part of the worker's PUBLIC shape: `serve/worker/index.ts`
+ * re-exports from here for the `@pyric/cli/serve/worker` package subpath.
+ */
+
+// Shared core: lens/issuer controls + the handle and snapshot types.
+export { setLens, getLens, setOpIssuer } from './client/core.js';
+export type {
+  ClientDb,
+  ClientRtdb,
+  RtdbRefHandle,
+  RtdbDataSnapshot,
+  DocRefHandle,
+  CollRefHandle,
+  QueryHandle,
+  AnyHandle,
+  Unsubscribe,
+} from './client/handles.js';
+export type { ClientDocSnapshot, ClientQuerySnapshot } from './client/snapshots.js';
+
+// API families. Each module exports only its public surface; internal helpers
+// stay unexported, so `export *` re-exports exactly the published symbols.
+export * from './client/connection.js';
+export * from './client/firestore-refs.js';
+export * from './client/firestore-reads.js';
+export * from './client/firestore-writes.js';
+export * from './client/rules.js';
+export * from './client/admin-firestore.js';
+export * from './client/rtdb.js';
+export * from './client/studio.js';
+export * from './client/presence.js';
+export * from './client/auth.js';
+export * from './client/storage.js';
+export * from './client/ai.js';