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

package/src/serve/worker/service-worker-relay.ts

@@ -0,0 +1,86 @@
+/** Session-aware Service Worker relay over the authoritative SharedWorker host. */
+import {
+  cleanupPort,
+  handleMessage,
+  type HostCtx,
+  type PortLike,
+} from './host.js';
+import type { ServiceWorkerChannelMessage } from './service-worker-channel.js';
+
+type HostEnvelope = Extract<ServiceWorkerChannelMessage, { direction: 'host' }>;
+
+interface RelayState {
+  readonly sessionId: string;
+  readonly port: PortLike;
+  queue: Promise<void>;
+}
+
+export interface ServiceWorkerRelay {
+  handle(envelope: HostEnvelope): Promise<void>;
+}
+
+/**
+ * Keep one virtual host port per logical app while treating each Service Worker
+ * realm as a new session. An attach from a replacement realm first tears down
+ * the previous port's subscriptions; frames from the superseded realm are then
+ * ignored instead of being attributed to the replacement.
+ */
+export function createServiceWorkerRelay(options: {
+  getCtx(): Promise<HostCtx>;
+  send(message: ServiceWorkerChannelMessage): void;
+  onError?(error: unknown, envelope: HostEnvelope): void;
+}): ServiceWorkerRelay {
+  const ports = new Map<string, RelayState>();
+
+  const makePort = (clientId: string, sessionId: string): PortLike => ({
+    postMessage(message) {
+      options.send({ direction: 'client', clientId, sessionId, message });
+    },
+  });
+
+  return {
+    async handle(envelope) {
+      if (envelope.phase === 'attach') {
+        const previous = ports.get(envelope.clientId);
+        if (previous?.sessionId === envelope.sessionId) {
+          await previous.queue;
+          return;
+        }
+        const state: RelayState = {
+          sessionId: envelope.sessionId,
+          port: makePort(envelope.clientId, envelope.sessionId),
+          queue: (previous?.queue ?? Promise.resolve()).then(async () => {
+            if (!previous) return;
+            try {
+              const ctx = await options.getCtx();
+              cleanupPort(ctx, previous.port);
+            } catch (error) {
+              options.onError?.(error, envelope);
+            }
+          }),
+        };
+        ports.set(envelope.clientId, state);
+        await state.queue;
+        return;
+      }
+
+      const state = ports.get(envelope.clientId);
+      if (!state || state.sessionId !== envelope.sessionId) return;
+      state.queue = state.queue.then(async () => {
+        try {
+          const ctx = await options.getCtx();
+          await handleMessage(ctx, state.port, envelope.message);
+          if (
+            envelope.message.t === 'disconnect'
+            && ports.get(envelope.clientId) === state
+          ) {
+            ports.delete(envelope.clientId);
+          }
+        } catch (error) {
+          options.onError?.(error, envelope);
+        }
+      });
+      await state.queue;
+    },
+  };
+}

package/src/serve/writer-lock.ts

@@ -0,0 +1,53 @@
+/**
+ * Single-writer lock for `--persist` (pre-mortem #3).
+ *
+ * Two tabs = two sandboxes, each flushing its WHOLE world view — so the
+ * second tab's flush doesn't merge, it ERASES everything the first wrote.
+ * "last-writer-wins" undersold it: last-tab's-universe wins, visibly, on the
+ * loser's next reload.
+ *
+ * The conflict only exists at WRITE time, so the lock is resolved there: the
+ * first page to flush claims the writer role (carried in the
+ * `x-pyric-writer` header); a different page's flush is refused (409) and
+ * that page drops to read-only persistence + a loud console line. A reader
+ * that never mutates never conflicts.
+ *
+ * Liveness: the holder refreshes `lastSeen` on every accepted write and via
+ * a periodic heartbeat. A holder that goes quiet for `staleMs` (crash, or an
+ * idle tab whose heartbeat also stopped) is considered gone, so a fresh page
+ * can claim the role — no permanent wedge. The small overlap window where a
+ * stale-but-alive holder and a new claimer both think they're the writer is
+ * an accepted dev-tool race (documented), kept rare by a generous staleMs.
+ */
+
+export interface WriterLock {
+  /** Claim/refresh for `id`. Granted when free, already held by `id`, or the
+   *  current holder is stale. Returns whether `id` now holds the lock. */
+  claim(id: string, now: number): boolean;
+  /** Release if `id` is the holder (no-op otherwise). */
+  release(id: string): void;
+  /** Current holder, or null. */
+  holder(): string | null;
+}
+
+export function createWriterLock(staleMs = 60_000): WriterLock {
+  let holder: string | null = null;
+  let lastSeen = 0;
+  return {
+    claim(id, now) {
+      if (holder === null || holder === id || now - lastSeen > staleMs) {
+        holder = id;
+        lastSeen = now;
+        return true;
+      }
+      return false;
+    },
+    release(id) {
+      if (holder === id) {
+        holder = null;
+        lastSeen = 0;
+      }
+    },
+    holder: () => holder,
+  };
+}

