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

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/standalone-assets.ts

@@ -31,7 +31,7 @@ export interface EmbeddedAssets {
    * materialization cache. Optional so older compiled binaries still boot.
    */
   assetVersion?: string;
-  /** Worker source hash stamped into the page (`<meta name="pyric-worker-v">`). */
+  /** Worker executable epoch stamped into the page (`<meta name="pyric-worker-v">`). */
   workerVersion: string;
   /** Lazy: flat map of SDK filename -> base64 bytes (app.js, worker.js, chunks). */
   sdk: () => Promise<Record<string, string>>;
@@ -68,7 +68,7 @@ function embedded(): EmbeddedAssets {
   return e;
 }
 
-/** The worker content hash baked in at compile time (see serve.ts). */
+/** The worker executable epoch baked in at compile time (see serve.ts). */
 export function embeddedWorkerVersion(): string {
   return embedded().workerVersion;
 }

package/src/serve/vite-ai-config.ts

@@ -0,0 +1,77 @@
+import type { AIOptions } from 'pyric/ai';
+import path from 'node:path';
+import { loadEnv } from 'vite';
+import type { AiEngineConfigWire } from './worker/protocol.js';
+
+const AI_PROXY_PATH = '/__pyric/ai-proxy';
+
+/** Declarative AI engines that can cross Vite's page/SharedWorker boundary. */
+export type PyricAiEngineConfig = Extract<NonNullable<AIOptions['engine']>, { kind: string }>;
+
+export interface PyricAiOptions {
+  /** Simple OpenAI-compatible model selection through Pyric's same-origin proxy. */
+  model?: string;
+  /** Advanced declarative engine configuration. */
+  engine?: PyricAiEngineConfig;
+  /** OpenAI-compatible upstream used by the same-origin proxy. */
+  proxyUpstream?: string;
+}
+
+export interface ResolvedViteAiConfig {
+  engineWire: AiEngineConfigWire | undefined;
+  proxyUpstream: string | undefined;
+}
+
+/** Load env using Vite's `envDir`-relative-to-root convention. */
+export function loadViteAiEnv(
+  mode: string,
+  root: string | undefined,
+  envDir: string | undefined,
+): Record<string, string> {
+  const resolvedRoot = path.resolve(root ?? process.cwd());
+  const resolvedEnvDir = envDir === undefined
+    ? resolvedRoot
+    : path.resolve(resolvedRoot, envDir);
+  return loadEnv(mode, resolvedEnvDir, '');
+}
+
+/** Convert a public declarative engine into the JSON-safe worker wire shape. */
+export function engineConfigToWire(engine: PyricAiEngineConfig): AiEngineConfigWire {
+  if (engine.kind === 'openai') {
+    return {
+      kind: 'openai',
+      baseUrl: engine.baseUrl ?? AI_PROXY_PATH,
+      ...(engine.model !== undefined ? { model: engine.model } : {}),
+      ...(engine.modelMap !== undefined ? { modelMap: engine.modelMap } : {}),
+    };
+  }
+  return {
+    kind: 'scripted',
+    ...(engine.script !== undefined
+      ? { script: engine.script as unknown as Array<Record<string, unknown>> }
+      : {}),
+  };
+}
+
+/** Resolve the plugin's explicit-options-over-Vite-env AI convention. */
+export function resolveViteAiConfig(
+  options: PyricAiOptions | undefined,
+  env: Record<string, string | undefined>,
+): ResolvedViteAiConfig {
+  if (options?.model !== undefined && options.engine !== undefined) {
+    throw new Error('@pyric/cli/vite: Choose either ai.model or ai.engine, not both.');
+  }
+
+  const model = options?.model?.trim() || env.PYRIC_AI_MODEL?.trim();
+  const engineWire = options?.engine
+    ? engineConfigToWire(options.engine)
+    : model
+      ? engineConfigToWire({ kind: 'openai', baseUrl: AI_PROXY_PATH, model })
+      : undefined;
+
+  return {
+    engineWire,
+    proxyUpstream:
+      options?.proxyUpstream?.trim() || env.PYRIC_AI_PROXY_UPSTREAM?.trim() || undefined,
+  };
+}