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

package/src/serve/worker/entry.ts

@@ -0,0 +1,179 @@
+/**
+ * SharedWorker entry point — the actual SharedWorker script.
+ *
+ * WHY A SEPARATE ENTRY
+ * --------------------
+ * `host.ts` is pure-ish: it accepts an injected `{ db, sandbox }` and
+ * fake ports, so tests can drive it without a real SharedWorker runtime.
+ * This file is the integration shell: it creates the ONE real sandbox,
+ * attaches IDB persistence, deploys permissive starter rules, and wires
+ * every connecting port to `handleMessage`.
+ *
+ * Do NOT import this file in tests — import `host.ts` directly.
+ *
+ * LIFECYCLE
+ * ---------
+ * The SharedWorker lives while at least one tab holds a port. When all
+ * tabs close or navigate away, the worker is GC'd. IDB persistence means
+ * data survives full close → reopen cycles: on the next connect the sandbox
+ * restores from IDB, and the tab reconnects to a warm state.
+ *
+ * PERSISTENCE KEY
+ * ---------------
+ * Project-scoped: `'pyric-shared-worker:<projectKey>'`, derived inside
+ * `buildWorkerCtx` from the init payload's `projectKey` (issue #359 family —
+ * IndexedDB is origin-scoped, so the old fixed key shared one sandbox
+ * snapshot database across every project on a localhost port). The legacy
+ * `'pyric-shared-worker'` key applies only when no project identity exists
+ * (older servers, standalone workers); see `workerPersistenceKey` in
+ * serve-init.ts for the orphan-don't-delete migration decision.
+ *
+ * RULES
+ * -----
+ * We deploy a permissive starter ruleset on first init. Callers change
+ * rules at runtime via `{ t:'op', method:'setRules', source }` messages.
+ *
+ * SINGLE SANDBOX GUARANTEE
+ * ------------------------
+ * `_ctx` is module-level. The first `connect` event lazily creates it;
+ * all subsequent ports reuse the same ctx — one sandbox, one Firestore
+ * backend for all tabs. This is the architectural invariant the whole
+ * SharedWorker approach depends on.
+ */
+
+// SharedWorkerGlobalScope is not in the default TypeScript lib (it's in
+// lib.webworker.d.ts which conflicts with lib.dom.d.ts). This entry file is
+// browser-only and only bundled with esbuild (never compiled by tsc for
+// production). We declare the minimal interface we need so tsc can type-check
+// without enabling the full webworker lib.
+interface SharedWorkerGlobalScope {
+  onconnect: ((e: MessageEvent) => void) | null;
+}
+
+import { createIndexedDBBackend } from 'pyric/sandbox';
+
+import {
+  handleMessage,
+  cleanupPort,
+  type HostCtx,
+  type PortLike,
+} from './host.js';
+import { buildWorkerCtx, type EventSourceLike } from './serve-init.js';
+import type { InboundMessage } from './protocol.js';
+import {
+  SERVICE_WORKER_CHANNEL,
+  type ServiceWorkerChannelMessage,
+} from './service-worker-channel.js';
+import { createServiceWorkerRelay } from './service-worker-relay.js';
+
+// ─── Singleton context ────────────────────────────────────────────────────
+
+// `_ctx` is the RESOLVED context, kept for the synchronous `close` handler.
+// The build is memoized as a PROMISE (`_ctxPromise`) — NOT as the resolved
+// value — because init is async (it awaits `/__pyric/init.json` + persistence
+// restore). The first messages arrive in a BURST (the authState sub, the first
+// firestore sub, an op — possibly across two tabs at once); if each re-checked
+// only the resolved `_ctx` they would every one start a fresh init and build a
+// SEPARATE sandbox, so a listener and a write could bind to different
+// instances and never see each other. The promise memo guarantees ONE init.
+let _ctx: HostCtx | null = null;
+let _ctxPromise: Promise<HostCtx> | null = null;
+
+/**
+ * Return the shared context, memoizing the in-flight init promise so
+ * concurrent first messages await ONE build (see `_ctxPromise` above).
+ */
+function getCtx(): Promise<HostCtx> {
+  return (_ctxPromise ??= buildCtx());
+}
+
+/**
+ * Build the ONE shared sandbox + Firestore handle. Invoked exactly once per
+ * worker lifetime via the `getCtx` memo — never concurrently. The real boot
+ * logic lives in `buildWorkerCtx` (serve-init.ts) so it is testable without
+ * a SharedWorker runtime; this shell only supplies the real ambients.
+ *
+ * NOTE (#754): no worker-side session restore. Sessions are per-port; each
+ * PAGE re-establishes its own session from web storage via
+ * `auth.restorePortSession` (runtime.ts). The user DB itself is restored
+ * from the persisted snapshot inside buildWorkerCtx (#629).
+ */
+async function buildCtx(): Promise<HostCtx> {
+  // ONE IDB backend for the whole worker. createIndexedDBBackend's guard
+  // checks `typeof indexedDB === 'undefined'` — SharedWorkers have full
+  // IndexedDB access, so this succeeds. The persistence controller's
+  // window.addEventListener('beforeunload', ...) is guarded by
+  // `typeof window !== 'undefined'`, so enablePersistence is worker-safe.
+  const ctx = await buildWorkerCtx({
+    fetch,
+    idb: createIndexedDBBackend(),
+    // EventSource is available in workers; guard anyway for exotic hosts.
+    makeEventSource:
+      typeof EventSource !== 'undefined'
+        ? (url) => new EventSource(url) as unknown as EventSourceLike
+        : null,
+  });
+  _ctx = ctx; // publish the resolved ctx for the synchronous close handler
+  return ctx;
+}
+
+// ─── SharedWorker connect handler ─────────────────────────────────────────
+
+/**
+ * `self` in a SharedWorker is `SharedWorkerGlobalScope`, not `Window`.
+ * Each tab that opens the SharedWorker fires one `connect` event.
+ * Each tab gets its own `MessagePort`; we start() it (required for
+ * classic-mode workers to un-pause the message queue) and wire onmessage.
+ */
+(self as unknown as SharedWorkerGlobalScope).onconnect = (e: MessageEvent) => {
+  const port = e.ports[0];
+  port.start();
+
+  let messageQueue = Promise.resolve();
+  port.onmessage = (ev: MessageEvent<InboundMessage>) => {
+    // Serialize each port's frames. A disconnect acknowledgement therefore
+    // cannot overtake an already-posted mutation, and later frames see the
+    // disconnected-port tombstone instead of touching the shared backend.
+    messageQueue = messageQueue.then(async () => {
+      try {
+        const ctx = await getCtx();
+        await handleMessage(ctx, port as unknown as PortLike, ev.data);
+      } catch (e) {
+        // eslint-disable-next-line no-console
+        console.error('[pyric worker] message handler error:', (e as Error)?.stack ?? e, 'msg:', ev.data);
+      }
+    });
+  };
+
+  // Best-effort port cleanup on tab close/navigation.
+  // Chrome doesn't reliably fire 'close' on MessagePort — handled as
+  // best-effort; subscriptions also GC when the worker itself dies.
+  port.addEventListener('close', () => {
+    if (_ctx) cleanupPort(_ctx, port as unknown as PortLike);
+  });
+};
+
+// ServiceWorkerGlobalScope cannot construct a SharedWorker, but both worker
+// kinds share BroadcastChannel. Adapt each SW app connection to the host's
+// existing PortLike seam so it reaches this exact context/broker instead of
+// constructing a second in-Service-Worker sandbox.
+if (typeof BroadcastChannel !== 'undefined') {
+  const channel = new BroadcastChannel(SERVICE_WORKER_CHANNEL);
+  const relay = createServiceWorkerRelay({
+    getCtx,
+    send(message) { channel.postMessage(message); },
+    onError(error, envelope) {
+      console.error(
+        '[pyric worker] service-worker relay error:',
+        (error as Error)?.stack ?? error,
+        'msg:',
+        envelope,
+      );
+    },
+  });
+  channel.onmessage = (event: MessageEvent<ServiceWorkerChannelMessage>) => {
+    const envelope = event.data;
+    if (envelope.direction !== 'host') return;
+    void relay.handle(envelope);
+  };
+}