package/src/verify/cases.ts

@@ -0,0 +1,233 @@
+import type { RequestEvent } from 'pyric/sandbox';
+import type { FirestoreMethod, FunctionMock, TestCase } from 'pyric/rules/internal';
+import {
+  parseVerifyFixture,
+  type PyricVerifyFixture,
+} from './fixture.js';
+
+export type VerifyFixtureWarning = {
+  service: 'firestore';
+  eventId?: string;
+  path?: string;
+  method?: string;
+  code: string;
+  message: string;
+};
+
+export type VerifyUnsupportedEvent = {
+  service: 'firestore';
+  eventId?: string;
+  path?: string;
+  method?: string;
+  reason: string;
+};
+
+export interface DeriveRulesTestCasesOptions {
+  service?: 'firestore';
+  includeAllowed?: boolean;
+  includeDenied?: boolean;
+  mockReads?: 'strict' | 'omit';
+}
+
+export interface DerivedRulesTestCase {
+  eventId: string;
+  testCase: TestCase;
+}
+
+export interface DeriveRulesTestCasesResult {
+  ok: boolean;
+  service: 'firestore';
+  testCases: TestCase[];
+  derived: DerivedRulesTestCase[];
+  warnings: VerifyFixtureWarning[];
+  unsupportedEvents: VerifyUnsupportedEvent[];
+}
+
+export function deriveRulesTestCases(
+  fixtureInput: PyricVerifyFixture | unknown,
+  opts: DeriveRulesTestCasesOptions = {},
+): DeriveRulesTestCasesResult {
+  const fixture = parseVerifyFixture(fixtureInput);
+  const includeAllowed = opts.includeAllowed ?? true;
+  const includeDenied = opts.includeDenied ?? true;
+  const mockReads = opts.mockReads ?? 'strict';
+  const derived: DerivedRulesTestCase[] = [];
+  const warnings: VerifyFixtureWarning[] = [];
+  const unsupportedEvents: VerifyUnsupportedEvent[] = [];
+
+  for (const event of fixture.events) {
+    if (!isFirestoreRequestEvent(event)) continue;
+    if (event.origin === 'listener') continue;
+    if (event.detail?.admin === true) continue;
+    if (event.result === 'allow' && !includeAllowed) continue;
+    if (event.result === 'deny' && !includeDenied) continue;
+
+    if (event.result === 'unsupported') {
+      unsupportedEvents.push({
+        service: 'firestore',
+        eventId: event.id,
+        path: event.path,
+        method: event.method,
+        reason: event.reasons.join('\n') || 'captured Firestore request was unsupported locally.',
+      });
+      continue;
+    }
+
+    const method = lowerFirestoreMethod(event);
+    if (!method) {
+      unsupportedEvents.push({
+        service: 'firestore',
+        eventId: event.id,
+        path: event.path,
+        method: event.method,
+        reason: `cannot derive a Rules Test API case for Firestore method '${event.method}'.`,
+      });
+      continue;
+    }
+
+    const functionMocks = extractFunctionMocks(event);
+    if (mockReads === 'strict' && functionMocks === null) {
+      unsupportedEvents.push({
+        service: 'firestore',
+        eventId: event.id,
+        path: event.path,
+        method: event.method,
+        reason:
+          'captured request appears to depend on get()/exists(), but the fixture does not contain exact rule-read mocks.',
+      });
+      continue;
+    }
+    if (mockReads === 'omit' && eventMayNeedFunctionMocks(event)) {
+      warnings.push({
+        service: 'firestore',
+        eventId: event.id,
+        path: event.path,
+        method: event.method,
+        code: 'READ_MOCKS_OMITTED',
+        message:
+          'captured request may depend on get()/exists(); deriving the case without functionMocks may change hosted Rules Test API behavior.',
+      });
+    }
+
+    derived.push({
+      eventId: event.id,
+      testCase: buildTestCase(event, method, functionMocks ?? []),
+    });
+  }
+
+  return {
+    ok: unsupportedEvents.length === 0,
+    service: 'firestore',
+    testCases: derived.map((item) => item.testCase),
+    derived,
+    warnings,
+    unsupportedEvents,
+  };
+}
+
+function isFirestoreRequestEvent(event: unknown): event is RequestEvent {
+  if (!isCapturedRequestEvent(event) || event.kind !== 'request') return false;
+  const service = event.service;
+  return service === undefined || service === 'firestore';
+}
+
+function lowerFirestoreMethod(event: RequestEvent): FirestoreMethod | null {
+  if (event.method === 'get' || event.method === 'list' || event.method === 'create' || event.method === 'update' || event.method === 'delete') {
+    return event.method;
+  }
+  if (event.method === 'set') {
+    return event.resourceBefore?.exists ? 'update' : 'create';
+  }
+  return null;
+}
+
+function buildTestCase(
+  event: RequestEvent,
+  method: FirestoreMethod,
+  functionMocks: FunctionMock[],
+): TestCase {
+  const testCase: TestCase = {
+    description: `${event.result === 'allow' ? 'allow' : 'deny'} ${method} ${event.path}`,
+    expectation: event.result === 'allow' ? 'ALLOW' : 'DENY',
+    method,
+    path: event.path,
+    auth: event.auth,
+    requestTime: new Date(event.at).toISOString(),
+  };
+
+  if (event.resourceBefore?.exists && event.resourceBefore.data !== null) {
+    testCase.resource = event.resourceBefore.data;
+  }
+
+  if (isWriteMethod(method)) {
+    if (method !== 'delete') {
+      const data = event.resourceAfter?.data ?? event.request?.resourceData;
+      if (isFirestoreWriteData(data)) testCase.data = data;
+    }
+    testCase.writeMode = writeModeFor(method);
+  }
+
+  if (functionMocks.length > 0) {
+    testCase.functionMocks = functionMocks;
+  }
+
+  const query = (event.detail as { query?: unknown } | undefined)?.query;
+  if (isListQuery(query)) {
+    testCase.query = query;
+  }
+
+  return testCase;
+}
+
+function writeModeFor(method: FirestoreMethod): TestCase['writeMode'] | undefined {
+  if (method === 'create') return { kind: 'create' };
+  if (method === 'update') return { kind: 'update' };
+  if (method === 'delete') return { kind: 'delete' };
+  return undefined;
+}
+
+function isWriteMethod(method: FirestoreMethod): boolean {
+  return method === 'create' || method === 'update' || method === 'delete';
+}
+
+function extractFunctionMocks(event: RequestEvent): FunctionMock[] | null {
+  const detail = event.detail as { functionMocks?: unknown } | undefined;
+  if (Array.isArray(detail?.functionMocks)) {
+    return detail.functionMocks.filter(isFunctionMock);
+  }
+  return eventMayNeedFunctionMocks(event) ? null : [];
+}
+
+function isFunctionMock(value: unknown): value is FunctionMock {
+  if (!isFunctionMockCandidate(value)) return false;
+  if (value.function !== 'get' && value.function !== 'exists') return false;
+  return typeof value.path === 'string' && 'result' in value;
+}
+
+function isListQuery(value: unknown): value is NonNullable<TestCase['query']> {
+  if (!isListQueryCandidate(value)) return false;
+  if ('limit' in value && value.limit !== undefined && typeof value.limit !== 'number') return false;
+  if ('offset' in value && value.offset !== undefined && typeof value.offset !== 'number') return false;
+  if ('orderBy' in value && value.orderBy !== undefined && typeof value.orderBy !== 'string') return false;
+  return true;
+}
+
+function eventMayNeedFunctionMocks(event: RequestEvent): boolean {
+  return event.reasons.some((reason) => /\b(get|exists)\s*\(/.test(reason));
+}
+
+function isCapturedRequestEvent(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFirestoreWriteData(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFunctionMockCandidate(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isListQueryCandidate(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/verify/fixture.ts

@@ -0,0 +1,258 @@
+import type { EventService, Sandbox, SandboxEvent } from 'pyric/sandbox';
+import { getStorageSandbox } from 'pyric/storage';
+import { isRtdbRulesJson } from '../rtdb/rules-json.js';
+
+export const VERIFY_FIXTURE_SCHEMA = 'pyric.verify.fixture.v1' as const;
+
+export interface VerifyFirestoreRulesBlock {
+  format: 'firestore.rules';
+  source: string;
+}
+
+export interface VerifyRtdbRulesBlock {
+  format: 'rtdb.rules.json';
+  json: { rules: Record<string, unknown> };
+}
+
+export interface VerifyStorageRulesBlock {
+  format: 'storage.rules';
+  source: string;
+}
+
+export interface PyricVerifyFixture {
+  schema: typeof VERIFY_FIXTURE_SCHEMA;
+  description?: string;
+  createdAt?: string;
+  /** Opaque id of the sandbox instance that produced this capture (the served
+   *  SharedWorker's `instanceId`). Purely additive: `pyric verify` ignores it.
+   *  Present only on captures written by the worker's capture flush; used by
+   *  boot-time event hydration to SKIP priming a capture that belongs to a
+   *  DIFFERENT instance (e.g. another browser profile sharing one `pyric dev`),
+   *  so someone else's session never shows up as yours. Absent on older /
+   *  standalone captures → hydration primes best-effort. */
+  capturedBy?: string;
+  events: SandboxEvent[];
+  services: {
+    firestore?: {
+      rules: VerifyFirestoreRulesBlock;
+      state: { documents: Record<string, Record<string, unknown>> };
+    };
+    rtdb?: {
+      rules: VerifyRtdbRulesBlock;
+      state: { tree: unknown };
+      databaseUrl?: string;
+    };
+    auth?: {
+      state: {
+        users?: unknown[];
+        currentUser?: unknown;
+      };
+    };
+    storage?: {
+      /** RULES TEXT ONLY — captured object state is a separate, larger
+       *  redesign (persistence.ts's IDB blob store) and is deliberately
+       *  left untouched here. `state` stays `null` until that lands. */
+      rules: VerifyStorageRulesBlock;
+      state: unknown;
+    };
+    [service: string]: unknown;
+  };
+}
+
+export interface BuildVerifyFixtureInput {
+  sandbox: Pick<Sandbox, 'history' | 'snapshot'> & { currentUser?: unknown };
+  description?: string;
+  firestoreRules?: string | null;
+  rtdbRules?: { rules: Record<string, unknown> } | null;
+  rtdbState?: unknown;
+  rtdbDatabaseUrl?: string | null;
+  /** Currently-deployed storage rules text. RULES ONLY — there is no
+   *  `storageState` input; captured storage OBJECTS are a separate,
+   *  larger redesign left untouched by this fixture. */
+  storageRules?: string | null;
+  authState?: {
+    users?: unknown[];
+    currentUser?: unknown;
+  } | null;
+  createdAt?: string;
+  /** Stamped into the fixture as `capturedBy` (identity for boot-time event
+   *  hydration). Omit for `pyric verify` builds — they have no instance. */
+  capturedBy?: string;
+}
+
+export function buildVerifyFixture(input: BuildVerifyFixtureInput): PyricVerifyFixture {
+  const events = input.sandbox.history();
+  const snapshot = input.sandbox.snapshot();
+  const firestoreDocuments = snapshot.firestore;
+  const services: PyricVerifyFixture['services'] = {};
+
+  if (
+    input.firestoreRules != null ||
+    Object.keys(firestoreDocuments).length > 0 ||
+    events.some((event) => eventService(event) === 'firestore')
+  ) {
+    services.firestore = {
+      rules: {
+        format: 'firestore.rules',
+        source: input.firestoreRules ?? '',
+      },
+      state: { documents: firestoreDocuments },
+    };
+  }
+
+  if (
+    input.rtdbRules != null ||
+    input.rtdbState !== undefined ||
+    events.some((event) => eventService(event) === 'rtdb')
+  ) {
+    services.rtdb = {
+      rules: {
+        format: 'rtdb.rules.json',
+        json: input.rtdbRules ?? { rules: {} },
+      },
+      state: { tree: input.rtdbState ?? null },
+      ...(input.rtdbDatabaseUrl ? { databaseUrl: input.rtdbDatabaseUrl } : {}),
+    };
+  }
+
+  if (
+    input.storageRules != null ||
+    events.some((event) => eventService(event) === 'storage')
+  ) {
+    services.storage = {
+      rules: {
+        format: 'storage.rules',
+        source: input.storageRules ?? '',
+      },
+      // RULES TEXT ONLY (scope note above) — objects are never captured.
+      state: null,
+    };
+  }
+
+  const authUsers = input.authState?.users;
+  const currentUser = input.authState?.currentUser ?? input.sandbox.currentUser;
+  if ((authUsers && authUsers.length > 0) || currentUser != null) {
+    services.auth = {
+      state: {
+        ...(authUsers ? { users: authUsers } : {}),
+        ...(currentUser != null ? { currentUser } : {}),
+      },
+    };
+  }
+
+  return {
+    schema: VERIFY_FIXTURE_SCHEMA,
+    ...(input.description ? { description: input.description } : {}),
+    createdAt: input.createdAt ?? new Date().toISOString(),
+    ...(input.capturedBy ? { capturedBy: input.capturedBy } : {}),
+    events,
+    services,
+  };
+}
+
+export function parseVerifyFixture(value: unknown): PyricVerifyFixture {
+  if (!isVerifyFixtureObject(value)) {
+    throw new Error('fixture must be a JSON object.');
+  }
+  if (value.schema !== VERIFY_FIXTURE_SCHEMA) {
+    throw new Error(`fixture schema must be '${VERIFY_FIXTURE_SCHEMA}'.`);
+  }
+  if (!Array.isArray(value.events)) {
+    throw new Error('fixture.events must be an array.');
+  }
+  if (!isVerifyFixtureObject(value.services)) {
+    throw new Error('fixture.services must be an object.');
+  }
+
+  const services = value.services;
+  if (services.firestore !== undefined) {
+    assertFirestoreService(services.firestore);
+  }
+  if (services.rtdb !== undefined) {
+    assertRtdbService(services.rtdb);
+  }
+  if (services.storage !== undefined) {
+    assertStorageService(services.storage);
+  }
+  if (services.auth !== undefined && !isVerifyFixtureObject(services.auth)) {
+    throw new Error('fixture.services.auth must be an object.');
+  }
+
+  return value as unknown as PyricVerifyFixture;
+}
+
+export function fixtureVerifiableServices(
+  fixture: PyricVerifyFixture,
+): Array<'firestore' | 'rtdb'> {
+  const services: Array<'firestore' | 'rtdb'> = [];
+  if (fixture.services.firestore) services.push('firestore');
+  if (fixture.services.rtdb) services.push('rtdb');
+  return services;
+}
+
+function assertFirestoreService(value: unknown): void {
+  if (!isVerifyFixtureObject(value)) throw new Error('fixture.services.firestore must be an object.');
+  if (!isVerifyFixtureObject(value.rules) || value.rules.format !== 'firestore.rules' || typeof value.rules.source !== 'string') {
+    throw new Error('fixture.services.firestore.rules must contain firestore.rules source.');
+  }
+  if (!isVerifyFixtureObject(value.state) || !isVerifyFixtureObject(value.state.documents)) {
+    throw new Error('fixture.services.firestore.state.documents must be an object.');
+  }
+}
+
+function assertRtdbService(value: unknown): void {
+  if (!isVerifyFixtureObject(value)) throw new Error('fixture.services.rtdb must be an object.');
+  if (
+    !isVerifyFixtureObject(value.rules) ||
+    value.rules.format !== 'rtdb.rules.json' ||
+    !isRtdbRulesJson(value.rules.json)
+  ) {
+    throw new Error('fixture.services.rtdb.rules must contain RTDB rules JSON.');
+  }
+  if (!isVerifyFixtureObject(value.state) || !('tree' in value.state)) {
+    throw new Error('fixture.services.rtdb.state.tree is required.');
+  }
+}
+
+function assertStorageService(value: unknown): void {
+  if (!isVerifyFixtureObject(value)) throw new Error('fixture.services.storage must be an object.');
+  if (
+    !isVerifyFixtureObject(value.rules) ||
+    value.rules.format !== 'storage.rules' ||
+    typeof value.rules.source !== 'string'
+  ) {
+    throw new Error('fixture.services.storage.rules must contain storage.rules source.');
+  }
+}
+
+/**
+ * Re-deploy a fixture's captured storage rules into a sandbox's storage
+ * evaluator. RULES TEXT ONLY, mirroring the capture-side scope note: this
+ * never touches storage OBJECTS (persistence.ts's IDB blob store) — only
+ * `fixture.services.storage.rules.source` is applied.
+ *
+ * Storage rules are honored only on the FIRST `getStorageSandbox` call per
+ * `Sandbox` (see `storage/service.ts`), so this must run before any other
+ * code opens the storage service on `sandbox` — exactly the same ordering
+ * constraint firestore/rtdb rules already have at restore time. A no-op
+ * when the fixture carries no storage block.
+ */
+export function restoreStorageRulesFromFixture(
+  fixture: PyricVerifyFixture,
+  sandbox: Sandbox,
+): void {
+  const source = fixture.services.storage?.rules?.source;
+  if (source === undefined) return;
+  getStorageSandbox(sandbox, { rules: source });
+}
+
+function eventService(event: SandboxEvent): EventService {
+  if ('service' in event && typeof event.service === 'string') {
+    return event.service as EventService;
+  }
+  return 'firestore';
+}
+
+function isVerifyFixtureObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}