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

package/src/serve/discovery.ts

@@ -0,0 +1,199 @@
+/**
+ * Discovery of a RUNNING `pyric dev --bridge` — shared by the stdio MCP
+ * proxy (`cli/mcp-proxy.ts`) and the Node remote-sandbox client
+ * (`remote/index.ts`). Extracted here so both speak the SAME pointer +
+ * identity-pinning rules instead of drifting copies.
+ *
+ * Strategy: the `.pyric/serve.json` pointer serve writes in the project cwd
+ * (exact + project-correct) first, then a health probe across the scan
+ * window as a fallback. Degrades LEGIBLY: if no serve is found, or the
+ * pointed server's identity can't be matched, callers get `null` (plus a
+ * `log` diagnostic) — never a silent wrong-server hit.
+ *
+ * IDENTITY — the discovery pointer records the bridge's `instanceId`; a
+ * server is accepted only if its `/__pyric/health` reports the SAME id. Two
+ * sandboxes can collide on one port across loopback families (IPv4 `*:P` +
+ * `[::1]:P`); without this, a client locks onto whichever family answers
+ * first while the browser is on the other — split-brain.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Ports probed when the pointer is absent — serve's default scan window PLUS
+ *  the vite-plugin default (5174), which the plain 3473+ window would miss (so a
+ *  vite-only project was never found by scan). The standalone `pyric bridge`
+ *  serves `/health` (not `/__pyric/health`) and writes no pointer, so it is
+ *  registered directly via `claude mcp add`, not discovered here. */
+export const SCAN_PORTS = [3473, 3474, 3475, 3476, 3477, 5174];
+export const POINTER = join('.pyric', 'serve.json');
+
+export interface HealthLite {
+  mode?: string;
+  instanceId?: string;
+  /** Whether a browser tab is currently connected as the sandbox peer. */
+  sandboxConnected?: boolean;
+}
+
+export interface Discovered {
+  mcpUrl: string;
+  /**
+   * The CANONICAL display URL — what a human/browser should OPEN. Comes from
+   * the serve-written pointer when present (`http://localhost:<port>` for the
+   * default host, the explicit `--host` otherwise); falls back to
+   * `http://localhost:<port>`. NEVER a literal loopback address: to a browser
+   * `localhost` and `127.0.0.1` are DIFFERENT ORIGINS (different
+   * SharedWorkers, so different sandboxes), and serve's banner/auto-open use
+   * `localhost` — guidance built from this field must land on the SAME origin.
+   * Node-side connectivity uses `base`/`mcpUrl` instead.
+   */
+  url: string;
+  /** `http://<family>:<port>` the server actually answered on. */
+  base: string;
+  /** Identity pinned at discovery. Null only when talking to an older server
+   *  that predates the instanceId field (matching is then skipped). */
+  instanceId: string | null;
+  source: string;
+}
+
+/**
+ * Probe BOTH loopback families on a port and return the base that answers.
+ *
+ * Hostname-based URLs are a trap here: serve writes `http://localhost:...`
+ * for humans (browsers dual-stack fine), but `localhost` resolution differs
+ * by runtime — node/undici prefers IPv6 `::1`, and a serve under one runtime
+ * may bind `127.0.0.1`-only while under another binds `::1`-only. So a
+ * discovery client never trusts the hostname: it takes the PORT and tries
+ * explicit `127.0.0.1` and `[::1]`, using whichever the server is actually on.
+ */
+export function basesForPort(port: number): string[] {
+  return [`http://127.0.0.1:${port}`, `http://[::1]:${port}`];
+}
+
+export async function probeHealth(base: string): Promise<HealthLite | null> {
+  try {
+    const res = await fetch(`${base}/__pyric/health`, { signal: AbortSignal.timeout(1000) });
+    if (res.status !== 200) return null;
+    const body = (await res.json()) as HealthLite;
+    return body.mode === 'sandbox' ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * First loopback base on `port` whose health reports a sandbox bridge. With an
+ * `expectedInstanceId`, returns ONLY a family whose health identity matches —
+ * so when two sandboxes collide on one port across families, the client locks
+ * onto the one the pointer names, not merely the first to answer. (An older
+ * server with no `instanceId` field can't be identity-checked; matching is
+ * skipped in that case so the pointer still resolves.)
+ */
+export async function healthyBase(
+  port: number,
+  expectedInstanceId?: string | null,
+): Promise<{ base: string; instanceId: string | null } | null> {
+  for (const base of basesForPort(port)) {
+    const health = await probeHealth(base);
+    if (!health) continue;
+    const id = health.instanceId ?? null;
+    // Healthy but the WRONG server (the cross-family squatter): skip, try next.
+    if (expectedInstanceId && id !== expectedInstanceId) continue;
+    return { base, instanceId: id };
+  }
+  return null;
+}
+
+/** Best-effort port extraction from a pointer url/mcpUrl. */
+function portOf(u: string | undefined): number | null {
+  const m = u?.match(/:(\d{2,5})(?:\/|$)/);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Canonical display URL for a serve on `port`. Prefers the pointer's own
+ * `url` (serve writes `http://<requested host>:<port>` — `localhost` for the
+ * default, the explicit `--host` otherwise) so guidance shares the origin the
+ * banner/auto-open used; falls back to `http://localhost:<port>` (browsers
+ * resolve `localhost` dual-stack, so it reaches either loopback family).
+ */
+export function canonicalServeUrl(port: number, pointerUrl?: string): string {
+  if (pointerUrl) {
+    try {
+      const u = new URL(pointerUrl);
+      if (u.protocol === 'http:' || u.protocol === 'https:') {
+        return `${u.protocol}//${u.host}`;
+      }
+    } catch {
+      /* malformed pointer url — fall through to the localhost default */
+    }
+  }
+  return `http://localhost:${port}`;
+}
+
+/** Find the running serve: pointer first (in `cwd`), then a port scan. The
+ *  pointer gives the PORT and (when present) the identity; the family is
+ *  resolved by probing, so the returned base always uses the address the
+ *  server is actually reachable on. */
+export async function discoverServe(
+  cwd: string,
+  log: (m: string) => void = () => {},
+  // Injectable so discovery can be tested hermetically — the default scan probes
+  // real localhost ports, which a test environment can't guarantee are free.
+  scanPorts: number[] = SCAN_PORTS,
+): Promise<Discovered | null> {
+  const pointerPath = join(cwd, POINTER);
+  if (existsSync(pointerPath)) {
+    try {
+      const p = JSON.parse(readFileSync(pointerPath, 'utf8')) as {
+        url?: string;
+        mcpUrl?: string;
+        port?: number;
+        instanceId?: string;
+      };
+      const port = p.port ?? portOf(p.mcpUrl) ?? portOf(p.url);
+      if (port) {
+        const expectedId = typeof p.instanceId === 'string' && p.instanceId ? p.instanceId : null;
+        const hit = await healthyBase(port, expectedId);
+        if (hit) {
+          return {
+            mcpUrl: `${hit.base}/__pyric/mcp`,
+            url: canonicalServeUrl(port, p.url),
+            base: hit.base,
+            instanceId: hit.instanceId,
+            source: `pointer ${POINTER}`,
+          };
+        }
+        // The pointer named a specific identity we could NOT find on its port:
+        // a different sandbox may be squatting it (cross-family collision) or
+        // the server stopped. Do NOT scan into a possibly-wrong server — that
+        // split-brain is exactly what this identity check prevents. Fail legibly.
+        if (expectedId) {
+          log(
+            `pointer ${POINTER} names a server (instanceId ${expectedId.slice(0, 8)}…) ` +
+              `that isn't answering on port ${port} — another sandbox may be squatting the ` +
+              `port on the other loopback family, or the server stopped. Not falling back to ` +
+              `a blind port scan (it could hit the wrong sandbox). Restart your dev server, ` +
+              `and open the exact URL it prints (http://localhost:<port> by default) — every ` +
+              `page must share that ONE origin, or the browser splits into separate sandboxes.`,
+          );
+          return null;
+        }
+      }
+    } catch {
+      /* stale/corrupt pointer — fall through to scan */
+    }
+  }
+  for (const port of scanPorts) {
+    const hit = await healthyBase(port);
+    if (hit) {
+      return {
+        mcpUrl: `${hit.base}/__pyric/mcp`,
+        url: canonicalServeUrl(port),
+        base: hit.base,
+        instanceId: hit.instanceId,
+        source: `port scan (:${port})`,
+      };
+    }
+  }
+  return null;
+}

package/src/serve/entries/ai.ts

@@ -0,0 +1,292 @@
+/**
+ * The bundle the import map serves for `firebase/ai`.
+ *
+ * DUAL-PATH (cdd-deltas #98): the FULL `pyric/ai` mirror surface
+ * (GenerativeModel / ChatSession / Schema / enums) always runs in-page —
+ * but ANSWERING follows the sandbox. When a SharedWorker is available, the
+ * broker + engines live in the WORKER HOST, in-process with the ONE shared
+ * sandbox (#98.1): `getAI` plugs a port-forwarding AnswerEngine into the
+ * in-page mirror, so every `generateContent` / `streamGenerateContent` /
+ * `countTokens` rides the worker protocol's `ai.*` ops (#98.3) and the
+ * worker broker's `service: 'ai'` events land on the shared event stream
+ * Studio consumes. Otherwise the mirror runs whole against the in-page
+ * sandbox — the unchanged fallback. Branch picked ONCE at load (`useWorker`).
+ *
+ * OPENAI ENGINE IN THE BROWSER (#98.2): an `engine: { kind: 'openai' }`
+ * config with no `baseUrl` targets serve's same-origin `/__pyric/ai-proxy`
+ * route (which forwards to the configured upstream, default
+ * `http://localhost:11434/v1`) — so a localhost Ollama needs no CORS setup
+ * on EITHER path. A custom AnswerEngine OBJECT can't cross the port and is
+ * rejected in worker mode rather than creating a second page-local backend.
+ * Direct/in-process `pyric/ai` sandboxes still accept custom engines.
+ *
+ * Engine config is per-sandbox (#98.4) and first-call-wins at the worker
+ * host. Each app has its own in-page port wrapper so deleting one app cannot
+ * disconnect a sibling; all wrappers still forward to that one worker broker.
+ * Browser-bundled by `../bundler.ts`; never imported by node-side.
+ */
+import * as ipAi from 'pyric/ai';
+import { aiErrorFromEnvelope } from 'pyric/ai/internal';
+import { getAI as pyricGetAI } from 'pyric/ai';
+import { createTransportAI } from 'pyric/ai/internal';
+import { FirebaseError, getApp, type FirebaseApp } from 'pyric/app';
+import { isSandboxAppDeleted } from 'pyric/app/internal';
+import type { AiEngineConfigWire } from '../worker/protocol.js';
+import { aiGenerateContent, aiCountTokens, aiStreamGenerateContent } from '../worker/client.js';
+import { useWorker } from './worker-runtime.js';
+import { workerClientForApp } from './app-client.js';
+
+// ── Mirror surface — path-independent (the mirror always runs in-page) ────
+export {
+  AIError,
+  AIErrorCode,
+  Backend,
+  BackendType,
+  GoogleAIBackend,
+  VertexAIBackend,
+  AIModel,
+  ChatSession,
+  ChatSessionBase,
+  GenerativeModel,
+  AnyOfSchema,
+  ArraySchema,
+  BooleanSchema,
+  IntegerSchema,
+  NumberSchema,
+  ObjectSchema,
+  Schema,
+  StringSchema,
+  BlockReason,
+  FinishReason,
+  FunctionCallingMode,
+  HarmBlockMethod,
+  HarmBlockThreshold,
+  HarmCategory,
+  HarmProbability,
+  HarmSeverity,
+  ImageConfigAspectRatio,
+  ImageConfigImageSize,
+  Language,
+  Modality,
+  Outcome,
+  POSSIBLE_ROLES,
+  ResponseModality,
+  SchemaType,
+  ThinkingLevel,
+  URLRetrievalStatus,
+  getGenerativeModel,
+} from 'pyric/ai';
+
+type EngineOption = NonNullable<ipAi.AIOptions['engine']>;
+type AnswerTransport = Parameters<typeof createTransportAI>[2];
+
+/** The serve proxy route the browser openai engine defaults to (#98.2). */
+const AI_PROXY_PATH = '/__pyric/ai-proxy';
+
+/** A custom AnswerEngine object (vs a plain, worker-cloneable EngineConfig). */
+function isAnswerEngine(engine: EngineOption): boolean {
+  return typeof (engine as { generateContent?: unknown }).generateContent === 'function';
+}
+
+/**
+ * Derive the JSON-safe wire config that crosses the port from the app's
+ * `AIOptions.engine`. Predicate script matchers are functions — structured
+ * clone rejects them LOUDLY at send time (never silently dropped).
+ */
+function toEngineWire(engine: EngineOption | undefined): AiEngineConfigWire | undefined {
+  if (!engine || isAnswerEngine(engine)) return undefined;
+  const config = engine as Exclude<EngineOption, { generateContent: unknown }> & { kind: string };
+  if (config.kind === 'openai') {
+    const openai = config as Extract<EngineOption, { kind: 'openai' }>;
+    return {
+      kind: 'openai',
+      baseUrl: openai.baseUrl ?? AI_PROXY_PATH,
+      ...(openai.model !== undefined ? { model: openai.model } : {}),
+      ...(openai.modelMap !== undefined ? { modelMap: openai.modelMap } : {}),
+    };
+  }
+  const scripted = config as Extract<EngineOption, { kind: 'scripted' }>;
+  return {
+    kind: 'scripted',
+    ...(scripted.script !== undefined
+      ? { script: scripted.script as unknown as Array<Record<string, unknown>> }
+      : {}),
+  };
+}
+
+/**
+ * The plugin-level engine (`@pyric/cli/vite`'s `ai.engine`) for the IN-PAGE
+ * path, injected as a synchronous global BEFORE any app code runs (the plugin's
+ * transformIndexHtml — a classic inline script). The served `getAI` is
+ * synchronous and can't await init.json, so the worker path's init.json channel
+ * (→ ctx.aiEngine) has this page-side twin. Undefined outside the plugin.
+ */
+function pluginEngineWire(): AiEngineConfigWire | undefined {
+  return (globalThis as { __PYRIC_AI_ENGINE__?: AiEngineConfigWire }).__PYRIC_AI_ENGINE__;
+}
+
+/**
+ * Resolve a plugin wire engine to the mirror's `EngineOption` — an openai
+ * config with no `baseUrl` targets the serve proxy (mirrors resolveEngineConfig
+ * host-side and toEngineWire's inverse).
+ */
+function wireToEngineOption(wire: AiEngineConfigWire): EngineOption {
+  if (wire.kind === 'openai') {
+    return {
+      kind: 'openai',
+      baseUrl: wire.baseUrl ?? AI_PROXY_PATH,
+      ...(wire.model !== undefined ? { model: wire.model } : {}),
+      ...(wire.modelMap !== undefined ? { modelMap: wire.modelMap } : {}),
+    } as EngineOption;
+  }
+  return {
+    kind: 'scripted',
+    ...(wire.script !== undefined
+      ? { script: wire.script as unknown as Extract<EngineOption, { kind: 'scripted' }>['script'] }
+      : {}),
+  } as EngineOption;
+}
+
+/** In-page path: default an openai config's absent baseUrl to the proxy. */
+function withProxyDefault(options?: ipAi.AIOptions): ipAi.AIOptions | undefined {
+  const engine = options?.engine;
+  if (!engine || isAnswerEngine(engine)) return options;
+  const config = engine as { kind?: string; baseUrl?: string };
+  if (config.kind === 'openai' && config.baseUrl === undefined) {
+    return { ...options, engine: { ...config, baseUrl: AI_PROXY_PATH } as EngineOption };
+  }
+  return options;
+}
+
+function aiErrorFromWire(err: unknown, modelResource: string, op: string): unknown {
+  const envelope = (err as { aiEnvelope?: Parameters<typeof aiErrorFromEnvelope>[0] } | null)
+    ?.aiEnvelope;
+  return envelope ? aiErrorFromEnvelope(envelope, modelResource, op) : err;
+}
+
+// ── The port-forwarding AnswerEngine (worker path) ─────────────────────────
+
+function portEngine(db: ReturnType<typeof workerClientForApp>, engineWire: AiEngineConfigWire | undefined): AnswerTransport {
+  const params = (model: string, request: Record<string, unknown>) => ({
+    model,
+    request,
+    ...(engineWire !== undefined ? { engine: engineWire } : {}),
+  });
+  const engine = {
+    async generateContent(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>> {
+      try {
+        return await aiGenerateContent(db, params(model, req));
+      } catch (err) {
+        throw aiErrorFromWire(err, model, 'generateContent');
+      }
+    },
+    streamGenerateContent(req: Record<string, unknown>, model: string): AsyncIterable<Record<string, unknown>> {
+      const inner = aiStreamGenerateContent(db, params(model, req));
+      return (async function* mapped(): AsyncGenerator<Record<string, unknown>> {
+        try {
+          for await (const chunk of inner) yield chunk;
+        } catch (err) {
+          throw aiErrorFromWire(err, model, 'streamGenerateContent');
+        }
+      })();
+    },
+    async countTokens(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>> {
+      try {
+        return await aiCountTokens(db, params(model, req));
+      } catch (err) {
+        throw aiErrorFromWire(err, model, 'countTokens');
+      }
+    },
+  };
+  return engine as unknown as AnswerTransport;
+}
+
+/**
+ * Firebase constructs an AI handle for a deleted app, but that observation
+ * does not authorize resurrecting the app against an in-page sandbox. Keep
+ * the handle constructible while every model operation stays tombstoned.
+ */
+function deletedAppEngine(): AnswerTransport {
+  return {
+    async generateContent(): Promise<never> {
+      throw deletedAppError();
+    },
+    streamGenerateContent(): AsyncIterable<never> {
+      return (async function* tombstoned(): AsyncGenerator<never> {
+        throw deletedAppError();
+      })();
+    },
+    async countTokens(): Promise<never> {
+      throw deletedAppError();
+    },
+  } as AnswerTransport;
+}
+
+function deletedAppError(): FirebaseError {
+  return new FirebaseError(
+    'app/app-deleted',
+    'Firebase App has already been deleted.',
+  );
+}
+
+// ── getAI — worker-forwarded answering or whole-mirror in-page ─────────────
+function mirrorGetAI(
+  app: unknown,
+  options?: ipAi.AIOptions,
+): ipAi.AI {
+  const resolved = (app ?? getApp()) as FirebaseApp;
+  const ai = pyricGetAI(resolved, options);
+  const target = (ai as unknown as {
+    [ipAi.TARGET_SYMBOL]?: { assertAlive?: () => void };
+  })[ipAi.TARGET_SYMBOL];
+  if (target) {
+    // Served entries are separately bundled, so the in-page AI mirror cannot
+    // rely on sharing pyric/app's private adapter singleton. Stamp the target
+    // with the served registry's per-app deletion guard instead. The target is
+    // per app handle even though its broker is shared by the sandbox.
+    target.assertAlive = () => {
+      if (isSandboxAppDeleted(resolved)) throw deletedAppError();
+    };
+  }
+  return ai;
+}
+
+export const getAI = (
+  useWorker
+    ? (app?: unknown, options?: ipAi.AIOptions) => {
+        const resolved = (app ?? getApp()) as FirebaseApp;
+        const engine = options?.engine;
+        const assertAlive = () => {
+          if (isSandboxAppDeleted(resolved)) throw deletedAppError();
+        };
+        if (isSandboxAppDeleted(resolved)) {
+          return createTransportAI(
+            resolved,
+            options,
+            deletedAppEngine(),
+            assertAlive,
+          );
+        }
+        if (engine && isAnswerEngine(engine)) {
+          throw new ipAi.AIError(
+            ipAi.AIErrorCode.UNSUPPORTED,
+            'Custom AnswerEngine objects cannot run in SharedWorker mode. ' +
+              "Use a structured { kind: 'scripted' } or { kind: 'openai' } engine config.",
+          );
+        }
+        return createTransportAI(
+          resolved,
+          options,
+          portEngine(workerClientForApp(resolved), toEngineWire(engine)),
+          assertAlive,
+        );
+      }
+    : (app?: unknown, options?: ipAi.AIOptions) => {
+        // Plugin-level engine wins over an app-code `getAI` engine (mirrors the
+        // worker host's ctx.aiEngine precedence). Absent ⇒ app options as-is.
+        const pluginWire = pluginEngineWire();
+        return pluginWire
+          ? mirrorGetAI(app, { ...options, engine: wireToEngineOption(pluginWire) })
+          : mirrorGetAI(app, withProxyDefault(options));
+      }
+) as typeof pyricGetAI;

package/src/serve/entries/app-backend.ts

@@ -0,0 +1,4 @@
+/** Realm-local placeholder attached to app handles; served services use the worker transport. */
+import { initializeSandbox } from 'pyric/sandbox';
+
+export const sandbox = initializeSandbox();

package/src/serve/entries/app-client.ts

@@ -0,0 +1,26 @@
+/** Per-app SharedWorker ports: distinct Firebase service containers, one worker backend. */
+import type { FirebaseApp } from 'pyric/app';
+import { registerAppCleanup } from 'pyric/app/internal';
+import type { ClientDb } from '../worker/client.js';
+import type { InboundMessage } from '../worker/protocol.js';
+import { disconnectClient } from '../worker/client/disconnect.js';
+import { openWorkerDb } from './worker-runtime.js';
+
+const clients = new WeakMap<FirebaseApp, ClientDb>();
+
+export function workerClientForApp(app: FirebaseApp): ClientDb {
+  const existing = clients.get(app);
+  if (existing) return existing;
+  let client: ClientDb | undefined;
+  registerAppCleanup(app, async () => {
+    clients.delete(app);
+    if (client) await disconnectClient(client);
+  });
+  client = openWorkerDb(app.name);
+  client.port.postMessage({
+    t: 'appConfig',
+    options: app.options as Record<string, unknown>,
+  } satisfies InboundMessage);
+  clients.set(app, client);
+  return client;
+}

package/src/serve/entries/app-session-store.ts

@@ -0,0 +1,47 @@
+/** App-owned browser auth-session stores for the served Firebase adapters. */
+import type { FirebaseApp } from 'pyric/app';
+import { registerAppCleanup } from 'pyric/app/internal';
+import { SessionStore, type SessionStores } from './session-store.js';
+
+export interface AppSessionStores {
+  forApp(app: FirebaseApp): SessionStore;
+}
+
+/**
+ * Build an app-identity-keyed store registry. The durable key inside each
+ * SessionStore remains app-name-keyed, so deleting/recreating an app can
+ * restore the same session while its in-memory mode/callback state is fresh.
+ */
+export function createAppSessionStores(stores: SessionStores): AppSessionStores {
+  const byApp = new WeakMap<FirebaseApp, SessionStore>();
+  return {
+    forApp(app) {
+      const existing = byApp.get(app);
+      if (existing) return existing;
+      const store = new SessionStore(stores, app.name);
+      byApp.set(app, store);
+      registerAppCleanup(app, () => { byApp.delete(app); });
+      return store;
+    },
+  };
+}
+
+function memoryStorage(): SessionStores['local'] {
+  const values = new Map<string, string>();
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => { values.set(key, value); },
+    removeItem: (key) => { values.delete(key); },
+  };
+}
+
+const browserStores: SessionStores =
+  typeof localStorage !== 'undefined' && typeof sessionStorage !== 'undefined'
+    ? { local: localStorage, session: sessionStorage }
+    : { local: memoryStorage(), session: memoryStorage() };
+
+const servedStores = createAppSessionStores(browserStores);
+
+export function sessionStoreForApp(app: FirebaseApp): SessionStore {
+  return servedStores.forApp(app);
+}

package/src/serve/entries/app.ts

@@ -0,0 +1,11 @@
+/** Served `firebase/app`: the exact Pyric client registry over the page runtime. */
+import { bindAppRegistrySandbox } from 'pyric/app/internal';
+import { sandbox } from './app-backend.js';
+
+// Keep this entry free of dynamic imports: ServiceWorkerGlobalScope supports
+// static module imports but rejects dynamic import(). The attached sandbox is
+// only the app handle's realm-local placeholder; served service calls route to
+// the SharedWorker (directly in Window, via BroadcastChannel in a real SW).
+bindAppRegistrySandbox(sandbox);
+
+export * from 'pyric/app';