@ericminassian/platform 0.0.0-stage → 0.1.0

package/src/server.ts

@@ -0,0 +1,274 @@
+/**
+ * Web Function entry wrapper. `plat build` generates:
+ *
+ *   import handler from '<app>/src/server.ts';
+ *   import { startServer } from '@ericminassian/platform/server';
+ *   startServer(handler);
+ *
+ * and bundles it to `index.mjs`. startServer listens on
+ * `AWS_LAMBDA_HTTP_ENDPOINT` (Web Function contract; `plat dev` sets it too),
+ * adds `/__platform/*` routes (health, auth), auto-instruments every request
+ * (telemetry `req`/`err`/`span` lines, traces) and maps `x-platform-host` to
+ * the public URL the app sees.
+ *
+ * CONTRACT: used by the CLI build. Keep stable.
+ */
+import {
+  fingerprint,
+  HEALTH_PATH,
+  HOST_HEADER,
+  PLATFORM_PATH_PREFIX,
+  TRACE_HEADER,
+} from '@ericminassian/platform-core';
+import { authGate, handleAuthRoute } from './auth/index.ts';
+import { getBindings, tryBindings } from './bindings.ts';
+import { currentContext, newContext, parseTraceparent, runWithContext } from './context.ts';
+import { createNodeServer, parseEndpoint } from './http.ts';
+import { emit, emitError, installConsoleCapture, installFetchInstrumentation, toError } from './telemetry.ts';
+
+/** Anything with a web-standard fetch: a Hono app, `{ fetch }`, or a bare function. */
+export type FetchHandlerLike =
+  | { fetch(request: Request, ...rest: unknown[]): Response | Promise<Response> }
+  | ((request: Request) => Response | Promise<Response>);
+
+interface RouteLike {
+  path: string;
+  method: string;
+}
+
+let cold = true;
+
+/** The wrapped fetch (platform routes + instrumentation), without listening. Useful in tests. */
+export function createPlatformFetch(handler: FetchHandlerLike): (request: Request) => Promise<Response> {
+  const appFetch =
+    typeof handler === 'function'
+      ? handler
+      : (req: Request) => (handler as { fetch: (r: Request) => Response | Promise<Response> }).fetch(req);
+  const matchRoute = routeMatcher(handler);
+  instrumentHonoErrors(handler);
+
+  return async (incoming: Request): Promise<Response> => {
+    const t0 = performance.now();
+    const trace = incoming.headers.get(TRACE_HEADER) ?? parseTraceparent(incoming.headers.get('traceparent'));
+    const ctx = newContext(trace);
+    const wasCold = cold;
+    cold = false;
+
+    return runWithContext(ctx, async () => {
+      const request = publicRequest(incoming);
+      const url = new URL(request.url);
+      let response: Response;
+      let errorEmitted = false;
+      try {
+        if (url.pathname.startsWith(PLATFORM_PATH_PREFIX)) {
+          response = await platformRoute(request);
+        } else {
+          response = (await authGate(request)) ?? (await appFetch(request));
+        }
+      } catch (e) {
+        if (e instanceof Response) response = e;
+        else {
+          emitError(e, 'http', { route: ctx.route ?? matchRoute(request.method, url.pathname) });
+          errorEmitted = true;
+          response = Response.json(
+            { error: { code: 'internal', message: 'Internal Server Error', trace: ctx.trace } },
+            { status: 500 },
+          );
+        }
+      }
+
+      response = finalize(response, ctx.trace, ctx.cookies);
+      const route = ctx.route ?? matchRoute(request.method, url.pathname);
+      if (response.status >= 500 && !errorEmitted) {
+        if (ctx.error !== undefined) emitError(ctx.error, 'http', { route });
+        else {
+          const e = new Error(`HTTP ${response.status} ${request.method} ${route}`);
+          e.name = 'HttpError';
+          emitError(e, 'http', { route });
+        }
+      }
+      emit('req', {
+        method: request.method,
+        route,
+        path: url.pathname,
+        status: response.status,
+        dur: Math.round((performance.now() - t0) * 10) / 10,
+        ...(lengthOf(response) !== undefined ? { bytes: lengthOf(response)! } : {}),
+        ...(incoming.headers.get('cloudfront-viewer-country')
+          ? { country: incoming.headers.get('cloudfront-viewer-country')! }
+          : {}),
+        ...(ctx.user ? { user: fingerprint([ctx.user.id]) } : {}),
+        ...(wasCold ? { cold: true } : {}),
+        span: ctx.span,
+      });
+      return response;
+    });
+  };
+}
+
+/** Rewrite the request onto the app's public origin (scheme/port from bindings, host from the router). */
+function publicRequest(incoming: Request): Request {
+  const b = tryBindings();
+  if (!b) return incoming;
+  const inUrl = new URL(incoming.url);
+  const origin = new URL(b.url);
+  const forwarded = incoming.headers.get(HOST_HEADER);
+  if (forwarded && /^[a-z0-9.-]+$/i.test(forwarded.replace(/:\d+$/, '')))
+    origin.hostname = forwarded.replace(/:\d+$/, '');
+  const target = `${origin.origin}${inUrl.pathname}${inUrl.search}`;
+  if (target === incoming.url) return incoming;
+  const hasBody = incoming.method !== 'GET' && incoming.method !== 'HEAD';
+  return new Request(target, {
+    method: incoming.method,
+    headers: incoming.headers,
+    signal: incoming.signal,
+    redirect: incoming.redirect,
+    ...(hasBody ? { body: incoming.body, duplex: 'half' } : {}),
+  } as RequestInit);
+}
+
+async function platformRoute(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  if (url.pathname === HEALTH_PATH) {
+    const b = getBindings();
+    return Response.json(
+      { ok: true, app: b.app, stage: b.stage, revision: b.revision },
+      { headers: { 'cache-control': 'no-store' } },
+    );
+  }
+  const authResponse = await handleAuthRoute(request);
+  if (authResponse) return authResponse;
+  return Response.json({ error: { code: 'not_found', message: 'Not found' } }, { status: 404 });
+}
+
+function finalize(response: Response, trace: string, cookies: string[]): Response {
+  const headers = new Headers(response.headers);
+  headers.set(TRACE_HEADER, trace);
+  if (!headers.has('cache-control')) headers.set('cache-control', 'private, no-store');
+  for (const c of cookies) headers.append('set-cookie', c);
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+function lengthOf(r: Response): number | undefined {
+  const v = r.headers.get('content-length');
+  return v ? Number(v) : undefined;
+}
+
+// ---------------------------------------------------------------- framework integration
+
+type ErrorHandler = (err: unknown, c: unknown) => Response | Promise<Response>;
+
+/**
+ * Hono catches handler errors itself (default: plain-text 500). Hook its
+ * onError so errors reach telemetry with their real stack, and so apps using
+ * the default handler get the platform's JSON 500 with a trace id. A custom
+ * onError the app installed keeps control of the response.
+ */
+function instrumentHonoErrors(handler: FetchHandlerLike): void {
+  const h = handler as {
+    onError?: (fn: ErrorHandler) => unknown;
+    errorHandler?: ErrorHandler;
+    __platform?: boolean;
+  };
+  if (typeof h.onError !== 'function' || h.__platform) return;
+  const prev = h.errorHandler;
+  const prevIsDefault =
+    typeof prev !== 'function' ||
+    prev.name === 'errorHandler' ||
+    String(prev).includes('Internal Server Error');
+  h.onError((err, c) => {
+    if (err && typeof (err as { getResponse?: unknown }).getResponse === 'function') {
+      return prev ? prev(err, c) : (err as { getResponse(): Response }).getResponse();
+    }
+    const ctx = currentContext();
+    if (ctx) ctx.error = err;
+    if (prev && !prevIsDefault) return prev(err, c);
+    throw err;
+  });
+  h.__platform = true;
+}
+
+// ---------------------------------------------------------------- route patterns
+
+const ID_SEGMENT =
+  /^(\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{12,}|[0-9a-hjkmnp-tv-z]{26}|(?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{16,})$/i;
+
+/** `/api/todos/42` → `/api/todos/:id` (used when the framework's route pattern is unknown). */
+export function normalizePath(path: string): string {
+  return path
+    .split('/')
+    .map((seg) => (seg && ID_SEGMENT.test(seg) ? ':id' : seg))
+    .join('/');
+}
+
+/** Hono apps expose `routes`; match against them to recover the route pattern. */
+function routeMatcher(handler: FetchHandlerLike): (method: string, path: string) => string {
+  const routes = (handler as { routes?: RouteLike[] }).routes;
+  if (!Array.isArray(routes)) return (_m, path) => normalizePath(path);
+  let compiled: Array<{ method: string; path: string; re: RegExp }> | undefined;
+  return (method, path) => {
+    compiled ??= routes
+      .filter((r) => r.method !== 'ALL' && typeof r.path === 'string' && !/^\/?\*?$/.test(r.path))
+      .map((r) => ({ method: r.method, path: r.path, re: patternToRegex(r.path) }));
+    const hit = compiled.find(
+      (r) => (r.method === method || (method === 'HEAD' && r.method === 'GET')) && r.re.test(path),
+    );
+    return hit ? hit.path : normalizePath(path);
+  };
+}
+
+function patternToRegex(pattern: string): RegExp {
+  const body = pattern
+    .split('/')
+    .map((seg) => {
+      if (seg === '*') return '.*';
+      if (seg.startsWith(':')) {
+        const custom = /\{(.+)\}/.exec(seg);
+        const optional = seg.endsWith('?');
+        const part = custom ? `(?:${custom[1]})` : '[^/]+';
+        return optional ? `?(?:${part})?` : part;
+      }
+      return seg.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\\\*/g, '.*');
+    })
+    .join('/');
+  return new RegExp(`^${body}/?$`);
+}
+
+// ---------------------------------------------------------------- server
+
+/** Start the HTTP server. Resolves once listening. */
+export async function startServer(handler: FetchHandlerLike): Promise<{ close(): Promise<void> }> {
+  installConsoleCapture();
+  installFetchInstrumentation();
+  const endpoint =
+    process.env.AWS_LAMBDA_HTTP_ENDPOINT ??
+    (process.env.PORT ? `127.0.0.1:${process.env.PORT}` : '127.0.0.1:8080');
+  const { host, port } = parseEndpoint(endpoint);
+  const server = createNodeServer(createPlatformFetch(handler));
+  server.keepAliveTimeout = 65_000;
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+  emit('env', { event: 'start', runtime: 'web', initMs: Math.round(performance.now()) });
+
+  const close = () =>
+    new Promise<void>((resolve) => {
+      server.close(() => resolve());
+      server.closeIdleConnections?.();
+    });
+
+  process.once('SIGTERM', () => {
+    emit('env', { event: 'stop', runtime: 'web' });
+    // Web Functions allow ~1 s for cleanup after SIGTERM.
+    const force = setTimeout(() => process.exit(0), 900);
+    force.unref();
+    close().then(() => process.exit(0));
+  });
+  process.on('unhandledRejection', (reason) => emitError(toError(reason), 'unhandled'));
+  return { close };
+}

package/src/storage.ts

@@ -0,0 +1,143 @@
+import { getBindings } from './bindings.ts';
+import { client } from './clients.ts';
+import { span } from './telemetry.ts';
+
+export interface StoredObject {
+  key: string;
+  size: number;
+  lastModified?: Date;
+}
+
+export interface Store {
+  put(key: string, body: Uint8Array | string, opts?: { contentType?: string }): Promise<void>;
+  get(key: string): Promise<Uint8Array | undefined>;
+  getText(key: string): Promise<string | undefined>;
+  delete(key: string): Promise<void>;
+  list(
+    prefix?: string,
+    opts?: { cursor?: string; limit?: number },
+  ): Promise<{ objects: StoredObject[]; cursor?: string }>;
+  /** Browser-direct upload URL (HTTP PUT). */
+  uploadUrl(key: string, opts?: { contentType?: string; expiresInSeconds?: number }): Promise<string>;
+  downloadUrl(key: string, opts?: { expiresInSeconds?: number; filename?: string }): Promise<string>;
+}
+
+function location(name: string): { bucket: string; prefix: string } {
+  const s = getBindings().storage;
+  if (!s?.stores.includes(name)) {
+    const declared = s?.stores ?? [];
+    throw new Error(
+      `Unknown store "${name}". Declared storage: ${declared.length ? declared.join(', ') : '(none)'} — add it under "storage" in platform.json.`,
+    );
+  }
+  return { bucket: s.bucket, prefix: `${s.prefix}${name}/` };
+}
+
+/** The S3 client and command module, loaded on first use. */
+async function s3() {
+  const [c, m] = await Promise.all([client('s3'), import('@aws-sdk/client-s3')]);
+  return { c, m };
+}
+
+async function sign(command: unknown, expiresIn: number): Promise<string> {
+  const [{ getSignedUrl }, c] = await Promise.all([import('@aws-sdk/s3-request-presigner'), client('s3')]);
+  // biome-ignore lint/suspicious/noExplicitAny: presigner and client generics differ across smithy versions
+  return getSignedUrl(c as any, command as any, { expiresIn });
+}
+
+function objectKey(prefix: string, key: string): string {
+  const k = key.replace(/^\/+/, '');
+  if (!k || k.split('/').some((p) => p === '..')) throw new Error(`Invalid storage key "${key}"`);
+  return prefix + k;
+}
+
+function isNotFound(e: unknown): boolean {
+  const name = (e as { name?: string })?.name;
+  const status = (e as { $metadata?: { httpStatusCode?: number } })?.$metadata?.httpStatusCode;
+  return name === 'NoSuchKey' || name === 'NotFound' || status === 404;
+}
+
+export function storage(name: string): Store {
+  const get = (key: string) =>
+    span('storage.get', name, async () => {
+      const { bucket, prefix } = location(name);
+      const { c, m } = await s3();
+      try {
+        const out = await c.send(new m.GetObjectCommand({ Bucket: bucket, Key: objectKey(prefix, key) }));
+        return out.Body ? await out.Body.transformToByteArray() : new Uint8Array();
+      } catch (e) {
+        if (isNotFound(e)) return undefined;
+        throw e;
+      }
+    });
+
+  return {
+    put: (key, body, opts) =>
+      span('storage.put', name, async () => {
+        const { bucket, prefix } = location(name);
+        const { c, m } = await s3();
+        await c.send(
+          new m.PutObjectCommand({
+            Bucket: bucket,
+            Key: objectKey(prefix, key),
+            Body: typeof body === 'string' ? Buffer.from(body) : body,
+            ...(opts?.contentType ? { ContentType: opts.contentType } : {}),
+          }),
+        );
+      }),
+    get,
+    getText: async (key) => {
+      const bytes = await get(key);
+      return bytes ? new TextDecoder().decode(bytes) : undefined;
+    },
+    delete: (key) =>
+      span('storage.delete', name, async () => {
+        const { bucket, prefix } = location(name);
+        const { c, m } = await s3();
+        await c.send(new m.DeleteObjectCommand({ Bucket: bucket, Key: objectKey(prefix, key) }));
+      }),
+    list: (sub, opts) =>
+      span('storage.list', name, async () => {
+        const { bucket, prefix } = location(name);
+        const { c, m } = await s3();
+        const out = await c.send(
+          new m.ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: prefix + (sub ?? '').replace(/^\/+/, ''),
+            ...(opts?.cursor ? { ContinuationToken: opts.cursor } : {}),
+            ...(opts?.limit ? { MaxKeys: opts.limit } : {}),
+          }),
+        );
+        const objects: StoredObject[] = (out.Contents ?? []).map((o) => ({
+          key: (o.Key ?? '').slice(prefix.length),
+          size: o.Size ?? 0,
+          ...(o.LastModified ? { lastModified: o.LastModified } : {}),
+        }));
+        return out.NextContinuationToken ? { objects, cursor: out.NextContinuationToken } : { objects };
+      }),
+    uploadUrl: (key, opts) =>
+      span('storage.sign', name, async () => {
+        const { bucket, prefix } = location(name);
+        const { m } = await s3();
+        const cmd = new m.PutObjectCommand({
+          Bucket: bucket,
+          Key: objectKey(prefix, key),
+          ...(opts?.contentType ? { ContentType: opts.contentType } : {}),
+        });
+        return sign(cmd, opts?.expiresInSeconds ?? 900);
+      }),
+    downloadUrl: (key, opts) =>
+      span('storage.sign', name, async () => {
+        const { bucket, prefix } = location(name);
+        const { m } = await s3();
+        const cmd = new m.GetObjectCommand({
+          Bucket: bucket,
+          Key: objectKey(prefix, key),
+          ...(opts?.filename
+            ? { ResponseContentDisposition: `attachment; filename="${opts.filename.replace(/"/g, '')}"` }
+            : {}),
+        });
+        return sign(cmd, opts?.expiresInSeconds ?? 900);
+      }),
+  };
+}