package/src/serve/worker/host/admin-firestore.ts

@@ -0,0 +1,88 @@
+/**
+ * SharedWorker host — admin-lens Firestore document ops (rules bypass).
+ *
+ * The `admin.*` surface used by the pyric-admin remote arm + Pyric Studio's
+ * "edit anything as admin": direct document get/list/set/delete against the
+ * sandbox admin plane, plus `admin.readState` (a prefix/depth-scoped snapshot
+ * of the whole store through the cached admin handle).
+ *
+ * Routed here by the host dispatcher. These ops act on `ctx.sandbox.admin` /
+ * the admin handle directly, so they take no resolved `db`. Never imports the
+ * dispatcher.
+ */
+
+import type { OpMessage } from '../protocol.js';
+import { snapshotDocuments } from 'pyric/sandbox/firestore';
+import { type HostCtx, type PortLike, ok, fail, bestEffortFlush } from '../host-context.js';
+
+/** The admin-lens op methods routed to {@link handleAdminFirestoreOp}. */
+const ADMIN_METHODS = new Set<string>([
+  'admin.getDocument',
+  'admin.listDocuments',
+  'admin.setDocument',
+  'admin.deleteDocument',
+  'admin.readState',
+]);
+
+export function isAdminFirestoreOp(method: OpMessage['method']): boolean {
+  return ADMIN_METHODS.has(method);
+}
+
+export async function handleAdminFirestoreOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  switch (msg.method) {
+    case 'admin.getDocument': {
+      try {
+        ok(port, msg.id, ctx.sandbox.admin.getDocument(msg.path));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'admin.listDocuments': {
+      try {
+        ok(port, msg.id, ctx.sandbox.admin.listDocuments(msg.path));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'admin.setDocument': {
+      try {
+        ctx.sandbox.admin.setDocument(msg.path, msg.data as Record<string, unknown>);
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'admin.deleteDocument': {
+      try {
+        const deleted = ctx.sandbox.admin.deleteDocument(msg.path);
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, deleted);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'admin.readState': {
+      try {
+        const snap = snapshotDocuments(ctx.sandbox);
+        const out: Record<string, unknown> = {};
+        const prefix = msg.path ?? '';
+        for (const [path, data] of Object.entries(snap)) {
+          if (prefix && !path.startsWith(prefix)) continue;
+          if (msg.maxDepth !== undefined && path.split('/').length > msg.maxDepth) continue;
+          out[path] = data;
+        }
+        ok(port, msg.id, out);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    default: {
+      fail(port, msg.id, new Error(`Unknown method: ${String((msg as { method: unknown }).method)}`));
+    }
+  }
+}

package/src/serve/worker/host/connection.ts

@@ -0,0 +1,179 @@
+/**
+ * SharedWorker host — connection / instance / state-transfer ops.
+ *
+ * The worker-lifecycle surface the client's `connection` family talks to:
+ *   - `getVersion` (build hash + per-worker instance id),
+ *   - full-state transfer (`exportState`/`importState`, the portable bundle),
+ *   - named branches (`saveBranch`/`listBranches`/`switchBranch`/`deleteBranch`,
+ *     saved-state bundles in the RAW idb).
+ *
+ * Owns the stable per-worker instance id (persisted to the raw idb) and the
+ * branch registry helpers. `getOrCreateInstanceId` is imported by serve-init;
+ * the instance-id + branch constants/helpers are part of the host's public
+ * surface (re-exported by the host barrel). Never imports the dispatcher.
+ */
+
+import type { PersistenceBackend } from 'pyric/sandbox';
+import { serializeToBuckets, bundleRecords, parseBundle, deserializeFromBuckets } from 'pyric/sandbox';
+
+import type { OpMessage } from '../protocol.js';
+import { type HostCtx, type PortLike, ok, fail } from '../host-context.js';
+
+/** Build hash injected by the bundler's esbuild `define`. Undefined when the
+ *  compiled host is imported directly (tests) — guarded with `typeof`. */
+declare const __PYRIC_WORKER_VERSION__: string;
+
+/**
+ * Per-SharedWorker instance id — generated once and persisted to the RAW idb
+ * (local-only, like the session record above; it must NEVER reach the
+ * committable server file). Because IndexedDB is per (origin + browser profile),
+ * two profiles on the same `localhost:<port>` get two distinct ids — which is
+ * exactly how the UI tells same-port-different-profile sandboxes apart.
+ */
+export const INSTANCE_ID_KEY = 'pyric:worker:instance';
+
+/**
+ * `crypto.randomUUID()` is secure-context-only (https or localhost), so it is
+ * `undefined` over plain http on a non-localhost host (a Tailscale or LAN
+ * hostname). `crypto.getRandomValues` is NOT gated, so build a v4 UUID from it as
+ * the fallback. Without this the worker throws on init over Tailscale and the
+ * whole sandbox (auth, firestore, bridge) silently fails to come up.
+ */
+export function randomUuid(): string {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  const b = crypto.getRandomValues(new Uint8Array(16));
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, '0'));
+  return `${h.slice(0, 4).join('')}-${h.slice(4, 6).join('')}-${h.slice(6, 8).join('')}-${h.slice(8, 10).join('')}-${h.slice(10, 16).join('')}`;
+}
+
+export async function getOrCreateInstanceId(idb: PersistenceBackend): Promise<string> {
+  const rec = (await idb.getRecord(INSTANCE_ID_KEY, 'id')) as { value?: string } | undefined;
+  if (rec && typeof rec.value === 'string') return rec.value;
+  const id = randomUuid();
+  await idb.putRecords(INSTANCE_ID_KEY, new Map([['id', { value: id }]]));
+  return id;
+}
+
+// ── Phase 3: named branches ─────────────────────────────────────────────────
+// A branch is a named saved state bundle in the RAW idb (local-only, like the
+// instance id + session; it must NEVER reach the committable server file). They
+// let one instance keep several named states it can switch between
+// (switchBranch = loadSnapshot the bundle, a clobber). A registry record holds
+// the ordered name list, since the backend lists records WITHIN a key, not keys.
+export const BRANCH_PREFIX = 'pyric:worker:branch:';
+export const BRANCH_REGISTRY_KEY = 'pyric:worker:branches';
+
+export async function listBranchNames(idb?: PersistenceBackend): Promise<string[]> {
+  if (!idb) return [];
+  const rec = (await idb.getRecord(BRANCH_REGISTRY_KEY, 'names')) as { value?: string[] } | undefined;
+  return Array.isArray(rec?.value) ? rec.value : [];
+}
+
+async function writeBranchRegistry(idb: PersistenceBackend, names: string[]): Promise<void> {
+  await idb.putRecords(BRANCH_REGISTRY_KEY, new Map([['names', { value: names }]]));
+}
+
+/** The connection/state/branch op methods routed to {@link handleConnectionOp}. */
+const CONNECTION_METHODS = new Set<string>([
+  'getVersion',
+  'exportState',
+  'importState',
+  'saveBranch',
+  'listBranches',
+  'switchBranch',
+  'deleteBranch',
+]);
+
+export function isConnectionOp(method: OpMessage['method']): boolean {
+  return CONNECTION_METHODS.has(method);
+}
+
+export async function handleConnectionOp(
+  ctx: HostCtx,
+  port: PortLike,
+  msg: OpMessage,
+): Promise<void> {
+  switch (msg.method) {
+    case 'getVersion': {
+      // The build hash is injected by the bundler (esbuild `define`). `typeof`
+      // guards the non-bundled path (tests import the compiled host directly,
+      // where the global is undefined) → reports 'dev'.
+      ok(port, msg.id, {
+        version: typeof __PYRIC_WORKER_VERSION__ !== 'undefined' ? __PYRIC_WORKER_VERSION__ : 'dev',
+        instanceId: ctx.instanceId,
+      });
+      break;
+    }
+
+    case 'exportState': {
+      // Phase 2 (transfer): serialize the FULL sandbox state to a portable bundle
+      // string using the SAME chunk format the persist layer uses, so wrapper
+      // types (Timestamp / Bytes / GeoPoint / VectorValue) round-trip. The string
+      // crosses the MessagePort cleanly (unlike the raw snapshot object).
+      const snap = ctx.sandbox.snapshot();
+      ok(port, msg.id, { bundle: bundleRecords(serializeToBuckets(snap.firestore, snap.services, 0)) });
+      break;
+    }
+
+    case 'importState': {
+      // Phase 2 (clobber): replace this sandbox's ENTIRE state with the imported
+      // bundle via the public loadSnapshot() (reset + rebuild firestore + restore
+      // services; listeners re-evaluate, persist re-flushes).
+      ctx.sandbox.loadSnapshot(deserializeFromBuckets(parseBundle(msg.bundle)));
+      ok(port, msg.id, { ok: true });
+      break;
+    }
+
+    case 'saveBranch': {
+      // Phase 3: snapshot the live sandbox into a named branch bundle (raw idb).
+      if (!ctx.sessionBackend) {
+        ok(port, msg.id, { ok: false, error: 'no persistence backend' });
+        break;
+      }
+      const snap = ctx.sandbox.snapshot();
+      const bundle = bundleRecords(serializeToBuckets(snap.firestore, snap.services, 0));
+      await ctx.sessionBackend.putRecords(BRANCH_PREFIX + msg.name, new Map([['bundle', { value: bundle }]]));
+      const names = await listBranchNames(ctx.sessionBackend);
+      if (!names.includes(msg.name)) await writeBranchRegistry(ctx.sessionBackend, [...names, msg.name]);
+      ok(port, msg.id, { ok: true });
+      break;
+    }
+
+    case 'listBranches': {
+      ok(port, msg.id, { branches: await listBranchNames(ctx.sessionBackend) });
+      break;
+    }
+
+    case 'switchBranch': {
+      // Phase 3: loadSnapshot the named branch bundle (a clobber).
+      const rec = ctx.sessionBackend
+        ? ((await ctx.sessionBackend.getRecord(BRANCH_PREFIX + msg.name, 'bundle')) as { value?: string } | undefined)
+        : undefined;
+      if (!rec?.value) {
+        ok(port, msg.id, { ok: false, error: `no such branch: ${msg.name}` });
+        break;
+      }
+      ctx.sandbox.loadSnapshot(deserializeFromBuckets(parseBundle(rec.value)));
+      ok(port, msg.id, { ok: true });
+      break;
+    }
+
+    case 'deleteBranch': {
+      if (ctx.sessionBackend) {
+        await ctx.sessionBackend.clear(BRANCH_PREFIX + msg.name);
+        await writeBranchRegistry(
+          ctx.sessionBackend,
+          (await listBranchNames(ctx.sessionBackend)).filter((n) => n !== msg.name),
+        );
+      }
+      ok(port, msg.id, { ok: true });
+      break;
+    }
+
+    default: {
+      fail(port, msg.id, new Error(`Unknown method: ${String((msg as { method: unknown }).method)}`));
+    }
+  }
+}