@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/server/ui-telemetry.ts

@@ -0,0 +1,198 @@
+import {
+  type JsonObject,
+  type JsonValue,
+  isJsonObject,
+  jsonString,
+} from "@dev.fast/review-protocol";
+import { mergeErrorTelemetryProperties } from "@review/error-telemetry";
+import type {
+  ReviewTabTelemetryEvent,
+  ReviewTelemetryContext,
+} from "@review/telemetry";
+import {
+  REVIEW_APP_SESSION_ID_HEADER,
+  sanitizeUiTelemetryEvent,
+} from "@review/ui-telemetry-events";
+import { z } from "zod";
+
+import { ClientErrorBudget } from "./client-error-budget";
+
+const contextSchema = z.object({
+  reviewUuid: z.string().min(1).max(128).optional(),
+  presentationSessionId: z.string().min(1).max(128).optional(),
+});
+
+type SanitizedUiTelemetryEvent = NonNullable<
+  ReturnType<typeof sanitizeUiTelemetryEvent>
+>;
+
+const clientErrorBudget = new ClientErrorBudget();
+
+/**
+ * Applies the per-session, per-digest error budget to a sanitized event, and
+ * returns what to send in its place: the event itself, one
+ * review_error_burst that says how many were withheld, or nothing. Every path
+ * that reports review_client_error goes through here. Other events, and errors
+ * without a session or a digest, pass unchanged.
+ */
+export function admitUiTelemetryEvent(
+  event: SanitizedUiTelemetryEvent,
+): SanitizedUiTelemetryEvent | undefined {
+  if (event.event !== "review_client_error") return event;
+  const sessionId = jsonString(event.properties.app_session_id);
+  const messageHash = jsonString(event.properties.message_hash);
+
+  if (sessionId === undefined || messageHash === undefined) return event;
+  const admission = clientErrorBudget.admit(sessionId, messageHash);
+
+  if (admission.verdict === "send") return event;
+
+  if (admission.verdict === "drop") return undefined;
+
+  return (
+    sanitizeUiTelemetryEvent({
+      name: "error_burst",
+      properties: {
+        message_hash: messageHash,
+        suppressed: admission.suppressed,
+        app_session_id: sessionId,
+      },
+    }) ?? undefined
+  );
+}
+
+const MAX_CLIENT_ERROR_SESSIONS = 100;
+
+const MAX_CLIENT_ERRORS_PER_SESSION = 20;
+
+const clientErrorsBySession = new Map<string, string[]>();
+
+export function recordClientError(
+  event: ReturnType<typeof sanitizeUiTelemetryEvent>,
+): void {
+  if (event?.event !== "review_client_error") return;
+  const sessionId = jsonString(event.properties.app_session_id);
+  const errorName = jsonString(event.properties.error_name);
+
+  if (sessionId === undefined || errorName === undefined) return;
+  const names = clientErrorsBySession.get(sessionId) ?? [];
+  names.push(errorName);
+
+  if (names.length > MAX_CLIENT_ERRORS_PER_SESSION) names.shift();
+  clientErrorsBySession.delete(sessionId);
+  clientErrorsBySession.set(sessionId, names);
+
+  while (clientErrorsBySession.size > MAX_CLIENT_ERROR_SESSIONS) {
+    const oldest = clientErrorsBySession.keys().next().value;
+
+    if (oldest === undefined) break;
+    clientErrorsBySession.delete(oldest);
+  }
+}
+
+export function clientErrorsForSession(sessionId: string): string[] {
+  const names = clientErrorsBySession.get(sessionId) ?? [];
+
+  if (names.length > 0) {
+    clientErrorsBySession.delete(sessionId);
+    clientErrorsBySession.set(sessionId, names);
+  }
+
+  return [...names];
+}
+
+export interface ReviewTelemetryCapture {
+  captureTabViewed(event: ReviewTabTelemetryEvent): Promise<void>;
+  captureUiEvent?(
+    event: string,
+    properties: Record<string, string | number | boolean>,
+    context?: ReviewTelemetryContext,
+    occurredAt?: number,
+  ): Promise<void>;
+}
+
+/** How far back a client may date its own event. */
+const MAX_CLIENT_EVENT_AGE_MS = 5 * 60 * 1_000;
+
+/**
+ * The client's occurrence time, clamped to the recent past: parallel requests
+ * can arrive out of order, but a client can never date an event ahead of now
+ * or far behind it.
+ */
+export function clientOccurredAt(
+  raw: JsonValue | undefined,
+  now: number,
+): number {
+  const parsed = z.number().safeParse(raw);
+
+  if (!parsed.success) return now;
+
+  return Math.min(now, Math.max(now - MAX_CLIENT_EVENT_AGE_MS, parsed.data));
+}
+
+export async function captureSanitizedUiTelemetry(
+  telemetry: ReviewTelemetryCapture,
+  request: Request,
+  name: JsonValue,
+  properties: JsonValue,
+  onSanitized?: (
+    event: SanitizedUiTelemetryEvent,
+    context: ReviewTelemetryContext | undefined,
+  ) => void,
+  /**
+   * The raw error envelope, which arrives beside `properties` and never inside
+   * it. This function is where the raw form dies: what continues is the class
+   * name, the message with paths and secrets replaced by markers, a digest of
+   * the original message, and bundle-relative frames. The allowlist re-checks
+   * all of it. Never merge this into `properties`.
+   */
+  rawError?: JsonValue,
+  /**
+   * Raw review and presentation ids, beside `properties` like `error`. They
+   * never reach PostHog: the telemetry API replaces them with keyed HMACs.
+   */
+  rawContext?: JsonValue,
+  /** The client's `occurredAt`, epoch ms; see {@link clientOccurredAt}. */
+  rawOccurredAt?: JsonValue,
+): Promise<void> {
+  const occurredAt = clientOccurredAt(rawOccurredAt, Date.now());
+
+  const appSessionId =
+    request.headers.get(REVIEW_APP_SESSION_ID_HEADER) ?? undefined;
+
+  const rawProperties: JsonObject = isJsonObject(properties) ? properties : {};
+
+  // The error fields come from the raw envelope and nowhere else; this
+  // helper drops any a client tried to assert. It matters because the
+  // allowlist cannot tell a cleaned message from a raw one.
+  const mergedProperties = mergeErrorTelemetryProperties(
+    rawProperties,
+    rawError,
+  );
+
+  if (appSessionId) mergedProperties.app_session_id = appSessionId;
+
+  const sanitized = sanitizeUiTelemetryEvent({
+    name,
+    properties: mergedProperties,
+  });
+
+  if (!sanitized) return;
+  const admitted = admitUiTelemetryEvent(sanitized);
+
+  if (!admitted) return;
+  const parsedContext = contextSchema.safeParse(rawContext);
+  const context = parsedContext.success ? parsedContext.data : undefined;
+  onSanitized?.(admitted, context);
+
+  try {
+    await telemetry.captureUiEvent?.(
+      admitted.event,
+      admitted.properties,
+      context,
+      occurredAt,
+    );
+  } catch (error) {
+    console.error(error);
+  }
+}

