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

package/src/serve/runtime/manifest.ts

@@ -0,0 +1,37 @@
+/** Stable routes and identity used by the served runtime and its UI. */
+export const PYRIC_WORKER_URL = '/__pyric/sdk/worker.js';
+export const PYRIC_WORKER_NAME = 'pyric-shared-worker';
+export const PYRIC_STUDIO_URL = '/__pyric/ui/';
+
+export interface PyricRuntimeManifest {
+  studioUrl: string;
+  worker: {
+    url: string;
+    name: string;
+    /** Content epoch served by the current dev server; null in in-page mode. */
+    servedEpoch: string | null;
+  };
+}
+
+interface RuntimeDocument {
+  querySelector(selector: string): { getAttribute(name: string): string | null } | null;
+}
+
+/** Read the server-stamped worker epoch before application code starts. */
+export function readPyricRuntimeManifest(
+  documentLike: RuntimeDocument | undefined = typeof document === 'undefined' ? undefined : document,
+): PyricRuntimeManifest {
+  const servedEpoch = documentLike
+    ?.querySelector('meta[name="pyric-worker-v"]')
+    ?.getAttribute('content')
+    ?.trim() || null;
+
+  return {
+    studioUrl: PYRIC_STUDIO_URL,
+    worker: {
+      url: PYRIC_WORKER_URL,
+      name: PYRIC_WORKER_NAME,
+      servedEpoch,
+    },
+  };
+}

package/src/serve/runtime/status.ts