package/src/telemetry.ts

@@ -0,0 +1,260 @@
+import { format } from 'node:util';
+import {
+  type ErrorEvent,
+  errorFingerprint,
+  newSpanId,
+  type TelemetryEvent,
+  type TelemetryKind,
+} from '@ericminassian/platform-core';
+import { tryBindings } from './bindings.ts';
+import { currentContext } from './context.ts';
+
+/**
+ * Telemetry writer. Every line is one core `TelemetryEvent` as JSON on stdout
+ * (Lambda ships stdout to CloudWatch Logs; the account-level subscription
+ * filter forwards `_p: 1` lines to the telemetry processor). Under `plat dev`
+ * (`PLATFORM_LOG_PRETTY=1`) lines are printed compactly for humans instead.
+ * Nothing here may ever throw into app code.
+ */
+
+type Sink = (event: TelemetryEvent) => void;
+
+// Captured before console is patched so telemetry never recurses through it.
+const rawWrite = process.stdout.write.bind(process.stdout);
+let sink: Sink | null = null;
+
+/** Replace the output (tests). `null` restores stdout. */
+export function setTelemetrySink(s: Sink | null): void {
+  sink = s;
+}
+
+type Fields<K extends TelemetryKind> = Omit<
+  Extract<TelemetryEvent, { t: K }>,
+  '_p' | 'ts' | 'app' | 'stage' | 'rev' | 't'
+> & {
+  ts?: number;
+};
+
+export function emit<K extends TelemetryKind>(t: K, fields: Fields<K>): void {
+  try {
+    const b = tryBindings();
+    const ctx = currentContext();
+    const event = {
+      _p: 1,
+      t,
+      ts: Date.now(),
+      app: b?.app ?? process.env.PLATFORM_APP ?? 'unknown',
+      stage: b?.stage ?? process.env.PLATFORM_STAGE ?? 'unknown',
+      rev: b?.revision ?? 'unknown',
+      ...(ctx ? { trace: ctx.trace } : {}),
+      ...fields,
+    } as unknown as TelemetryEvent;
+    if (sink) sink(event);
+    else rawWrite(`${process.env.PLATFORM_LOG_PRETTY === '1' ? pretty(event) : JSON.stringify(event)}\n`);
+  } catch {
+    // never throw from telemetry
+  }
+}
+
+/** Time `fn` as a span (`db.get`, `queue.send`, ...) under the current trace. */
+export async function span<T>(op: string, name: string | undefined, fn: () => Promise<T>): Promise<T> {
+  const t0 = performance.now();
+  const ctx = currentContext();
+  const id = newSpanId();
+  let status: 'ok' | 'error' = 'ok';
+  try {
+    return await fn();
+  } catch (e) {
+    status = 'error';
+    throw e;
+  } finally {
+    // Spans only matter as part of a trace; skip them outside a request/job.
+    if (ctx)
+      emit('span', {
+        op,
+        ...(name ? { name } : {}),
+        dur: round(performance.now() - t0),
+        status,
+        span: id,
+        parent: ctx.span,
+        start: round(t0 - ctx.startedAt),
+      });
+  }
+}
+
+/** Emit an `err` event for a thrown value. */
+export function emitError(
+  err: unknown,
+  source: ErrorEvent['source'],
+  extra: { route?: string; job?: string } = {},
+): void {
+  const e = toError(err);
+  emit('err', {
+    source,
+    name: e.name,
+    message: e.message,
+    ...(e.stack ? { stack: e.stack } : {}),
+    ...extra,
+    fingerprint: errorFingerprint(e.name, e.message, e.stack),
+  });
+}
+
+export function toError(err: unknown): Error {
+  if (err instanceof Error) return err;
+  return new Error(typeof err === 'string' ? err : safeStringify(err));
+}
+
+// ---------------------------------------------------------------- metrics & log
+
+export const metrics = {
+  count(name: string, n = 1): void {
+    emit('metric', { name, value: n, unit: 'count' });
+  },
+  value(name: string, value: number, unit?: string): void {
+    emit('metric', { name, value, ...(unit ? { unit } : {}) });
+  },
+};
+
+type Level = 'debug' | 'info' | 'warn' | 'error';
+
+function logAt(level: Level, msg: string, fields?: unknown): void {
+  if (
+    level === 'error' &&
+    (fields instanceof Error || (fields && typeof fields === 'object' && 'stack' in fields))
+  ) {
+    const e = toError(fields);
+    emit('log', { level, msg, error: { name: e.name, message: e.message, stack: e.stack } });
+    emitError(e, 'log', jobOrRoute());
+    return;
+  }
+  const extra =
+    fields && typeof fields === 'object'
+      ? (fields as Record<string, unknown>)
+      : fields === undefined
+        ? {}
+        : { value: fields };
+  emit('log', { ...extra, level, msg });
+}
+
+export const log = {
+  debug: (msg: string, fields?: Record<string, unknown>) => logAt('debug', msg, fields),
+  info: (msg: string, fields?: Record<string, unknown>) => logAt('info', msg, fields),
+  warn: (msg: string, fields?: Record<string, unknown>) => logAt('warn', msg, fields),
+  error: (msg: string, fields?: Record<string, unknown> | unknown) => logAt('error', msg, fields),
+};
+
+function jobOrRoute(): { route?: string; job?: string } {
+  const ctx = currentContext();
+  if (!ctx) return {};
+  return { ...(ctx.route ? { route: ctx.route } : {}), ...(ctx.job ? { job: ctx.job } : {}) };
+}
+
+// ---------------------------------------------------------------- console capture
+
+let consolePatched = false;
+const originalConsole: Partial<Record<keyof Console, unknown>> = {};
+
+/** Route console.* through telemetry so app logs carry the trace id. */
+export function installConsoleCapture(): void {
+  if (consolePatched) return;
+  consolePatched = true;
+  const map: Array<[keyof Console, Level]> = [
+    ['log', 'info'],
+    ['info', 'info'],
+    ['debug', 'debug'],
+    ['warn', 'warn'],
+    ['error', 'error'],
+  ];
+  for (const [method, level] of map) {
+    originalConsole[method] = console[method];
+    (console as unknown as Record<string, (...a: unknown[]) => void>)[method] = (...args: unknown[]) => {
+      emit('log', { level, msg: format(...args) });
+    };
+  }
+}
+
+// ---------------------------------------------------------------- fetch spans
+
+let fetchPatched = false;
+let originalFetch: typeof fetch | undefined;
+
+/** Record outgoing `fetch` calls as spans (method + host only; no URLs with secrets). */
+export function installFetchInstrumentation(): void {
+  if (fetchPatched || typeof globalThis.fetch !== 'function') return;
+  fetchPatched = true;
+  originalFetch = globalThis.fetch;
+  const original = globalThis.fetch.bind(globalThis);
+  globalThis.fetch = (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    if (!currentContext()) return original(input, init);
+    let name = 'fetch';
+    try {
+      const url = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
+      const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
+      name = `${method.toUpperCase()} ${url.host}`;
+    } catch {}
+    return span('fetch', name, () => original(input, init));
+  }) as typeof fetch;
+}
+
+/** Undo console/fetch patching (tests). */
+export function uninstallInstrumentation(): void {
+  if (consolePatched) {
+    for (const [k, v] of Object.entries(originalConsole))
+      (console as unknown as Record<string, unknown>)[k] = v;
+    consolePatched = false;
+  }
+  if (fetchPatched && originalFetch) {
+    globalThis.fetch = originalFetch;
+    fetchPatched = false;
+  }
+}
+
+// ---------------------------------------------------------------- pretty printing
+
+const COLORS = {
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  reset: '\x1b[0m',
+};
+
+function pretty(e: TelemetryEvent): string {
+  const time = new Date(e.ts).toISOString().slice(11, 23);
+  const c = (color: keyof typeof COLORS, s: string) => `${COLORS[color]}${s}${COLORS.reset}`;
+  switch (e.t) {
+    case 'req': {
+      const color = e.status >= 500 ? 'red' : e.status >= 400 ? 'yellow' : 'green';
+      return `${c('dim', time)} ${c(color, String(e.status))} ${e.method} ${e.path} ${c('dim', `${e.dur}ms${e.cold ? ' cold' : ''}`)}`;
+    }
+    case 'err':
+      return `${c('dim', time)} ${c('red', `✖ ${e.name}: ${e.message}`)}${e.stack ? `\n${c('dim', e.stack.split('\n').slice(1, 6).join('\n'))}` : ''}`;
+    case 'job':
+      return `${c('dim', time)} ${c(e.status === 'ok' ? 'cyan' : 'red', `${e.kind}:${e.name}`)} ${e.status} ${c('dim', `${e.dur}ms`)}`;
+    case 'span':
+      return `${c('dim', `${time}   ↳ ${e.op}${e.name ? ` ${e.name}` : ''} ${e.dur}ms${e.status === 'error' ? ' error' : ''}`)}`;
+    case 'log': {
+      const { _p, t, ts, app, stage, rev, trace, span: _s, parent, level, msg, ...rest } = e;
+      const extra = Object.keys(rest).length ? ` ${c('dim', safeStringify(rest))}` : '';
+      const color = level === 'error' ? 'red' : level === 'warn' ? 'yellow' : 'reset';
+      return `${c('dim', time)} ${c(color, msg)}${extra}`;
+    }
+    case 'metric':
+      return `${c('dim', `${time} metric ${e.name}=${e.value}${e.unit ? ` ${e.unit}` : ''}`)}`;
+    case 'env':
+      return `${c('dim', `${time} ${e.runtime} ${e.event}${e.initMs !== undefined ? ` (${e.initMs}ms)` : ''}`)}`;
+  }
+}
+
+function round(ms: number): number {
+  return Math.round(ms * 10) / 10;
+}
+
+function safeStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}