package/src/server-discovery.ts

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { z } from "zod";
+
+import { devReviewHome } from "./review-home-paths.js";
+
+const discoverySchema = z.object({
+  version: z.literal(1),
+  instanceId: z.uuid(),
+  url: z.url().refine((value) => {
+    const url = new URL(value);
+
+    return url.protocol === "http:" && url.hostname === "127.0.0.1";
+  }),
+  serverPid: z.number().int().positive(),
+  token: z.string().min(1),
+});
+
+export type ReviewServerDiscovery = z.infer<typeof discoverySchema>;
+
+export function reviewServerStateDir(env: NodeJS.ProcessEnv = process.env) {
+  return env.DEV_REVIEW_SERVER_DIR?.trim()
+    ? path.resolve(env.DEV_REVIEW_SERVER_DIR.trim())
+    : devReviewHome(env);
+}
+
+export function reviewServerDiscoveryPath(stateDir: string) {
+  return path.join(stateDir, "review-server", "server.json");
+}
+
+export function headlessServerLockPath(stateDir: string) {
+  return path.join(stateDir, "headless-server.lock");
+}
+
+export async function readReviewServerDiscovery(
+  stateDir: string,
+): Promise<ReviewServerDiscovery | null> {
+  let source: string;
+
+  try {
+    source = await readFile(reviewServerDiscoveryPath(stateDir), "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return null;
+    throw error;
+  }
+
+  try {
+    return discoverySchema.parse(JSON.parse(source));
+  } catch {
+    throw new Error(
+      `Whiteboard server discovery in ${stateDir} is invalid or incompatible. Restart it with this version of whiteboard server start.`,
+    );
+  }
+}
+
+export async function reviewServerIsHealthy(discovery: ReviewServerDiscovery) {
+  return (await readReviewServerHealth(discovery)) !== null;
+}
+
+/** The recorded server's /health, or null when another or none answers. */
+export async function readReviewServerHealth(
+  discovery: Pick<ReviewServerDiscovery, "url" | "token" | "instanceId">,
+) {
+  try {
+    const response = await fetch(`${discovery.url}/health`, {
+      headers: { "x-review-token": discovery.token },
+      signal: AbortSignal.timeout(1_500),
+    });
+
+    if (!response.ok) return null;
+
+    const health = z
+      .object({
+        ok: z.literal(true),
+        instanceId: z.string(),
+        serverId: z.string().optional(),
+        version: z.string().optional(),
+      })
+      .safeParse(await response.json());
+
+    return health.success && health.data.instanceId === discovery.instanceId
+      ? health.data
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function serverNotReady(stateDir: string) {
+  return new Error(
+    `Whiteboard server is not ready in ${stateDir}. Run whiteboard server start --state-dir ${JSON.stringify(stateDir)}, then retry.`,
+  );
+}

package/src/session-markers.ts

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+
+import { parseJsonText } from "@dev.fast/review-protocol";
+import { writeFileAtomic } from "@dev.fast/trace-core";
+import { z } from "zod";
+
+import type { PostHogCaptureProperties } from "./posthog-capture-client";
+import { devReviewHome } from "./review-home-paths";
+import { reviewTelemetryChannel, uuidV7Schema } from "./telemetry-config";
+
+/**
+ * The envelope fields of the launch that opened a session which a later
+ * launch may not share. An abnormal end carries them so it counts against
+ * the launch that died, not the one that reported it. Closed values only.
+ */
+const launchEnvelopeSchema = z.object({
+  app_version: z.string().min(1).optional(),
+  cli_version: z.string().min(1),
+  version: z.string().min(1),
+  channel: z.enum(["stable", "preview", "dev"]),
+  environment: z.enum(["production", "ci", "internal", "e2e", "smoke"]),
+  surface: z.enum(["desktop", "cli", "headless", "mcp", "api"]),
+  node_major: z.number().int(),
+  arch: z.string().min(1),
+  os_version: z.string().min(1),
+  ci: z.boolean(),
+  internal: z.boolean(),
+  $session_id: uuidV7Schema.optional(),
+  install_age_days: z.number().int().nonnegative().optional(),
+});
+
+export type LaunchEnvelope = z.infer<typeof launchEnvelopeSchema>;
+
+/** Picks the launch fields out of an event envelope; undefined if malformed. */
+export function launchEnvelope(
+  properties: PostHogCaptureProperties,
+): LaunchEnvelope | undefined {
+  return launchEnvelopeSchema.safeParse(properties).data;
+}
+
+/**
+ * A review session the Desktop opened and has not yet reported as ended. The
+ * next launch turns any survivor into `review_session_ended{outcome:abnormal}`,
+ * which is the floor under crash and hang counts.
+ */
+export interface OpenSessionMarker {
+  presentationSessionId: string;
+  reviewUuid: string;
+  startedAt: number;
+  appSessionId?: string;
+  /**
+   * The process that owns the session: the Desktop's Electron main for its
+   * server. A live owner means the session is still open, whichever launch
+   * reconciles.
+   */
+  ownerPid?: number;
+  /** Absent on markers written before launches recorded their envelope. */
+  envelope?: LaunchEnvelope;
+}
+
+const markersSchema = z.array(
+  z.object({
+    presentationSessionId: z.string().min(1),
+    reviewUuid: z.string().min(1),
+    startedAt: z.number(),
+    appSessionId: z.string().min(1).optional(),
+    ownerPid: z.number().int().positive().optional(),
+    // A malformed envelope degrades to a legacy marker, not a lost one.
+    envelope: launchEnvelopeSchema.optional().catch(undefined),
+  }),
+);
+
+/** Per channel, like the telemetry config: each channel has its own identity. */
+export function openSessionMarkersPath(env: NodeJS.ProcessEnv): string {
+  return path.join(
+    devReviewHome(env),
+    "telemetry",
+    reviewTelemetryChannel(env) === "preview"
+      ? "open-sessions.preview.json"
+      : "open-sessions.json",
+  );
+}
+
+function readMarkers(file: string): OpenSessionMarker[] {
+  try {
+    const parsed = markersSchema.safeParse(
+      parseJsonText(readFileSync(file, "utf8")),
+    );
+
+    return parsed.success ? parsed.data : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeMarkers(file: string, markers: OpenSessionMarker[]): void {
+  writeFileAtomic(file, `${JSON.stringify(markers)}\n`, "utf8");
+}
+
+export function recordOpenSession(
+  file: string,
+  marker: OpenSessionMarker,
+): void {
+  const others = readMarkers(file).filter(
+    (existing) =>
+      existing.presentationSessionId !== marker.presentationSessionId,
+  );
+
+  writeMarkers(file, [...others, marker]);
+}
+
+export function clearOpenSession(
+  file: string,
+  presentationSessionId: string,
+): void {
+  if (!existsSync(file)) return;
+  writeMarkers(
+    file,
+    readMarkers(file).filter(
+      (marker) => marker.presentationSessionId !== presentationSessionId,
+    ),
+  );
+}
+
+/** Reads every marker and deletes the file. */
+export function takeOpenSessions(file: string): OpenSessionMarker[] {
+  const markers = readMarkers(file);
+  rmSync(file, { force: true });
+
+  return markers;
+}

package/src/sharing/auth.ts

@@ -0,0 +1,41 @@
+import { DEFAULT_STORE_ORIGIN, readStoreAuth } from "@dev.fast/trace-core";
+import { ReviewInputError } from "@review/review-api/document.js";
+
+/** CI credentials stay in the server environment and are never persisted to a profile. */
+export async function readSharingAuth(env: NodeJS.ProcessEnv = process.env) {
+  if (env.DEV_REVIEW_SHARE_TOKEN === undefined) {
+    if (env.DEV_REVIEW_SHARE_ORIGIN !== undefined)
+      throw new ReviewInputError(
+        "DEV_REVIEW_SHARE_ORIGIN requires DEV_REVIEW_SHARE_TOKEN.",
+      );
+
+    return readStoreAuth(env);
+  }
+
+  const token = env.DEV_REVIEW_SHARE_TOKEN.trim();
+
+  if (!token) throw new ReviewInputError("DEV_REVIEW_SHARE_TOKEN is empty.");
+  let url: URL;
+
+  try {
+    url = new URL(env.DEV_REVIEW_SHARE_ORIGIN ?? DEFAULT_STORE_ORIGIN);
+  } catch {
+    throw new ReviewInputError(
+      "DEV_REVIEW_SHARE_ORIGIN must be a bare HTTPS origin.",
+    );
+  }
+
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.pathname !== "/" ||
+    url.search ||
+    url.hash
+  )
+    throw new ReviewInputError(
+      "DEV_REVIEW_SHARE_ORIGIN must be a bare HTTPS origin.",
+    );
+
+  return { origin: url.origin, token };
+}

package/src/sharing/cli.ts

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import type { Writable } from "node:stream";
+
+import { connectReviewApi } from "@review/review-api/agent-client.js";
+import { z } from "zod";
+
+const resultSchema = z.strictObject({
+  shareId: z.uuid(),
+  version: z.number().int(),
+  url: z.url(),
+});
+
+export async function runShareCli(input: {
+  review?: string;
+  version?: string;
+  requestId?: string;
+  preview?: boolean;
+  revoke?: string;
+  json?: boolean;
+  env?: NodeJS.ProcessEnv;
+  stdout: Writable;
+  stderr: Writable;
+}) {
+  try {
+    const client = await connectReviewApi(input.env);
+
+    if (input.revoke) {
+      const result = z
+        .strictObject({ shareId: z.uuid(), revoked: z.literal(true) })
+        .parse(await client.post("/sharing/revoke", { shareId: input.revoke }));
+
+      input.stdout.write(
+        input.json
+          ? JSON.stringify(result) + "\n"
+          : "Share revoked. Existing downloads remain available offline.\n",
+      );
+    } else {
+      if (!input.review) throw new Error("Use whiteboard share --review <id>.");
+
+      const version =
+        input.version === undefined
+          ? undefined
+          : z.number().int().nonnegative().parse(Number(input.version));
+
+      input.stderr.write(
+        "Sharing includes retained images, maps, and full trace conversations. Anyone with the link can download them. Reviews with code require GitHub repository access to fetch the pinned commits.\n",
+      );
+
+      const result = resultSchema.parse(
+        await client.post("/sharing/publish", {
+          reviewId: input.review,
+          version,
+          requestId:
+            input.requestId === undefined
+              ? randomUUID()
+              : z.uuid().parse(input.requestId),
+        }),
+      );
+
+      if (input.preview) {
+        const url = new URL(result.url);
+        url.searchParams.set("app", "preview");
+        result.url = url.href;
+      }
+
+      input.stdout.write(
+        input.json ? JSON.stringify(result) + "\n" : result.url + "\n",
+      );
+    }
+
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Sharing failed.";
+
+    if (input.json)
+      input.stdout.write(
+        JSON.stringify({ error: { code: "share_failed", message } }) + "\n",
+      );
+    input.stderr.write(message + "\n");
+
+    return 1;
+  }
+}