@@ -0,0 +1,216 @@
+import type { SandboxEvent } from 'pyric/sandbox';
+import type { PyricRuntimeManifest } from './manifest.js';
+import { readPyricRuntimeManifest } from './manifest.js';
+
+export type PyricRuntimeMode = 'starting' | 'shared-worker' | 'in-page';
+export type PyricRuntimeErrorSource = 'sandbox' | 'worker' | 'runtime';
+
+export interface PyricRuntimeError {
+  id: string;
+  source: PyricRuntimeErrorSource;
+  at: number;
+  message: string;
+  code?: string;
+  stack?: string;
+  service?: string;
+  method?: string;
+  path?: string;
+}
+
+export interface PyricRuntimeSnapshot {
+  manifest: PyricRuntimeManifest;
+  mode: PyricRuntimeMode;
+  servedEpoch: string | null;
+  runningEpoch: string | null;
+  updateAvailable: boolean;
+  updatingWorker: boolean;
+  errors: readonly PyricRuntimeError[];
+}
+
+export interface PyricRuntimeStatus {
+  getSnapshot(): PyricRuntimeSnapshot;
+  subscribe(listener: (snapshot: PyricRuntimeSnapshot) => void): () => void;
+  setWorker(input: { mode: Exclude<PyricRuntimeMode, 'starting'>; runningEpoch?: string | null }): void;
+  setWorkerUpdater(update: (() => Promise<void>) | null): void;
+  updateWorker(): Promise<void>;
+  reportError(error: unknown, source: PyricRuntimeErrorSource): void;
+  recordSandboxEvents(events: readonly SandboxEvent[]): void;
+  clearErrors(): void;
+}
+
+let nextErrorId = 0;
+
+function errorCode(value: unknown): string | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const code = (value as { code?: unknown }).code;
+  return typeof code === 'string' ? code : undefined;
+}
+
+/** Convert thrown values into a serializable, copyable runtime error. */
+export function normalizePyricRuntimeError(
+  value: unknown,
+  source: PyricRuntimeErrorSource,
+  at = Date.now(),
+  id = `runtime-error-${++nextErrorId}`,
+): PyricRuntimeError {
+  if (value instanceof Error) {
+    return {
+      id,
+      source,
+      at,
+      message: value.message,
+      ...(errorCode(value) ? { code: errorCode(value) } : {}),
+      ...(value.stack ? { stack: value.stack } : {}),
+    };
+  }
+  if (typeof value === 'string') return { id, source, at, message: value };
+  if (value && typeof value === 'object') {
+    const message = (value as { message?: unknown }).message;
+    return {
+      id,
+      source,
+      at,
+      message: typeof message === 'string' ? message : String(value),
+      ...(errorCode(value) ? { code: errorCode(value) } : {}),
+    };
+  }
+  return { id, source, at, message: String(value) };
+}
+
+function sandboxError(event: SandboxEvent): PyricRuntimeError | null {
+  if (event.kind === 'runtime_error') {
+    return {
+      id: event.id,
+      source: 'sandbox',
+      at: event.at,
+      service: event.service,
+      method: event.method,
+      ...(event.path ? { path: event.path } : {}),
+      ...(event.error.code ? { code: event.error.code } : {}),
+      message: event.error.message,
+    };
+  }
+  if (event.kind === 'listener_errored' && event.error) {
+    return {
+      id: event.id,
+      source: 'sandbox',
+      at: event.at,
+      service: 'firestore',
+      method: 'listener',
+      ...('path' in event.target ? { path: event.target.path } : {}),
+      code: event.error.code,
+      message: event.error.message,
+    };
+  }
+  if (event.kind === 'listener' && event.phase === 'errored' && event.error) {
+    return {
+      id: event.id,
+      source: 'sandbox',
+      at: event.at,
+      service: event.service,
+      method: 'listener',
+      ...(event.target.path ? { path: event.target.path } : {}),
+      ...(event.error.code ? { code: event.error.code } : {}),
+      message: event.error.message,
+    };
+  }
+  return null;
+}
+
+/** Observable, bounded status model shared by the runtime and injected UI. */
+export function createPyricRuntimeStatus(
+  manifest: PyricRuntimeManifest,
+  options: { maxErrors?: number } = {},
+): PyricRuntimeStatus {
+  const maxErrors = Math.max(1, options.maxErrors ?? 50);
+  const listeners = new Set<(snapshot: PyricRuntimeSnapshot) => void>();
+  const errorIds = new Set<string>();
+  let snapshot: PyricRuntimeSnapshot = {
+    manifest,
+    mode: 'starting',
+    servedEpoch: manifest.worker.servedEpoch,
+    runningEpoch: null,
+    updateAvailable: false,
+    updatingWorker: false,
+    errors: [],
+  };
+  let workerUpdater: (() => Promise<void>) | null = null;
+
+  const publish = (next: PyricRuntimeSnapshot): void => {
+    snapshot = next;
+    for (const listener of listeners) listener(snapshot);
+  };
+  const appendError = (error: PyricRuntimeError): void => {
+    if (errorIds.has(error.id)) return;
+    errorIds.add(error.id);
+    const errors = [...snapshot.errors, error].slice(-maxErrors);
+    const retained = new Set(errors.map((item) => item.id));
+    for (const id of errorIds) if (!retained.has(id)) errorIds.delete(id);
+    publish({ ...snapshot, errors });
+  };
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(snapshot);
+      return () => listeners.delete(listener);
+    },
+    setWorker({ mode, runningEpoch = null }) {
+      const servedEpoch = manifest.worker.servedEpoch;
+      publish({
+        ...snapshot,
+        mode,
+        runningEpoch,
+        updateAvailable: Boolean(
+          mode === 'shared-worker'
+          && servedEpoch
+          && runningEpoch
+          && runningEpoch !== 'dev'
+          && servedEpoch !== runningEpoch,
+        ),
+        updatingWorker: false,
+      });
+    },
+    setWorkerUpdater(update) {
+      workerUpdater = update;
+    },
+    async updateWorker() {
+      if (!snapshot.updateAvailable || snapshot.updatingWorker || !workerUpdater) {
+        throw new Error('No Pyric worker update is available.');
+      }
+      publish({ ...snapshot, updatingWorker: true });
+      try {
+        await workerUpdater();
+      } catch (error) {
+        publish({ ...snapshot, updatingWorker: false });
+        appendError(normalizePyricRuntimeError(error, 'worker'));
+        throw error;
+      }
+    },
+    reportError(error, source) {
+      appendError(normalizePyricRuntimeError(error, source));
+    },
+    recordSandboxEvents(events) {
+      for (const event of events) {
+        const normalized = sandboxError(event);
+        if (normalized) appendError(normalized);
+      }
+    },
+    clearErrors() {
+      errorIds.clear();
+      publish({ ...snapshot, errors: [] });
+    },
+  };
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __pyricRuntime: PyricRuntimeStatus | undefined;
+}
+
+/** One global status source even when the runtime and UI are separate bundles. */
+export function getPyricRuntimeStatus(): PyricRuntimeStatus {
+  return globalThis.__pyricRuntime
+    ??= createPyricRuntimeStatus(readPyricRuntimeManifest());
+}

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

@@ -0,0 +1,14 @@
+import type { ClientDb } from '../worker/client/handles.js';
+
+/** Construct the control connection without letting a browser policy failure abort runtime boot. */
+export function connectRuntimeWorker(
+  connect: () => ClientDb,
+  reportError: (error: unknown) => void,
+): ClientDb | null {
+  try {
+    return connect();
+  } catch (error) {
+    reportError(error);
+    return null;
+  }
+}

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

@@ -0,0 +1,75 @@
+import { PYRIC_WORKER_NAME } from './manifest.js';
+
+export const PYRIC_WORKER_GENERATION_KEY = 'pyric:worker-generation';
+const PYRIC_WORKER_GENERATION_PROBE_KEY = 'pyric:worker-generation-probe';
+
+interface EpochStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem?(key: string): void;
+}
+
+/** Select the replacement generation only after this page was told to move. */
+export function workerNameForEpoch(
+  _servedEpoch: string | null,
+  storage: EpochStorage | undefined,
+): string {
+  if (!storage) return PYRIC_WORKER_NAME;
+  try {
+    const generation = storage.getItem(PYRIC_WORKER_GENERATION_KEY);
+    return generation && /^[a-f0-9]{16}$/.test(generation)
+      ? `${PYRIC_WORKER_NAME}:${generation}`
+      : PYRIC_WORKER_NAME;
+  } catch {
+    return PYRIC_WORKER_NAME;
+  }
+}
+
+/** Persist the generation boundary before a page reloads. */
+export function rememberWorkerEpoch(
+  epoch: string,
+  storage: EpochStorage | undefined,
+): void {
+  if (!/^[a-f0-9]{16}$/.test(epoch)) {
+    throw new Error('Pyric cannot replace the worker: invalid served worker epoch.');
+  }
+  if (!storage) {
+    throw new Error(
+      'Pyric cannot replace the worker because origin storage is unavailable. Close all tabs for this origin and reopen the app.',
+    );
+  }
+  try {
+    storage.setItem(PYRIC_WORKER_GENERATION_KEY, epoch);
+    if (storage.getItem(PYRIC_WORKER_GENERATION_KEY) !== epoch) {
+      throw new Error('the worker generation could not be read back');
+    }
+  } catch (cause) {
+    throw new Error(
+      'Pyric cannot replace the worker because origin storage is unavailable. Close all tabs for this origin and reopen the app.',
+      { cause },
+    );
+  }
+}
+
+/** Prove origin storage works without publishing a successor generation. */
+export function preflightWorkerEpochStorage(storage: EpochStorage | undefined): void {
+  if (!storage?.removeItem) {
+    throw new Error(
+      'Pyric cannot replace the worker because origin storage is unavailable. Close all tabs for this origin and reopen the app.',
+    );
+  }
+  try {
+    const previousProbe = storage.getItem(PYRIC_WORKER_GENERATION_PROBE_KEY);
+    storage.setItem(PYRIC_WORKER_GENERATION_PROBE_KEY, 'ok');
+    if (storage.getItem(PYRIC_WORKER_GENERATION_PROBE_KEY) !== 'ok') {
+      throw new Error('the worker generation probe could not be read back');
+    }
+    if (previousProbe === null) storage.removeItem(PYRIC_WORKER_GENERATION_PROBE_KEY);
+    else storage.setItem(PYRIC_WORKER_GENERATION_PROBE_KEY, previousProbe);
+  } catch (cause) {
+    throw new Error(
+      'Pyric cannot replace the worker because origin storage is unavailable. Close all tabs for this origin and reopen the app.',
+      { cause },
+    );
+  }
+}

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

@@ -0,0 +1,42 @@
+interface WorkerReplacementOptions {
+  targetEpoch: string;
+  retire(): Promise<void>;
+  subscribeReload(listener: (epoch: string) => void): () => void;
+  preflight(): void;
+  commitGeneration(epoch: string): void;
+  onPreparationError?(error: unknown): void;
+  reload(): void;
+  schedule?: (run: () => void) => void;
+}
+
+export interface WorkerReplacement {
+  request(): Promise<void>;
+  dispose(): void;
+}
+
+/** Coordinate one reload per page after the old SharedWorker announces retirement. */
+export function createWorkerReplacement(options: WorkerReplacementOptions): WorkerReplacement {
+  const schedule = options.schedule ?? ((run) => { setTimeout(run, 100); });
+  let reloadScheduled = false;
+  const unsubscribe = options.subscribeReload((epoch) => {
+    if (reloadScheduled) return;
+    try {
+      options.commitGeneration(epoch);
+    } catch (error) {
+      options.onPreparationError?.(error);
+      return;
+    }
+    reloadScheduled = true;
+    schedule(options.reload);
+  });
+  return {
+    async request() {
+      // Verify that this page can persist the successor before asking the old
+      // worker to retire, but do not publish that successor until the worker
+      // announces that its drain and capture barrier completed.
+      options.preflight();
+      await options.retire();
+    },
+    dispose: unsubscribe,
+  };
+}

package/src/serve/sandbox-marker.ts

@@ -0,0 +1,31 @@
+/**
+ * The sandbox-build marker — the single source of truth shared by the three
+ * places that produce or read it: the Vite plugin stamps it into a
+ * `vite build --mode pyric` output's `index.html`; `pyric dev` trusts it (a
+ * marked dist bundles pyric's in-page adapters, so its assets never inline the
+ * real SDK and the inlined-firebase scanner is skipped).
+ *
+ * Dependency-free (fs/path only) so the dev server can read it without pulling
+ * in the browser bundler.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The attribute stamped into a sandbox build's `index.html` head. Presence in
+ *  an asset's text is the signal — the value is fixed, never parsed. */
+export const SANDBOX_BUILD_MARKER = 'data-pyric-sandbox-build';
+
+/** The full `<meta>` tag the plugin injects at the start of `<head>`. */
+export const SANDBOX_BUILD_META = `<meta name="pyric-sandbox-build" content="1" ${SANDBOX_BUILD_MARKER}>`;
+
+/** True when `dir`'s `index.html` carries the sandbox-build marker. Missing or
+ *  unreadable index → false (treated as an ordinary build). */
+export function hasSandboxBuildMarker(dir: string): boolean {
+  const index = join(dir, 'index.html');
+  if (!existsSync(index)) return false;
+  try {
+    return readFileSync(index, 'utf8').includes(SANDBOX_BUILD_MARKER);
+  } catch {
+    return false;
+  }
+}