The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Add an endpoint that outputs Data App Dev diagnostic reports for an agent (#78358)
Timofey Kachalov5fe045c2ab85
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx b/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsxindex 6c276693f62..42b31d25684 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx@@ -10,13 +10,17 @@ import {DataAppDevProvider,DevToolbar,createDataAppSandbox,- installDevDiagnostics,+ installDiagnosticsReporter,+ sdkCallCapture,+ devDiagnostics,+ instanceConnectionCheck,} from "@metabase/embedding-sdk-react/data-app-dev";import {allowedHosts,appSlug,bundleUrl,rebuiltEvent,+ sdkVersion,} from "virtual:metabase-data-app-dev-config";import { createRoot } from "react-dom/client";@@ -24,41 +28,48 @@ import { createRoot } from "react-dom/client";// dev preview matches production. style-loader injects it at runtime.import "metabase-enterprise/data_apps/sandbox/iframe-baseline.css";-// The data-app dev entry. rspack bundles this file into the SDK dist as-// `data-app-dev-entry.js` (see `rspack.embedding-sdk-package.config.js`),-// inlining the sandbox + dev toolbar so they aren't part of the package's public-// API. `react`, `react-dom`, `@metabase/embedding-sdk-react/*`, and the dev-// plugin's `virtual:metabase-data-app-dev-config` are left EXTERNAL, so the-// consumer's Vite resolves them — the bundle runs against the consumer's single-// React/SDK instance (the same ones the app bundle is endowed with), and the dev-// plugin provides the config (the app's `allowed_hosts` + the bundle URL/event).-//-// It mounts the diagnostics toolbar, builds the Near-Membrane sandbox, then-// fetches + evaluates the app's IIFE bundle and renders it under-// `DataAppDevProvider`. Load failures go through `console.error`, so the toolbar-// surfaces them.+// Built by rspack into the SDK dist (`rspack.embedding-sdk-package.config.js`).+// React, the SDK subpaths and the virtual config stay EXTERNAL so the consumer's+// Vite resolves them: the preview has to run against the same React and SDK+// instances the app bundle is endowed with, not copies of them.+// Either may be missing from `.env.local`. Rendering anyway is deliberate: the+// requests then fail, and the diagnostics feed names the env var to fill — which+// beats a blank page with the reason only in the terminal.const authConfig = {- metabaseInstanceUrl: import.meta.env.DATA_APP_MB_URL,- apiKey: import.meta.env.DATA_APP_MB_API_KEY,+ metabaseInstanceUrl: import.meta.env.DATA_APP_MB_URL ?? "",+ apiKey: import.meta.env.DATA_APP_MB_API_KEY ?? "",};-installDevDiagnostics();+devDiagnostics.install();++instanceConnectionCheck.install({+ metabaseUrl: authConfig.metabaseInstanceUrl,+ sdkVersion,+});++sdkCallCapture.install(authConfig.metabaseInstanceUrl);++const hot = import.meta.hot;const toolbarRoot = document.createElement("div");+document.body.appendChild(toolbarRoot);createRoot(toolbarRoot).render(<DevToolbar />);const root = document.getElementById("root");+if (!root) {throw new Error("#root not found");}+const appRoot = createRoot(root);const sandbox = createDataAppSandbox({label: "dev",targetWindow: window,allowedHosts,+ onBlocked: devDiagnostics.recordSandboxBlocked,endowments: {React,reactDom: ReactDOM,@@ -98,8 +109,12 @@ loadAndRender().catch((error) => {console.error(error);});-if (import.meta.hot) {- import.meta.hot.on(rebuiltEvent, () => {+if (hot) {+ // Mirror the toolbar's data to the dev server, which re-serves it as JSON for+ // tools that have a shell but no browser (see `diagnostics-channel.ts`).+ installDiagnosticsReporter(hot);++ hot.on(rebuiltEvent, () => {loadAndRender().catch((error) => {console.error(error);});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev.tsindex 35c6a43e144..c58fcddc370 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev.ts@@ -2,5 +2,8 @@// The Node Vite config preset lives at `/data-app-dev/config` (data-app-dev.config.ts).export { DataAppDevProvider } from "./data-app-dev/components/DataAppDevProvider/DataAppDevProvider";export { DevToolbar } from "./data-app-dev/components/DevToolbar/DevToolbar";-export { installDevDiagnostics } from "./data-app-dev/components/DevToolbar/diagnostics";+export { devDiagnostics } from "./data-app-dev/components/DevToolbar/diagnostics";+export { instanceConnectionCheck } from "./data-app-dev/lib/instance-connection-check";+export { installDiagnosticsReporter } from "./data-app-dev/lib/diagnostics-reporter";+export { sdkCallCapture } from "./data-app-dev/lib/sdk-call-capture";export { createDataAppSandbox } from "metabase-enterprise/data_apps/sandbox/sandbox";diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.tsx b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.tsxindex 87898249519..a0904e2daf9 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.tsx+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.tsx@@ -2,19 +2,19 @@import cx from "classnames";import { useState, useSyncExternalStore } from "react";+import { formatDevDiagnostic, isAlert } from "../../lib/diagnostics-payload";+import S from "./DevToolbar.module.css";-import {- clearDevDiagnostics,- getDevDiagnostics,- subscribeDevDiagnostics,-} from "./diagnostics";+import { devDiagnostics } from "./diagnostics";export function DevToolbar() {- const entries = useSyncExternalStore(- subscribeDevDiagnostics,- getDevDiagnostics,+ const captured = useSyncExternalStore(+ devDiagnostics.subscribe,+ devDiagnostics.getEntries,);const [open, setOpen] = useState(false);++ const entries = captured.filter(isAlert);const count = entries.length;return (@@ -27,7 +27,7 @@ export function DevToolbar() {<buttontype="button"className={S.Action}- onClick={clearDevDiagnostics}+ onClick={devDiagnostics.clear}>Clear</button>@@ -51,7 +51,9 @@ export function DevToolbar() {<div className={S.EntryTime}>{new Date(entry.time).toLocaleTimeString()}</div>- <div className={S.EntryMessage}>{entry.message}</div>+ <div className={S.EntryMessage}>+ {formatDevDiagnostic(entry)}+ </div></div>)))}diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsxindex 86a335a5675..bfe9d127f27 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx@@ -3,7 +3,7 @@ import userEvent from "@testing-library/user-event";import { act, render, screen } from "__support__/ui";import { DevToolbar } from "./DevToolbar";-import { clearDevDiagnostics, installDevDiagnostics } from "./diagnostics";+import { devDiagnostics } from "./diagnostics";const recordError = (message: string) => {act(() => {@@ -16,7 +16,7 @@ let originalConsoleError: typeof console.error;beforeAll(() => {originalConsoleError = console.error;console.error = () => {};- installDevDiagnostics();+ devDiagnostics.install();});afterAll(() => {@@ -24,7 +24,7 @@ afterAll(() => {});beforeEach(() => {- clearDevDiagnostics();+ devDiagnostics.clear();});const getToggle = () => screen.getByRole("button", { name: /Diagnostics/ });@@ -74,6 +74,45 @@ describe("DevToolbar", () => {expect(getToggle()).toHaveTextContent(/^⚠ Diagnostics$/);});+ it("leaves successful requests off the badge and out of the panel", async () => {+ render(<DevToolbar />);+ act(() => {+ devDiagnostics.record({+ kind: "sdk-call",+ method: "GET",+ endpoint: "/api/card/1",+ status: 200,+ durationMs: 12,+ });+ });++ // Every request lands in the collector now. Counting them would warn about+ // a page that is working.+ expect(getToggle()).toHaveTextContent(/^⚠ Diagnostics$/);++ await userEvent.click(getToggle());+ expect(screen.getByText("No errors captured.")).toBeInTheDocument();+ });++ it("still badges a request that failed", async () => {+ render(<DevToolbar />);+ act(() => {+ devDiagnostics.record({+ kind: "sdk-call",+ method: "POST",+ endpoint: "/api/dataset",+ status: 400,+ durationMs: 8,+ error: "Table does not exist",+ });+ });++ expect(getToggle()).toHaveTextContent("⚠ Diagnostics (1)");++ await userEvent.click(getToggle());+ expect(screen.getByText(/Table does not exist/)).toBeInTheDocument();+ });+it("closes the panel when Close is clicked", async () => {render(<DevToolbar />);diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.tsindex e5f0fde1f3d..07989090b69 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts@@ -1,114 +1,159 @@-// Dev diagnostics store for the data-app dev toolbar. Captures errors —-// including the sandbox's `[data-app …] blocked API call: …` logs, which surface-// through `console.error` — so the toolbar can show what went wrong (the sandbox-// otherwise reports blocked APIs only as an opaque `#<Object>`).-//-// Capture is opt-in: it only patches `console.error` / listens for uncaught-// errors once `installDevDiagnostics()` is called. Nothing here runs on import,-// so a host that imports `createDataAppSandbox` from the same entry doesn't pull-// any of this in unless it's actually used.--export type DevDiagnosticLevel = "error";--export interface DevDiagnosticEntry {- id: number;- time: number;- level: DevDiagnosticLevel;- message: string;-}+import type { SandboxBlockedEvent } from "metabase-enterprise/data_apps/sandbox/types";++import {+ trimDiagnosticEntries,+ truncateDiagnosticText,+} from "../../lib/diagnostics-limits";+import type {+ DevDiagnosticEntry,+ DevDiagnosticEvent,+} from "../../types/diagnostics";+import type { InstanceConnectionStatus } from "../../types/diagnostics-channel";-const MAX_ENTRIES = 200;+/**+ * In-page collector of what the dev preview captured — uncaught errors, CSP+ * violations, sandbox blocks, SDK calls — plus the instance connection status.+ * `install()` starts the capture; readers (the toolbar, the reporter) subscribe.+ */+export class DevDiagnosticsCollector {+ private entries: DevDiagnosticEntry[] = [];+ private connectionStatus: InstanceConnectionStatus | null = null;+ private nextEntryId = 1;+ private uncapturedConsoleError: typeof console.error | null = null;+ private readonly listeners = new Set<() => void>();++ /**+ * Wraps `console.error` and listens for uncaught errors.+ */+ install(): void {+ const originalError = console.error.bind(console);+ this.uncapturedConsoleError = originalError;++ console.error = (...args: unknown[]) => {+ this.record({+ kind: "error",+ message: args.map((arg) => this.formatArg(arg)).join(" "),+ });++ originalError(...args);+ };++ window.addEventListener("error", (event) => {+ if (event.error != null || event.message) {+ this.record({+ kind: "error",+ message: this.formatArg(event.error ?? event.message),+ });+ }+ });++ window.addEventListener("unhandledrejection", (event) => {+ this.record({+ kind: "error",+ message: `Unhandled rejection: ${this.formatArg(event.reason)}`,+ });+ });++ window.addEventListener("securitypolicyviolation", (event) => {+ this.record({+ kind: "csp-violation",+ directive: event.effectiveDirective || event.violatedDirective,+ blockedUri: event.blockedURI,+ });+ });+ }-let entries: DevDiagnosticEntry[] = [];-let nextId = 1;-let installed = false;-const listeners = new Set<() => void>();+ record(event: DevDiagnosticEvent): void {+ const newEntry = {+ id: this.nextEntryId++,+ time: Date.now(),+ ...this.truncateEventText(event),+ };-const emit = () => {- for (const listener of listeners) {- listener();+ this.entries = trimDiagnosticEntries([...this.entries, newEntry]);+ this.emit();}-};-const formatArg = (arg: unknown): string => {- if (typeof arg === "string") {- return arg;- }- if (arg instanceof Error) {- return arg.stack ?? `${arg.name}: ${arg.message}`;- }- try {- return JSON.stringify(arg);- } catch {- return String(arg);+ recordSandboxBlocked = (event: SandboxBlockedEvent): void => {+ if (event.type === "api") {+ this.record({ kind: "blocked-api", message: event.message });+ this.logToConsole(event.message);++ return;+ }++ this.record({+ kind: "blocked-network",+ api: event.api,+ url: event.url,+ reason: event.reason,+ });++ this.logToConsole(+ `[data-app dev] blocked ${event.api === "xhr" ? "XMLHttpRequest" : "fetch"} to ${event.reason}`,+ );+ };++ getEntries = (): readonly DevDiagnosticEntry[] => this.entries;++ getConnectionStatus(): InstanceConnectionStatus | null {+ return this.connectionStatus;}-};-/**- * Format a CSP violation for the toolbar. The dev server mirrors Metabase's- * production CSP, so a violation here means the app would be blocked once- * sandboxed in Metabase too — e.g. a native `<form action="…">` hitting- * `form-action 'none'`, or a `fetch` to a host outside `allowed_hosts`. These- * never reach `console.error`, so the toolbar wouldn't see them otherwise.- */-const formatCspViolation = (event: SecurityPolicyViolationEvent): string => {- const directive = event.effectiveDirective || event.violatedDirective;- const target = event.blockedURI || "inline content";-- return `Content Security Policy (${directive}) blocked ${target}`;-};--const record = (level: DevDiagnosticLevel, message: string) => {- // New array reference each time so `useSyncExternalStore` re-renders.- entries = [...entries, { id: nextId++, time: Date.now(), level, message }];- if (entries.length > MAX_ENTRIES) {- entries = entries.slice(-MAX_ENTRIES);+ setConnectionStatus(status: InstanceConnectionStatus): void {+ this.connectionStatus = status;+ this.emit();}- emit();-};-export const getDevDiagnostics = (): readonly DevDiagnosticEntry[] => entries;+ subscribe = (listener: () => void): (() => void) => {+ this.listeners.add(listener);-export const subscribeDevDiagnostics = (listener: () => void): (() => void) => {- listeners.add(listener);- return () => {- listeners.delete(listener);+ return () => {+ this.listeners.delete(listener);+ };};-};-export const clearDevDiagnostics = (): void => {- entries = [];- emit();-};+ clear = (): void => {+ this.entries = [];+ this.emit();+ };-/**- * Start capturing errors into the diagnostics store: wraps `console.error` and- * listens for uncaught errors / unhandled rejections. Idempotent. Call it before- * the sandbox runs so nothing is missed.- */-export const installDevDiagnostics = (): void => {- if (installed || typeof window === "undefined") {- return;+ private emit() {+ for (const listener of this.listeners) {+ listener();+ }}- installed = true;- const originalError = console.error.bind(console);- console.error = (...args: unknown[]) => {- record("error", args.map(formatArg).join(" "));- originalError(...args);- };+ private logToConsole(message: string) {+ this.uncapturedConsoleError?.(message);+ }- window.addEventListener("error", (event) => {- if (event.error != null || event.message) {- record("error", formatArg(event.error ?? event.message));+ private formatArg(arg: unknown): string {+ if (typeof arg === "string") {+ return truncateDiagnosticText(arg);}- });- window.addEventListener("unhandledrejection", (event) => {- record("error", `Unhandled rejection: ${formatArg(event.reason)}`);- });+ if (arg instanceof Error && arg.stack) {+ return truncateDiagnosticText(arg.stack);+ }++ let json: string | undefined;+ try {+ json = JSON.stringify(arg);+ } catch {}++ return truncateDiagnosticText(json ?? String(arg));+ }++ private truncateEventText(event: DevDiagnosticEvent): DevDiagnosticEvent {+ // Safe cast: only string values are rewritten, so the shape is unchanged.+ return Object.fromEntries(+ Object.entries(event).map(([key, value]) => [+ key,+ typeof value === "string" ? truncateDiagnosticText(value) : value,+ ]),+ ) as DevDiagnosticEvent;+ }+}- window.addEventListener("securitypolicyviolation", (event) => {- record("error", formatCspViolation(event));- });-};+export const devDiagnostics = new DevDiagnosticsCollector();diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.tsindex 2b43636276f..eacd45e04a6 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts@@ -1,12 +1,12 @@-import {- type DevDiagnosticEntry,- clearDevDiagnostics,- getDevDiagnostics,- installDevDiagnostics,- subscribeDevDiagnostics,-} from "./diagnostics";--const last = (entries: readonly DevDiagnosticEntry[]) =>+import { DATA_APP_DIAGNOSTIC_MAX_CHARS } from "../../constants/diagnostics-channel";+// `formatDevDiagnostic` is a lens onto captured entries — the projection lives+// in the payload module now, this spec only uses it to read what was captured.+import { formatDevDiagnostic } from "../../lib/diagnostics-payload";+import type { DevDiagnosticEntry } from "../../types/diagnostics";++import { devDiagnostics } from "./diagnostics";++const getLastEntry = (entries: readonly DevDiagnosticEntry[]) =>entries[entries.length - 1];let forwarded: unknown[][] = [];@@ -17,7 +17,7 @@ beforeAll(() => {console.error = (...args: unknown[]) => {forwarded.push(args);};- installDevDiagnostics();+ devDiagnostics.install();});afterAll(() => {@@ -25,22 +25,22 @@ afterAll(() => {});beforeEach(() => {- clearDevDiagnostics();+ devDiagnostics.clear();forwarded = [];});-describe("dev diagnostics store", () => {+describe("dev diagnostics collector", () => {it("starts empty", () => {- expect(getDevDiagnostics()).toEqual([]);+ expect(devDiagnostics.getEntries()).toEqual([]);});it("records console.error calls as error entries with id/time/message", () => {console.error("boom", { code: 1 });- const entries = getDevDiagnostics();+ const entries = devDiagnostics.getEntries();expect(entries).toHaveLength(1);expect(entries[0]).toMatchObject({- level: "error",+ kind: "error",message: 'boom {"code":1}',});expect(typeof entries[0].id).toBe("number");@@ -53,10 +53,29 @@ describe("dev diagnostics store", () => {expect(forwarded).toContainEqual(["passed through"]);});+ it("survives arguments JSON cannot represent", () => {+ const noop = () => undefined;++ // `JSON.stringify` returns undefined rather than throwing for these. The+ // wrapper must still record and forward — breaking `console.error` itself+ // would take the app down over a log line.+ console.error(undefined);+ console.error(noop);+ console.error(Symbol("sym"));++ expect(+ devDiagnostics.getEntries().map((entry) => formatDevDiagnostic(entry)),+ ).toEqual(["undefined", String(noop), "Symbol(sym)"]);+ expect(forwarded).toContainEqual([undefined]);+ expect(forwarded).toContainEqual([noop]);+ });+it("formats Error arguments using their message", () => {console.error(new Error("kaboom"));- expect(last(getDevDiagnostics()).message).toContain("kaboom");+ expect(+ formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries())),+ ).toContain("kaboom");});it("captures uncaught window errors", () => {@@ -65,7 +84,9 @@ describe("dev diagnostics store", () => {});window.dispatchEvent(event);- expect(last(getDevDiagnostics()).message).toContain("window blew up");+ expect(+ formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries())),+ ).toContain("window blew up");});it("captures unhandled promise rejections", () => {@@ -74,10 +95,12 @@ describe("dev diagnostics store", () => {});window.dispatchEvent(event);- expect(last(getDevDiagnostics()).message).toBe("Unhandled rejection: nope");+ expect(formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries()))).toBe(+ "Unhandled rejection: nope",+ );});- it("captures CSP form-action violations (e.g. a blocked native form submit)", () => {+ it("captures CSP violations as typed entries", () => {const event = Object.assign(new Event("securitypolicyviolation"), {effectiveDirective: "form-action",violatedDirective: "form-action",@@ -86,33 +109,37 @@ describe("dev diagnostics store", () => {} satisfies Partial<SecurityPolicyViolationEvent>);window.dispatchEvent(event);- expect(last(getDevDiagnostics()).message).toBe(+ const entry = getLastEntry(devDiagnostics.getEntries());+ expect(entry).toMatchObject({+ kind: "csp-violation",+ directive: "form-action",+ blockedUri: "https://example.com/",+ });+ expect(formatDevDiagnostic(entry)).toBe("Content Security Policy (form-action) blocked https://example.com/",);});- it("formats other CSP violations generically (e.g. connect-src)", () => {- const event = Object.assign(new Event("securitypolicyviolation"), {- effectiveDirective: "connect-src",- violatedDirective: "connect-src",- blockedURI: "https://evil.test/",- originalPolicy: "connect-src 'self'; form-action 'none'",- } satisfies Partial<SecurityPolicyViolationEvent>);- window.dispatchEvent(event);+ it("formats a CSP violation with an empty URI as inline content", () => {+ devDiagnostics.record({+ kind: "csp-violation",+ directive: "script-src",+ blockedUri: "",+ });- expect(last(getDevDiagnostics()).message).toBe(- "Content Security Policy (connect-src) blocked https://evil.test/",+ expect(formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries()))).toBe(+ "Content Security Policy (script-src) blocked inline content",);});it("notifies subscribers on record and clear, and stops after unsubscribe", () => {const listener = jest.fn();- const unsubscribe = subscribeDevDiagnostics(listener);+ const unsubscribe = devDiagnostics.subscribe(listener);console.error("one");expect(listener).toHaveBeenCalledTimes(1);- clearDevDiagnostics();+ devDiagnostics.clear();expect(listener).toHaveBeenCalledTimes(2);unsubscribe();@@ -121,27 +148,171 @@ describe("dev diagnostics store", () => {});it("returns a fresh array reference per record (so useSyncExternalStore re-renders)", () => {- const before = getDevDiagnostics();+ const before = devDiagnostics.getEntries();console.error("change");- expect(getDevDiagnostics()).not.toBe(before);+ expect(devDiagnostics.getEntries()).not.toBe(before);});- it("is idempotent — installing again does not double-record", () => {- installDevDiagnostics();- console.error("once");-- expect(getDevDiagnostics()).toHaveLength(1);- });-- it("caps stored entries at 200, keeping the most recent", () => {+ it("trims stored entries to 200, keeping the most recent", () => {for (let i = 0; i < 205; i++) {console.error(`error ${i}`);}- const entries = getDevDiagnostics();+ const entries = devDiagnostics.getEntries();expect(entries).toHaveLength(200);- expect(entries[0].message).toBe("error 5");- expect(last(entries).message).toBe("error 204");+ expect(formatDevDiagnostic(entries[0])).toBe("error 5");+ expect(formatDevDiagnostic(getLastEntry(entries))).toBe("error 204");+ });++ it("does not let a flood of requests evict earlier errors", () => {+ console.error("the error worth keeping");++ for (let i = 0; i < 500; i++) {+ devDiagnostics.record({+ kind: "sdk-call",+ method: "GET",+ endpoint: `/api/card/${i}`,+ status: 200,+ durationMs: 1,+ });+ }++ // A polling app used to push whatever explained its own failures out of the+ // shared buffer — the one entry an author or an agent actually needs.+ const entries = devDiagnostics.getEntries();+ expect(formatDevDiagnostic(entries[0])).toBe("the error worth keeping");+ expect(entries.filter((entry) => entry.kind === "sdk-call")).toHaveLength(+ 50,+ );+ });+});++describe("devDiagnostics.recordSandboxBlocked", () => {+ it("records a blocked API as a blocked-api entry and logs it uncaptured", () => {+ devDiagnostics.recordSandboxBlocked({+ type: "api",+ message: "[data-app dev] blocked API call: document.write",+ });++ const entries = devDiagnostics.getEntries();+ expect(entries).toHaveLength(1);+ expect(entries[0]).toMatchObject({+ kind: "blocked-api",+ message: "[data-app dev] blocked API call: document.write",+ });+ // Forwarded to the real console, without being re-captured as an error.+ expect(forwarded).toContainEqual([+ "[data-app dev] blocked API call: document.write",+ ]);+ });++ it("records a blocked network call as a blocked-network entry and logs it uncaptured", () => {+ devDiagnostics.recordSandboxBlocked({+ type: "network",+ api: "fetch",+ url: "https://evil.test/x",+ reason: "evil.test (not in allowed_hosts)",+ });++ const entries = devDiagnostics.getEntries();+ expect(entries).toHaveLength(1);+ expect(entries[0]).toMatchObject({+ kind: "blocked-network",+ api: "fetch",+ url: "https://evil.test/x",+ reason: "evil.test (not in allowed_hosts)",+ });+ expect(formatDevDiagnostic(entries[0])).toBe(+ "Blocked fetch to evil.test (not in allowed_hosts)",+ );+ expect(forwarded).toContainEqual([+ "[data-app dev] blocked fetch to evil.test (not in allowed_hosts)",+ ]);+ });+});++describe("sdk-call entries", () => {+ it("formats a completed call with status and duration", () => {+ devDiagnostics.record({+ kind: "sdk-call",+ method: "POST",+ endpoint: "/api/card/1/query",+ status: 202,+ durationMs: 45,+ });++ expect(formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries()))).toBe(+ "POST /api/card/1/query → 202 (45ms)",+ );+ });++ it("keeps the endpoint on the summary line and the reason below it", () => {+ devDiagnostics.record({+ kind: "sdk-call",+ method: "POST",+ endpoint: "/api/dataset",+ status: 400,+ durationMs: 12,+ error: 'Table "orders" is not in the manifest',+ });++ expect(formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries()))).toBe(+ 'POST /api/dataset → 400 (12ms)\nTable "orders" is not in the manifest',+ );+ });++ it("formats a transport failure, which has no status", () => {+ devDiagnostics.record({+ kind: "sdk-call",+ method: "GET",+ endpoint: "/api/user/current",+ status: null,+ durationMs: 5,+ error: "Failed to fetch",+ });++ expect(formatDevDiagnostic(getLastEntry(devDiagnostics.getEntries()))).toBe(+ "GET /api/user/current → failed (5ms)\nFailed to fetch",+ );+ });+});++describe("connection status", () => {+ it("stores the connection status and notifies subscribers", () => {+ const listener = jest.fn();+ const unsubscribe = devDiagnostics.subscribe(listener);++ devDiagnostics.setConnectionStatus({+ checkedAt: 1,+ metabaseUrl: "http://localhost:3000",+ reachable: true,+ sdkVersion: "0.63.1",+ error: null,+ });++ expect(devDiagnostics.getConnectionStatus()).toMatchObject({+ reachable: true,+ });+ expect(listener).toHaveBeenCalledTimes(1);+ unsubscribe();+ });+});++describe("bounded entry size", () => {+ it("truncates a huge logged object instead of retaining it whole", () => {+ devDiagnostics.clear();++ // The count limit alone bounds nothing: one entry can be arbitrarily large,+ // and it is retained twice and re-serialized on every poll.+ console.error("rows", {+ rows: Array.from({ length: 50_000 }, (_, i) => i),+ });++ const [entry] = devDiagnostics.getEntries();+ expect(entry.kind).toBe("error");+ const message = entry.kind === "error" ? entry.message : "";+ expect(message.length).toBeLessThan(DATA_APP_DIAGNOSTIC_MAX_CHARS * 2);+ expect(message).toContain("truncated");});});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.tsindex f68f5eaa2ce..0d0f510ad83 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.ts@@ -20,9 +20,7 @@ export const buildDevCsp = (...(instanceOrigin ? [instanceOrigin] : []),...allowedHosts,];- const formAction =- allowedHosts.length > 0 ? allowedHosts.join(" ") : "'none'";- const frameSrc = ["'self'", ...allowedHosts].join(" ");- return `connect-src ${sources.join(" ")}; form-action ${formAction}; frame-src ${frameSrc}`;+ // Match the production iframe CSP+ return `connect-src ${sources.join(" ")}; form-action 'none'; frame-src 'none'`;};diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.unit.spec.tsindex 9534dee3e33..9361be8e3b5 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.unit.spec.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/dev-connect-src.unit.spec.ts@@ -11,25 +11,25 @@ function directive(csp: string, name: string): string | undefined {}describe("buildDevCsp", () => {- it("blocks native submits and limits framing to 'self' when no allowed_hosts", () => {+ it("blocks native submits and framing", () => {const csp = buildDevCsp([], undefined);expect(directive(csp, "connect-src")).toBe("'self' ws://localhost:* wss://localhost:* ws://127.0.0.1:* wss://127.0.0.1:*",);expect(directive(csp, "form-action")).toBe("'none'");- expect(directive(csp, "frame-src")).toBe("'self'");+ expect(directive(csp, "frame-src")).toBe("'none'");});- it("adds allowed_hosts to connect-src, form-action and frame-src", () => {+ it("adds allowed_hosts to connect-src only, never to form-action or frame-src", () => {const hosts = ["https://api.example.com", "https://*.trusted.test"];const csp = buildDevCsp(hosts, undefined);for (const host of hosts) {expect(directive(csp, "connect-src")).toContain(host);}- expect(directive(csp, "form-action")).toBe(hosts.join(" "));- expect(directive(csp, "frame-src")).toBe(`'self' ${hosts.join(" ")}`);+ expect(directive(csp, "form-action")).toBe("'none'");+ expect(directive(csp, "frame-src")).toBe("'none'");});it("adds the Metabase instance origin to connect-src only, normalized to an origin", () => {@@ -41,7 +41,7 @@ describe("buildDevCsp", () => {expect(csp).not.toContain("secret");// The instance origin is for fetch, not for submitting/framing.expect(directive(csp, "form-action")).toBe("'none'");- expect(directive(csp, "frame-src")).toBe("'self'");+ expect(directive(csp, "frame-src")).toBe("'none'");});it("ignores an unparseable Metabase URL", () => {diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/validate-manifest.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/validate-manifest.tsnew file mode 100644index 00000000000..0cc4084c6a4--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/validate-manifest.ts@@ -0,0 +1,112 @@+import fs from "node:fs";+import path from "node:path";++import { load as parseYaml } from "js-yaml";++import { DATA_APP_MANIFEST_FILE_NAME } from "../constants/paths";+import type { DataAppManifestStatus } from "../types/manifest-status";++const asNonEmptyString = (value: unknown): string | null => {+ if (+ typeof value !== "string" &&+ typeof value !== "number" &&+ typeof value !== "boolean"+ ) {+ return null;+ }++ const trimmed = String(value).trim();++ return trimmed || null;+};++const compareAllowedHosts = (+ prevHosts: string[],+ nextHosts: string[],+): boolean => {+ const normalize = (hosts: string[]) =>+ hosts.map((entry) => entry.trim().toLowerCase()).sort();++ const [prev, next] = [normalize(prevHosts), normalize(nextHosts)];++ return (+ prev.length === next.length &&+ prev.every((entry, index) => entry === next[index])+ );+};++/**+ * Not a full validator: the manifest rules live in the backend's `parse-app-config`+ * and a copy here would drift. This only adds what the backend cannot see —+ * this machine's disk, and what the dev server booted with.+ */+export function validateDataAppManifest(+ appRoot: string,+ initialAllowedHosts: string[],+): DataAppManifestStatus {+ const status: DataAppManifestStatus = {+ checkedAt: Date.now(),+ name: null,+ bundlePath: null,+ bundlePathExists: false,+ allowedHosts: [],+ errors: [],+ warnings: [],+ restartRequired: false,+ };++ const manifestPath = path.join(appRoot, DATA_APP_MANIFEST_FILE_NAME);++ if (!fs.existsSync(manifestPath)) {+ status.errors.push(+ `No ${DATA_APP_MANIFEST_FILE_NAME} found — this app will not sync.`,+ );++ return status;+ }++ let parsed: unknown;+ try {+ parsed = parseYaml(fs.readFileSync(manifestPath, "utf8"));+ } catch (error) {+ status.errors.push(+ `Could not parse ${DATA_APP_MANIFEST_FILE_NAME}: ${+ error instanceof Error ? error.message : String(error)+ }`,+ );++ return status;+ }++ // js-yaml types the parse result is `unknown`+ const fields = (parsed ?? {}) as Record<string, unknown>;+ const manifestValue = (key: string): unknown => fields[key];++ status.name = asNonEmptyString(manifestValue("name"));+ status.bundlePath = asNonEmptyString(manifestValue("path"));++ if (status.bundlePath != null) {+ status.bundlePathExists = fs.existsSync(+ path.join(appRoot, status.bundlePath),+ );++ if (!status.bundlePathExists) {+ status.warnings.push(+ `"${status.bundlePath}" does not exist — run \`npm run build\` before committing, or sync will fail.`,+ );+ }+ }++ const rawHosts = manifestValue("allowed_hosts");++ status.allowedHosts = Array.isArray(rawHosts)+ ? rawHosts.map((entry) => String(entry))+ : [];++ status.restartRequired = !compareAllowedHosts(+ initialAllowedHosts,+ status.allowedHosts,+ );++ return status;+}diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/validate-manifest.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/validate-manifest.unit.spec.tsnew file mode 100644index 00000000000..bfa350dc6ef--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/config/validate-manifest.unit.spec.ts@@ -0,0 +1,130 @@+import fs from "node:fs";+import path from "node:path";++import { validateDataAppManifest } from "./validate-manifest";++jest.mock("node:fs");++const mockedFs = jest.mocked(fs);++const APP_ROOT = "/repo/data_apps/sales";+const YAML_PATH = path.join(APP_ROOT, "data_app.yaml");++const VALID_YAML = `+name: Sales dashboard+path: dist/index.js+`;++const setup = (files: Record<string, string | true>) => {+ mockedFs.existsSync.mockImplementation((p) => p.toString() in files);+ mockedFs.readFileSync.mockImplementation((p) => {+ const content = files[p.toString()];++ if (typeof content !== "string") {+ throw new Error(`unexpected read: ${p}`);+ }++ return content;+ });+};++afterEach(() => jest.resetAllMocks());++describe("validateDataAppManifest", () => {+ it("errors when the manifest is missing (the app would silently not sync)", () => {+ setup({});++ const status = validateDataAppManifest(APP_ROOT, []);++ expect(status.errors).toEqual([+ "No data_app.yaml found — this app will not sync.",+ ]);+ });++ it("accepts a valid manifest whose bundle exists", () => {+ setup({+ [YAML_PATH]: VALID_YAML,+ [path.join(APP_ROOT, "dist/index.js")]: true,+ });++ const status = validateDataAppManifest(APP_ROOT, []);++ expect(status).toMatchObject({+ name: "Sales dashboard",+ bundlePath: "dist/index.js",+ bundlePathExists: true,+ allowedHosts: [],+ errors: [],+ warnings: [],+ restartRequired: false,+ });+ });++ it("reports an unparseable yaml", () => {+ setup({ [YAML_PATH]: "name: [unclosed" });++ const status = validateDataAppManifest(APP_ROOT, []);++ expect(status.errors).toHaveLength(1);+ expect(status.errors[0]).toContain("Could not parse data_app.yaml");+ });++ it("warns when the bundle file does not exist yet", () => {+ setup({ [YAML_PATH]: VALID_YAML });++ const status = validateDataAppManifest(APP_ROOT, []);++ expect(status.errors).toEqual([]);+ expect(status.warnings).toEqual([+ '"dist/index.js" does not exist — run `npm run build` before committing, or sync will fail.',+ ]);+ });++ it("flags a restart when allowed_hosts drift from what the server booted with", () => {+ setup({+ [YAML_PATH]: `${VALID_YAML}allowed_hosts:\n - https://api.example.com\n`,+ [path.join(APP_ROOT, "dist/index.js")]: true,+ });++ const status = validateDataAppManifest(APP_ROOT, []);++ expect(status.errors).toEqual([]);+ expect(status.restartRequired).toBe(true);+ });++ it("does not demand a restart for a padded or reordered allowed_hosts list", () => {+ // The startup list is the raw YAML; the validated list is normalized. Comparing+ // them naively reported a restart that restarting could never satisfy.+ setup({+ [YAML_PATH]: `+name: Sales dashboard+path: dist/index.js+allowed_hosts:+ - " https://B.example.com "+ - https://a.example.com+`,+ });++ const status = validateDataAppManifest(APP_ROOT, [+ "https://a.example.com",+ " https://B.example.com ",+ ]);++ expect(status.restartRequired).toBe(false);+ });++ it("accepts a non-string scalar the backend would stringify", () => {+ // `(some-> v str str/trim not-empty)` imports `name: 2024` as "2024".+ setup({+ [YAML_PATH]: `+name: 2024+path: dist/index.js+`,+ });++ const status = validateDataAppManifest(APP_ROOT, []);++ expect(status.name).toBe("2024");+ expect(status.errors).toEqual([]);+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.tsnew file mode 100644index 00000000000..26ef3bfa8c9--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.ts@@ -0,0 +1,26 @@+export const DATA_APP_DIAGNOSTICS_EVENT = "data-app:diagnostics";++// Server → page nudge. Carries no data: readers re-read the endpoint, so the+// toolbar and a shell agent never diverge on where the truth came from.+export const DATA_APP_DIAGNOSTICS_CHANGED_EVENT =+ "data-app:diagnostics-changed";++export const DATA_APP_DIAGNOSTICS_URL = "/__data-app/diagnostics";++export const START_EVENT_ID_PARAM = "startEventId";++export const DATA_APP_DIAGNOSTICS_LIMIT = 200;++// Requests outrun every other kind by orders of magnitude, so under one shared+// limit a polling app quietly evicts the very errors the requests are meant to+// explain. Limiting them separately keeps the rest of the buffer out of reach.+export const DATA_APP_DIAGNOSTICS_CALL_LIMIT = 50;++// Per-field character limit. Bounding the entry count alone bounds nothing: one+// `console.error("failed", rows)` can be an arbitrarily large string.+export const DATA_APP_DIAGNOSTIC_MAX_CHARS = 4000;++// Largest 2xx body the SDK-call capture will parse for a reported failure. A+// failed query carries no result rows, so it stays well under this; a larger+// body is a real result, not worth parsing just to find no error.+export const MAX_INSPECTED_BODY_CHARS = 128 * 1024;diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/env.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/env.tsnew file mode 100644index 00000000000..ff6bb8aa3a0--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/env.ts@@ -0,0 +1,4 @@+/** Read from the repo-root `.env.local`; see `config/find-env-root.ts`. */+export const DATA_APP_MB_URL_ENV = "DATA_APP_MB_URL";++export const DATA_APP_MB_API_KEY_ENV = "DATA_APP_MB_API_KEY";diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/paths.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/paths.tsindex dd19e2f182f..df6f0086cdd 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/paths.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/paths.ts@@ -1 +1,7 @@+export const SDK_PACKAGE_NAME = "@metabase/embedding-sdk-react";++export const PACKAGE_JSON_FILE_NAME = "package.json";++export const DATA_APP_MANIFEST_FILE_NAME = "data_app.yaml";+export const DATA_APP_DEV_ENTRY_FILE_NAME = "data-app-dev-entry.js";diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/timings.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/timings.tsnew file mode 100644index 00000000000..311b865b5e6--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/timings.ts@@ -0,0 +1,2 @@+/** How long the reporter batches page events before pushing them to the server. */+export const DIAGNOSTICS_FLUSH_MS = 100;diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.tsindex c69a5b7d062..09106ca4a53 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts@@ -1,8 +1,7 @@-import { type Connect, type Rollup, build } from "vite";+import { type Rollup, build } from "vite";import { dataAppBuildPlugins, dataAppLibBuild } from "../config/build-config";import { getDataAppDefine } from "../config/define";-import { DATA_APP_BUNDLE_URL } from "../constants/bundle";export interface AppBundleOptions {root: string;@@ -14,6 +13,7 @@ export interface AppBundle {/** Resolves `true` only for the call that produced fresh output. */rebuild: () => Promise<boolean>;readonly code: string;+ readonly lastRebuildAt: number | null;}export function createAppBundle({@@ -22,6 +22,7 @@ export function createAppBundle({onError,}: AppBundleOptions): AppBundle {let code = "";+ let lastRebuildAt: number | null = null;let building = false;let stale = false;@@ -37,6 +38,9 @@ export function createAppBundle({build: {write: false,minify: mode === "production",+ // Inline: only `chunk.code` is kept, so a sibling `.map` has nothing+ // to resolve against.+ sourcemap: "inline",...dataAppLibBuild("data-app-bundle.js"),},});@@ -49,6 +53,8 @@ export function createAppBundle({.find((chunk): chunk is Rollup.OutputChunk => chunk.type === "chunk")?.code ?? "";+ lastRebuildAt = Date.now();+return true;} catch (error) {onError(@@ -86,26 +92,9 @@ export function createAppBundle({get code() {return code;},- };-}--export const serveAppBundle =- (bundle: AppBundle): Connect.NextHandleFunction =>- (req, res, next) => {- if (req.url?.split("?")[0] !== DATA_APP_BUNDLE_URL) {- next();-- return;- }- if (!bundle.code) {- res.statusCode = 503;- res.setHeader("Content-Type", "text/plain");- res.end("data-app bundle is not built — see the dev server logs.");-- return;- }-- res.setHeader("Content-Type", "text/javascript");- res.end(bundle.code);+ get lastRebuildAt() {+ return lastRebuildAt;+ },};+}diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.tsindex 50fc5071d89..6b503281b43 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts@@ -24,12 +24,13 @@ beforeEach(() => {});describe("createAppBundle", () => {- it("exposes the built chunk", async () => {+ it("exposes the built chunk and when it was built", async () => {const bundle = setup();expect(await bundle.rebuild()).toBe(true);expect(bundle.code).toBe("built");+ expect(bundle.lastRebuildAt).toEqual(expect.any(Number));});it("reports a build failure instead of throwing at the dev server", async () => {@@ -42,6 +43,7 @@ describe("createAppBundle", () => {expect(onError).toHaveBeenCalledWith(expect.stringContaining("syntax error in App.tsx"),);+ expect(bundle.lastRebuildAt).toBeNull();});it("keeps the last good bundle when a later build fails", async () => {diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.tsnew file mode 100644index 00000000000..a706890e843--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.ts@@ -0,0 +1,110 @@+import {+ trimDiagnosticEntries,+ truncateDiagnosticText,+} from "../lib/diagnostics-limits";+import type {+ DataAppDiagnosticEntry,+ DataAppDiagnosticPayload,+ DataAppDiagnosticsMessage,+ DiagnosticsStoreReport,+ InstanceConnectionStatus,+} from "../types/diagnostics-channel";++/**+ * The dev server's buffer of what the preview page reported.+ **/+export class DiagnosticsStore {+ private entries: DataAppDiagnosticPayload[] = [];+ private connection: InstanceConnectionStatus | null = null;+ private lastReportAt: number | null = null;+ private sessionId: string | null = null;+ // Ids are assigned here rather than taken from the page, whose counter+ // restarts at 1 on every reload: a reader that already read up to 40 would+ // then skip everything the reloaded page reports.+ private nextEntryId = 1;++ applyMessage(message: DataAppDiagnosticsMessage): boolean {+ this.lastReportAt = Date.now();++ const connectionChanged = this.applyConnection(message?.connection);+ const sessionChanged = this.applySession(message?.sessionId);+ const entriesAdded = this.appendEntries(message?.entries);++ // Returns whether a reader would now see something different.+ return connectionChanged || sessionChanged || entriesAdded;+ }++ clear(): void {+ this.entries = [];+ }++ /**+ * Gets report starting from `startEventId`+ **/+ getReport(startEventId: number): DiagnosticsStoreReport {+ return {+ entries: Number.isFinite(startEventId)+ ? this.entries.filter((entry) => entry.eventId >= startEventId)+ : this.entries,+ connection: this.connection,+ lastReportAt: this.lastReportAt,+ sessionId: this.sessionId,+ nextEventId: this.nextEntryId,+ };+ }++ private applyConnection(+ nextConnection: InstanceConnectionStatus | null | undefined,+ ): boolean {+ if (!nextConnection) {+ return false;+ }++ // Compare by `checkedAt`, not by reference: every message arrives off the+ // socket as a fresh object, so a reference check would call each a change.+ const changed = nextConnection.checkedAt !== this.connection?.checkedAt;+ this.connection = nextConnection;++ return changed;+ }++ private applySession(sessionId: string | undefined): boolean {+ if (!sessionId || sessionId === this.sessionId) {+ return false;+ }++ // A reload does not empty the buffer: the errors that prompted it are the+ // ones a reader most needs. Only the size limit evicts. A reader that wants+ // the new page alone starts from the `nextEventId` it saw before the reload.+ this.sessionId = sessionId;++ return true;+ }++ private appendEntries(+ entries: DataAppDiagnosticEntry[] | undefined,+ ): boolean {+ if (!Array.isArray(entries) || entries.length === 0) {+ return false;+ }++ this.entries = trimDiagnosticEntries([+ ...this.entries,+ ...entries.map((entry) => this.toStoredEntry(entry)),+ ]);++ return true;+ }++ private toStoredEntry(+ entry: DataAppDiagnosticEntry,+ ): DataAppDiagnosticPayload {+ return {+ ...entry,+ summary: truncateDiagnosticText(entry.summary ?? ""),+ detail:+ entry.detail == null ? null : truncateDiagnosticText(entry.detail),+ eventId: this.nextEntryId++,+ };+ }+}diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.tsnew file mode 100644index 00000000000..e5443392cc2--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.ts@@ -0,0 +1,278 @@+import {+ DATA_APP_DIAGNOSTICS_CALL_LIMIT,+ DATA_APP_DIAGNOSTICS_LIMIT,+ DATA_APP_DIAGNOSTIC_MAX_CHARS,+} from "../constants/diagnostics-channel";+import type { DataAppDiagnosticEntry } from "../types/diagnostics-channel";++import { DiagnosticsStore } from "./diagnostics-store";++const entry = (+ over: Partial<DataAppDiagnosticEntry> = {},+): DataAppDiagnosticEntry => ({+ time: 1700000000000,+ kind: "error",+ summary: "boom",+ detail: null,+ hint: null,+ alert: true,+ ...over,+});++// The page stamps each load with a `sessionId`; a new one is how the server+// tells a reload (fresh id) from a soft HMR re-render (same id).+const message = (entries: DataAppDiagnosticEntry[], sessionId = "page-1") => ({+ sessionId,+ entries,+ connection: null,+});++describe("DiagnosticsStore", () => {+ it("stamps ids from one, so a poller can start at the beginning", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry({ summary: "first" })]));+ store.applyMessage(message([entry({ summary: "second" })]));++ expect(+ store.getReport(0).entries.map((e) => [e.eventId, e.summary]),+ ).toEqual([+ [1, "first"],+ [2, "second"],+ ]);+ expect(store.getReport(0).nextEventId).toBe(3);+ });++ it("keeps ids climbing across a reload so a poller's cursor stays valid", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry({ summary: "old page" })], "page-1"));+ store.applyMessage(message([entry({ summary: "new page" })], "page-2"));++ // Restarting at 1 would put the new page's events *behind* a cursor that+ // already advanced, and the toolbar would look healthy while going blank.+ const [, second] = store.getReport(0).entries;+ expect(second.summary).toBe("new page");+ expect(second.eventId).toBe(2);+ });++ it("keeps the previous page's events across a reload", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(+ message([entry({ summary: "before reload" })], "page-1"),+ );+ store.applyMessage(message([entry({ summary: "after reload" })], "page-2"));++ // The errors that prompted the reload are the ones a reader most needs.+ expect(store.getReport(0).entries.map((e) => e.summary)).toEqual([+ "before reload",+ "after reload",+ ]);+ expect(store.getReport(0).sessionId).toBe("page-2");+ });++ it("serves only the new page's events to a reader that carried its cursor", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(+ message([entry({ summary: "before reload" })], "page-1"),+ );+ const cursor = store.getReport(0).nextEventId;++ store.applyMessage(message([entry({ summary: "after reload" })], "page-2"));++ // How the toolbar shows post-reload entries only, without the buffer+ // having to forget anything.+ expect(store.getReport(cursor).entries.map((e) => e.summary)).toEqual([+ "after reload",+ ]);+ });++ it("keeps events reported under the same session", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry({ summary: "one" })], "page-1"));+ store.applyMessage(message([entry({ summary: "two" })], "page-1"));++ expect(store.getReport(0).entries).toHaveLength(2);+ });++ it("adopts the first session without discarding what came with it", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry({ summary: "first ever" })], "page-1"));++ expect(store.getReport(0).entries).toHaveLength(1);+ });++ it("returns only what a cursor has not seen", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(+ message([+ entry({ summary: "one" }),+ entry({ summary: "two" }),+ entry({ summary: "three" }),+ ]),+ );++ expect(store.getReport(3).entries.map((e) => e.summary)).toEqual(["three"]);+ expect(store.getReport(store.getReport(0).nextEventId).entries).toEqual([]);+ });++ it("returns everything for a cursor that isn't a number", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry()]));++ // `?startEventId=abc` parses to NaN, and `eventId >= NaN` is false for+ // every entry — so without the guard a typo yields an empty feed, which+ // reads as "nothing is wrong". An absent param needs no guard: it parses+ // to 0, and every id is >= 0.+ expect(store.getReport(Number.NaN).entries).toHaveLength(1);+ expect(store.getReport(0).entries).toHaveLength(1);+ });++ it("re-truncates oversized text, since the socket is just another local process", () => {+ const store = new DiagnosticsStore();+ const long = "x".repeat(DATA_APP_DIAGNOSTIC_MAX_CHARS + 100);++ store.applyMessage(message([entry({ summary: long, detail: long })]));++ const [only] = store.getReport(0).entries;+ expect(only.summary).toContain("truncated");+ expect(only.detail).toContain("truncated");+ });++ it("holds the last connection status reported, ignoring messages without one", () => {+ const store = new DiagnosticsStore();+ const connection = {+ checkedAt: 1,+ metabaseUrl: "http://localhost:3000",+ reachable: true,+ sdkVersion: "0.63.1",+ error: null,+ };++ store.applyMessage({ sessionId: "page-1", entries: [], connection });+ store.applyMessage(message([entry()]));++ expect(store.getReport(0).connection).toEqual(connection);+ });++ it("empties on clear, without rewinding the ids", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry(), entry()]));+ store.clear();+ store.applyMessage(message([entry({ summary: "after clear" })]));++ // Reusing an id a poller already consumed would hide the new entry.+ expect(store.getReport(0).entries).toEqual([+ expect.objectContaining({ eventId: 3, summary: "after clear" }),+ ]);+ });++ it("keeps the cursor moving forward while the buffer empties", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(message([entry(), entry()]));+ expect(store.getReport(0).nextEventId).toBe(3);++ store.clear();++ // Derived from the last retained entry it would fall back to 1 here, and a+ // poller that had already read up to 3 would re-read everything after.+ expect(store.getReport(0).entries).toEqual([]);+ expect(store.getReport(0).nextEventId).toBe(3);+ });++ it("does not let a flood of requests evict the errors that explain them", () => {+ const store = new DiagnosticsStore();++ store.applyMessage(+ message([entry({ summary: "the error worth keeping" })]),+ );+ store.applyMessage(+ message(+ Array.from({ length: DATA_APP_DIAGNOSTICS_LIMIT * 3 }, () =>+ entry({ kind: "sdk-call", summary: "GET /api/card/1 → 200" }),+ ),+ ),+ );++ const kept = store.getReport(0).entries;+ expect(kept[0].summary).toBe("the error worth keeping");+ expect(kept.filter((e) => e.kind === "sdk-call")).toHaveLength(+ DATA_APP_DIAGNOSTICS_CALL_LIMIT,+ );+ });++ describe("reporting whether anything changed", () => {+ const connection = {+ checkedAt: 1,+ metabaseUrl: "http://localhost:3000",+ reachable: true,+ sdkVersion: "0.63.1",+ error: null,+ };++ it("is true for new entries", () => {+ const store = new DiagnosticsStore();++ expect(store.applyMessage(message([entry()]))).toBe(true);+ });++ it("is true for a new session", () => {+ const store = new DiagnosticsStore();+ store.applyMessage(message([entry()], "page-1"));++ expect(store.applyMessage(message([], "page-2"))).toBe(true);+ });++ it("is true when the connection check has re-run", () => {+ const store = new DiagnosticsStore();+ store.applyMessage({ sessionId: "page-1", entries: [], connection });++ expect(+ store.applyMessage({+ sessionId: "page-1",+ entries: [],+ connection: { ...connection, checkedAt: 2 },+ }),+ ).toBe(true);+ });++ it("is false for a flush that carries nothing new", () => {+ const store = new DiagnosticsStore();+ store.applyMessage({+ sessionId: "page-1",+ entries: [entry()],+ connection,+ });++ // The reporter flushes on a timer whether or not anything happened, and+ // the connection arrives as a fresh object every time — comparing it by+ // reference would call every flush a change and undo the whole point of+ // pushing instead of polling.+ expect(+ store.applyMessage({+ sessionId: "page-1",+ entries: [],+ connection: { ...connection },+ }),+ ).toBe(false);+ });+ });++ it("starts empty rather than pretending a page has reported", () => {+ const store = new DiagnosticsStore();++ expect(store.getReport(0).entries).toEqual([]);+ expect(store.getReport(0).sessionId).toBeNull();+ expect(store.getReport(0).connection).toBeNull();+ expect(store.getReport(0).lastReportAt).toBeNull();+ expect(store.getReport(0).nextEventId).toBe(1);+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.tsnew file mode 100644index 00000000000..597b65d090e--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.ts@@ -0,0 +1,26 @@+import type { Connect } from "vite";++import { DATA_APP_BUNDLE_URL } from "../../constants/bundle";+import type { AppBundle } from "../app-bundle";++/** Serves the in-memory app bundle the sandbox fetches and evaluates. */+export const getAppBundleMiddleware =+ (bundle: AppBundle): Connect.NextHandleFunction =>+ (req, res, next) => {+ if (req.url?.split("?")[0] !== DATA_APP_BUNDLE_URL) {+ next();++ return;+ }++ if (!bundle.code) {+ res.statusCode = 503;+ res.setHeader("Content-Type", "text/plain");+ res.end("data-app bundle is not built — see the dev server logs.");++ return;+ }++ res.setHeader("Content-Type", "text/javascript");+ res.end(bundle.code);+ };diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.tsnew file mode 100644index 00000000000..4e2db975051--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.ts@@ -0,0 +1,70 @@+import type { Connect } from "vite";++import {+ DATA_APP_DIAGNOSTICS_URL,+ START_EVENT_ID_PARAM,+} from "../../constants/diagnostics-channel";+import type { DataAppDiagnosticsReport } from "../../types/diagnostics-channel";+import type { DataAppManifestStatus } from "../../types/manifest-status";+import type { DiagnosticsStore } from "../diagnostics-store";++export interface DiagnosticsEndpointMiddlewareOptions {+ store: DiagnosticsStore;+ getManifest: () => DataAppManifestStatus | null;+ getClients: () => number;+ getLastRebuildAt: () => number | null;+}++/**+ * Adds the `DATA_APP_DIAGNOSTICS_URL` endpoint to the dev server: `GET` returns+ * the feed as JSON (from `?startEventId=` onward), `DELETE` empties it.+ */+export const getDiagnosticsEndpointMiddleware =+ ({+ store,+ getManifest,+ getClients,+ getLastRebuildAt,+ }: DiagnosticsEndpointMiddlewareOptions): Connect.NextHandleFunction =>+ (req, res, next) => {+ const [pathname, query] = (req.url ?? "").split("?");++ if (pathname !== DATA_APP_DIAGNOSTICS_URL) {+ next();++ return;+ }++ // Clear diagnostics store on DELETE+ if (req.method === "DELETE") {+ store.clear();+ res.statusCode = 204;+ res.end();++ return;+ }++ if (req.method !== "GET") {+ res.statusCode = 405;+ res.setHeader("Allow", "GET, DELETE");+ res.end();++ return;+ }++ const startEventId = Number(+ new URLSearchParams(query).get(START_EVENT_ID_PARAM),+ );++ const report: DataAppDiagnosticsReport = {+ ...store.getReport(startEventId),+ manifest: getManifest(),+ clients: getClients(),+ lastRebuildAt: getLastRebuildAt(),+ };++ res.setHeader("Content-Type", "application/json");+ res.setHeader("Cache-Control", "no-store");++ res.end(JSON.stringify(report, null, 2));+ };diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/serve-index-html.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/index-html-middleware.tssimilarity index 90%rename from enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/serve-index-html.tsrename to enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/index-html-middleware.tsindex 2ef45e6e91e..17646835f19 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/serve-index-html.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/index-html-middleware.ts@@ -1,8 +1,8 @@import type { Connect, ViteDevServer } from "vite";-import { INDEX_HTML } from "../constants/index-html";+import { INDEX_HTML } from "../../constants/index-html";-export const serveIndexHtml =+export const getIndexHtmlMiddleware =(server: ViteDevServer): Connect.NextHandleFunction =>async (req, res, next) => {if (req.method !== "GET" || !req.headers.accept?.includes("text/html")) {diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.tsindex 532ad69a3a4..28f4b9ef69f 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts@@ -2,10 +2,20 @@ import path from "node:path";import type { Plugin } from "vite";+import { validateDataAppManifest } from "../config/validate-manifest";import { DATA_APP_REBUILT_EVENT } from "../constants/bundle";+import {+ DATA_APP_DIAGNOSTICS_CHANGED_EVENT,+ DATA_APP_DIAGNOSTICS_EVENT,+} from "../constants/diagnostics-channel";+import { DATA_APP_MANIFEST_FILE_NAME } from "../constants/paths";+import type { DataAppManifestStatus } from "../types/manifest-status";-import { createAppBundle, serveAppBundle } from "./app-bundle";-import { serveIndexHtml } from "./serve-index-html";+import { createAppBundle } from "./app-bundle";+import { DiagnosticsStore } from "./diagnostics-store";+import { getAppBundleMiddleware } from "./middlewares/app-bundle-middleware";+import { getDiagnosticsEndpointMiddleware } from "./middlewares/diagnostics-endpoint-middleware";+import { getIndexHtmlMiddleware } from "./middlewares/index-html-middleware";import {loadDataAppVirtualModule,resolveDataAppVirtualId,@@ -15,6 +25,9 @@ export function dataAppSandboxDevPlugin(appSlug: string,allowedHosts: string[],): Plugin {+ const diagnostics = new DiagnosticsStore();+ let manifestStatus: DataAppManifestStatus | null = null;+return {name: "metabase-data-app-dev",apply: "serve",@@ -32,19 +45,49 @@ export function dataAppSandboxDevPlugin(onError: (message) => server.config.logger.error(message),});- await bundle.rebuild();+ const refreshManifestStatus = () => {+ manifestStatus = validateDataAppManifest(root, allowedHosts);+ };- server.middlewares.use(serveAppBundle(bundle));+ refreshManifestStatus();++ server.middlewares.use(getAppBundleMiddleware(bundle));+ server.middlewares.use(+ getDiagnosticsEndpointMiddleware({+ store: diagnostics,+ getManifest: () => manifestStatus,+ getClients: () => server.ws.clients.size,+ getLastRebuildAt: () => bundle.lastRebuildAt,+ }),+ );++ server.ws.on(DATA_APP_DIAGNOSTICS_EVENT, (message) => {+ if (diagnostics.applyMessage(message)) {+ server.ws.send({+ type: "custom",+ event: DATA_APP_DIAGNOSTICS_CHANGED_EVENT,+ });+ }+ });const srcDir = `${path.sep}src${path.sep}`;- server.watcher.on("change", async (file) => {++ server.watcher.on("all", async (_event, file) => {+ if (path.basename(file) === DATA_APP_MANIFEST_FILE_NAME) {+ refreshManifestStatus();++ return;+ }+if (file.includes(srcDir) && (await bundle.rebuild())) {server.ws.send({ type: "custom", event: DATA_APP_REBUILT_EVENT });}});+ await bundle.rebuild();+return () => {- server.middlewares.use(serveIndexHtml(server));+ server.middlewares.use(getIndexHtmlMiddleware(server));};},};diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.tsindex d10da12fef6..abb0f6e827c 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts@@ -12,14 +12,15 @@ import {DATA_APP_BUNDLE_URL,DATA_APP_REBUILT_EVENT,} from "../constants/bundle";+import {+ DATA_APP_DIAGNOSTICS_CHANGED_EVENT,+ DATA_APP_DIAGNOSTICS_EVENT,+ DATA_APP_DIAGNOSTICS_URL,+} from "../constants/diagnostics-channel";import { dataAppSandboxDevPlugin } from "./plugin";jest.mock("vite", () => ({ build: jest.fn() }));-// Mock at the app's own config boundary rather than the individual Vite plugins-// it pulls in (`vite-plugin-css-injected-by-js`, `vite-plugin-svgr`): `build`-// is stubbed out anyway, so the plugin never uses these values — the test only-// needs `build-config` not to import those ESM-only packages at load time.jest.mock("../config/build-config", () => ({dataAppBuildPlugins: () => [],dataAppLibBuild: () => ({}),@@ -31,28 +32,138 @@ const mockedFs = jest.mocked(fs);const RESOLVED = (id: string) => `\0${id}`;-type FakeServer = {- config: {- root: string;- mode: string;- logger: { error: jest.Mock };- server: { headers: Record<string, string | null> };- };- ws: { send: jest.Mock };- middlewares: { use: jest.Mock };- watcher: { on: jest.Mock };- transformIndexHtml: jest.Mock;+type ConnectReq = {+ url?: string;+ method?: string;+ headers?: Record<string, string>;};+type ConnectRes = { statusCode: number; setHeader: jest.Mock; end: jest.Mock };+type ConnectHandler = (+ req: ConnectReq,+ res: ConnectRes,+ next: (err?: unknown) => void,+) => unknown;++type RequestResult = {+ res: ConnectRes;+ statusCode: number;+ fellThrough: boolean;+ nextError: unknown;+ body: any;+};++const DEV_CSP = "connect-src 'self'; form-action 'none'; frame-src 'none'";++const APP_SLUG = "test-app";++const isJson = (payload: unknown): payload is string =>+ typeof payload === "string" && /^\s*[[{]/.test(payload);++class FakeDevServer {+ private readonly middlewareStack: ConnectHandler[] = [];+ private readonly wsListeners = new Map<string, (message: unknown) => void>();+ private readonly watchListeners = new Map<+ string,+ ((...args: unknown[]) => unknown)[]+ >();++ readonly config = {+ root: "/app",+ mode: "development",+ logger: { error: jest.fn() },+ server: { headers: { "Content-Security-Policy": DEV_CSP } },+ };++ readonly ws = {+ on: jest.fn((event: string, handler: (message: unknown) => void) => {+ this.wsListeners.set(event, handler);+ }),+ send: jest.fn(),+ clients: new Set<unknown>(),+ emit: (event: string, message: unknown) =>+ this.wsListeners.get(event)?.(message),+ };++ readonly watcher = {+ on: jest.fn((event: string, handler: (...args: unknown[]) => unknown) => {+ this.watchListeners.set(event, [+ ...(this.watchListeners.get(event) ?? []),+ handler,+ ]);+ }),+ emit: async (event: string, ...args: unknown[]) => {+ for (const handler of this.watchListeners.get(event) ?? []) {+ await handler(...args);+ }+ },+ };++ readonly middlewares = {+ use: jest.fn((middleware: ConnectHandler) => {+ this.middlewareStack.push(middleware);+ }),+ };++ readonly transformIndexHtml = jest.fn(+ async (_url: string, html: string) => html,+ );++ async request(+ url: string,+ { method = "GET", headers = {} }: RequestOptions = {},+ ): Promise<RequestResult> {+ const req: ConnectReq = { url, method, headers };+ const res: ConnectRes = {+ statusCode: 0,+ setHeader: jest.fn(),+ end: jest.fn(),+ };++ let index = 0;+ let fellThrough = false;+ let nextError: unknown;++ const next = async (err?: unknown): Promise<void> => {+ if (err !== undefined) {+ nextError = err;+ return;+ }++ const middleware = this.middlewareStack[index++];+ if (!middleware) {+ fellThrough = true;+ return;+ }++ await middleware(req, res, next);+ };++ await next();++ const [payload] = res.end.mock.calls[0] ?? [];++ return {+ res,+ statusCode: res.statusCode,+ fellThrough,+ nextError,+ // The feed is JSON; other routes (the bundle, the HTML shell) are+ // asserted through `res.end` directly, so leave `body` null for them.+ body: isJson(payload) ? JSON.parse(payload) : null,+ };+ }+}++type RequestOptions = { method?: string; headers?: Record<string, string> };+type TestPlugin = {name: string;apply: string;resolveId: (id: string) => string | undefined;load: (id: string) => string | undefined;- configureServer: (server: FakeServer) => Promise<() => void>;+ configureServer: (server: FakeDevServer) => Promise<() => void>;};-const APP_SLUG = "test-app";-function makePlugin(appSlug: string, allowedHosts: string[] = []): TestPlugin {// Vite declares every hook on `Plugin` as an `ObjectHook` union (a function or// a `{ handler }` object) bound to Rollup's plugin context. The tests call the@@ -69,7 +180,6 @@ describe("dataAppSandboxDevPlugin", () => {it("only applies to the dev server", () => {const plugin = makePlugin(APP_SLUG);- expect(plugin.name).toBe("metabase-data-app-dev");expect(plugin.apply).toBe("serve");});@@ -128,23 +238,6 @@ describe("dataAppSandboxDevPlugin", () => {});describe("dev server wiring", () => {- const DEV_CSP = "connect-src 'self'; form-action 'none'; frame-src 'self'";-- function makeServer(): FakeServer {- return {- config: {- root: "/app",- mode: "development",- logger: { error: jest.fn() },- server: { headers: { "Content-Security-Policy": DEV_CSP } },- },- ws: { send: jest.fn() },- middlewares: { use: jest.fn() },- watcher: { on: jest.fn() },- transformIndexHtml: jest.fn(async (_url: string, html: string) => html),- };- }-async function setup(bundleCode = "BUNDLE_CODE") {// Rollup's `OutputChunk` declares ~20 required fields; the plugin only// reads `type` and `code`, so the stub deliberately omits the rest.@@ -152,7 +245,7 @@ describe("dataAppSandboxDevPlugin", () => {output: [{ type: "chunk", code: bundleCode }],} as unknown as Awaited<ReturnType<typeof build>>);- const server = makeServer();+ const server = new FakeDevServer();// `configureServer` returns a hook Vite runs after its own middlewares;// call it so the document (index.html) middleware is registered too.@@ -166,43 +259,30 @@ describe("dataAppSandboxDevPlugin", () => {it("builds the bundle on startup and serves it at the bundle URL", async () => {const { server } = await setup("BUNDLE_CODE");- expect(mockedBuild).toHaveBeenCalledTimes(1);-- const bundleMiddleware = server.middlewares.use.mock.calls[0][0];- const res = { statusCode: 0, setHeader: jest.fn(), end: jest.fn() };- const next = jest.fn();- bundleMiddleware({ url: DATA_APP_BUNDLE_URL }, res, next);+ const { res } = await server.request(DATA_APP_BUNDLE_URL);expect(res.setHeader).toHaveBeenCalledWith("Content-Type","text/javascript",);expect(res.end).toHaveBeenCalledWith("BUNDLE_CODE");- expect(next).not.toHaveBeenCalled();});it("passes non-bundle requests through to the next middleware", async () => {const { server } = await setup();- const bundleMiddleware = server.middlewares.use.mock.calls[0][0];- const next = jest.fn();- bundleMiddleware(- { url: "/some/asset.js" },- { setHeader: jest.fn(), end: jest.fn() },- next,- );-- expect(next).toHaveBeenCalledTimes(1);+ expect((await server.request("/some/asset.js")).fellThrough).toBe(true);});it("rebuilds and notifies the client when a src file changes", async () => {const { server } = await setup();expect(mockedBuild).toHaveBeenCalledTimes(1);- const [event, onChange] = server.watcher.on.mock.calls[0];- expect(event).toBe("change");-- await onChange(`/app${path.sep}src${path.sep}index.tsx`);+ await server.watcher.emit(+ "all",+ "change",+ path.join("/app", "src", "index.tsx"),+ );expect(mockedBuild).toHaveBeenCalledTimes(2);expect(server.ws.send).toHaveBeenCalledWith({@@ -211,32 +291,79 @@ describe("dataAppSandboxDevPlugin", () => {});});+ it("rebuilds when a src file is added or removed, not only edited", async () => {+ const { server } = await setup();++ await server.watcher.emit(+ "all",+ "add",+ path.join("/app", "src", "new.tsx"),+ );+ await server.watcher.emit(+ "all",+ "unlink",+ path.join("/app", "src", "old.tsx"),+ );++ expect(mockedBuild).toHaveBeenCalledTimes(3);+ });+it("ignores changes outside src/", async () => {const { server } = await setup();- const onChange = server.watcher.on.mock.calls[0][1];- await onChange("/app/README.md");+ await server.watcher.emit(+ "all",+ "change",+ path.join("/app", "README.md"),+ );expect(mockedBuild).toHaveBeenCalledTimes(1);expect(server.ws.send).not.toHaveBeenCalled();});- describe("synthetic index.html document", () => {- // Registered by the post-hook, so it's always the last one added.- const getDocumentMiddleware = (server: FakeServer) =>- server.middlewares.use.mock.calls.at(-1)[0];+ describe("manifest validation", () => {+ it("re-validates when data_app.yaml changes, and serves it on the feed", async () => {+ const { server } = await setup();+ mockedFs.existsSync.mockReturnValue(true);+ mockedFs.readFileSync.mockReturnValue(+ "name: Renamed\npath: dist/index.js\n",+ );- it("serves the transformed shell with the configured CSP for navigations", async () => {+ await server.watcher.emit(+ "all",+ "change",+ path.join("/app", "data_app.yaml"),+ );++ // The status is read from the feed, not pushed to the page — the page+ // used to echo it back, which raced and reported "not validated yet".+ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);++ expect(body.manifest).toMatchObject({ name: "Renamed" });+ });++ it("does not rebuild the bundle for a manifest change", async () => {const { server } = await setup();- const res = { statusCode: 0, setHeader: jest.fn(), end: jest.fn() };- const next = jest.fn();- await getDocumentMiddleware(server)(- { method: "GET", headers: { accept: "text/html" }, url: "/" },- res,- next,+ await server.watcher.emit(+ "all",+ "change",+ path.join("/app", "data_app.yaml"),);+ expect(mockedBuild).toHaveBeenCalledTimes(1);+ expect(server.ws.send).not.toHaveBeenCalled();+ });+ });++ describe("synthetic index.html document", () => {+ it("serves the transformed shell with the configured CSP for navigations", async () => {+ const { server } = await setup();++ const { res } = await server.request("/", {+ headers: { accept: "text/html" },+ });+// The shell HTML goes through Vite's transform (HMR client, etc.).expect(server.transformIndexHtml).toHaveBeenCalledWith("/",@@ -251,40 +378,159 @@ describe("dataAppSandboxDevPlugin", () => {expect(res.end).toHaveBeenCalledWith(expect.stringContaining("<!doctype html>"),);- expect(next).not.toHaveBeenCalled();});it("leaves non-HTML requests for the next middleware", async () => {const { server } = await setup();- const next = jest.fn();-- await getDocumentMiddleware(server)(- {- method: "GET",- headers: { accept: "application/javascript" },- url: "/some/asset.js",- },- { setHeader: jest.fn(), end: jest.fn() },- next,- );- expect(server.transformIndexHtml).not.toHaveBeenCalled();- expect(next).toHaveBeenCalledTimes(1);+ const { fellThrough } = await server.request("/some/asset.js", {+ headers: { accept: "application/javascript" },+ });++ expect(fellThrough).toBe(true);});it("forwards transformIndexHtml errors to the next middleware", async () => {const { server } = await setup();const error = new Error("transform failed");server.transformIndexHtml.mockRejectedValueOnce(error);- const next = jest.fn();- await getDocumentMiddleware(server)(- { method: "GET", headers: { accept: "text/html" }, url: "/" },- { statusCode: 0, setHeader: jest.fn(), end: jest.fn() },- next,+ const { nextError } = await server.request("/", {+ headers: { accept: "text/html" },+ });++ expect(nextError).toBe(error);+ });+ });++ describe("diagnostics feed", () => {+ const report = (+ server: FakeDevServer,+ entries: unknown[],+ sessionId?: string,+ ) =>+ server.ws.emit(DATA_APP_DIAGNOSTICS_EVENT, {+ sessionId,+ entries,+ connection: { reachable: true },+ });++ it("refuses a method it does not serve", async () => {+ const { server } = await setup();++ const { statusCode, res } = await server.request(+ DATA_APP_DIAGNOSTICS_URL,+ { method: "POST" },+ );++ expect(statusCode).toBe(405);+ expect(res.setHeader).toHaveBeenCalledWith("Allow", "GET, DELETE");+ });++ it("serves what the page reported, and passes other URLs through", async () => {+ const { server } = await setup();++ report(server, [+ { id: 1, kind: "error", summary: "boom", alert: true },+ { id: 2, kind: "sdk-call", summary: "POST /api/dataset → 400" },+ ]);++ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);+ expect(+ body.entries.map((entry: { eventId: number }) => entry.eventId),+ ).toEqual([1, 2]);+ expect(body.connection).toEqual({ reachable: true });+ expect(body.nextEventId).toBe(3);++ expect((await server.request("/something-else")).fellThrough).toBe(+ true,+ );+ });++ it("carries the manifest before any client has reported", async () => {+ // Regression: the manifest used to round-trip through the page, so the+ // feed said "not validated yet" whenever that echo hadn't happened.+ const { server } = await setup();++ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);++ expect(body.manifest).toEqual(+ expect.objectContaining({ errors: expect.any(Array) }),+ );+ });++ it("keeps the manifest even when the page reports without one", async () => {+ const { server } = await setup();+ report(server, [{ eventId: 1, summary: "boom" }]);++ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);++ expect(body.manifest).not.toBeNull();+ });++ it("returns only events from `startEventId` onward", async () => {+ const { server } = await setup();+ report(server, [+ { id: 1, summary: "old" },+ { id: 2, summary: "new" },+ ]);++ const { body } = await server.request(+ `${DATA_APP_DIAGNOSTICS_URL}?startEventId=2`,);- expect(next).toHaveBeenCalledWith(error);+ expect(body.entries).toHaveLength(1);+ expect(body.entries[0].summary).toBe("new");+ });++ it("reports connected clients, so an empty feed isn't read as healthy", async () => {+ const { server } = await setup();++ expect(+ (await server.request(DATA_APP_DIAGNOSTICS_URL)).body,+ ).toMatchObject({+ entries: [],+ clients: 0,+ lastReportAt: null,+ });++ server.ws.clients.add({});+ report(server, []);++ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);+ expect(body.clients).toBe(1);+ expect(body.lastReportAt).toEqual(expect.any(Number));+ });++ const changeNudges = (server: FakeDevServer) =>+ server.ws.send.mock.calls.filter(+ ([message]) => message?.event === DATA_APP_DIAGNOSTICS_CHANGED_EVENT,+ ).length;++ it("nudges readers when a report brings something new", async () => {+ const { server } = await setup();++ report(server, [{ summary: "boom" }], "page-1");++ // The nudge carries no payload: readers re-read the endpoint, so the+ // toolbar and a shell agent still see the same bytes.+ expect(changeNudges(server)).toBe(1);+ expect(server.ws.send).toHaveBeenCalledWith({+ type: "custom",+ event: DATA_APP_DIAGNOSTICS_CHANGED_EVENT,+ });+ });++ it("stays quiet when a report brings nothing new", async () => {+ const { server } = await setup();++ report(server, [{ summary: "boom" }], "page-1");+ report(server, [], "page-1");+ report(server, [], "page-1");++ // The reporter flushes on a timer whether or not anything happened.+ // Nudging on those would rebuild the poll loop from the other side.+ expect(changeNudges(server)).toBe(1);});});});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.tsindex 90b6b207756..ceb6209de4e 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts@@ -1,4 +1,6 @@import fs from "node:fs";+import { createRequire } from "node:module";+import path from "node:path";import { fileURLToPath } from "node:url";// A namespace import stays single-line so the disable covers the reported line.@@ -9,7 +11,12 @@ import {DATA_APP_BUNDLE_URL,DATA_APP_REBUILT_EVENT,} from "../constants/bundle";-import { DATA_APP_DEV_ENTRY_FILE_NAME } from "../constants/paths";+import { DATA_APP_DIAGNOSTICS_CHANGED_EVENT } from "../constants/diagnostics-channel";+import {+ DATA_APP_DEV_ENTRY_FILE_NAME,+ PACKAGE_JSON_FILE_NAME,+ SDK_PACKAGE_NAME,+} from "../constants/paths";const { DATA_APP_DEV_CONFIG_VIRTUAL_ID, DATA_APP_DEV_ENTRY_VIRTUAL_ID } =dataAppVirtualModules;@@ -21,6 +28,26 @@ const DEV_ENTRY_SOURCE_PATH = fileURLToPath(new URL(DATA_APP_DEV_ENTRY_FILE_NAME, import.meta.url),);+const readInstalledSdkVersion = (appRoot: string): string | null => {+ try {+ const requireFromApp = createRequire(+ path.join(appRoot, PACKAGE_JSON_FILE_NAME),+ );+ const pkg: unknown = requireFromApp(+ `${SDK_PACKAGE_NAME}/${PACKAGE_JSON_FILE_NAME}`,+ );++ return typeof pkg === "object" &&+ pkg !== null &&+ "version" in pkg &&+ typeof pkg.version === "string"+ ? pkg.version+ : null;+ } catch {+ return null;+ }+};+export const resolveDataAppVirtualId = (id: string): string | undefined =>id === DATA_APP_DEV_ENTRY_VIRTUAL_ID || id === DATA_APP_DEV_CONFIG_VIRTUAL_ID? RESOLVED_PREFIX + id@@ -45,6 +72,8 @@ export const loadDataAppVirtualModule = (`export const appSlug = ${JSON.stringify(appSlug)};`,`export const bundleUrl = ${JSON.stringify(DATA_APP_BUNDLE_URL)};`,`export const rebuiltEvent = ${JSON.stringify(DATA_APP_REBUILT_EVENT)};`,+ `export const diagnosticsChangedEvent = ${JSON.stringify(DATA_APP_DIAGNOSTICS_CHANGED_EVENT)};`,+ `export const sdkVersion = ${JSON.stringify(readInstalledSdkVersion(process.cwd()))};`,].join("\n");}};diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-limits.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-limits.tsnew file mode 100644index 00000000000..b959462f4fd--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-limits.ts@@ -0,0 +1,37 @@+import {+ DATA_APP_DIAGNOSTICS_CALL_LIMIT,+ DATA_APP_DIAGNOSTICS_LIMIT,+ DATA_APP_DIAGNOSTIC_MAX_CHARS,+} from "../constants/diagnostics-channel";++/**+ * Trim to `DATA_APP_DIAGNOSTICS_LIMIT`, dropping requests first and never+ * letting them hold more than their own budget. Whatever they leave unused goes+ * to the other kinds, so a quiet app still keeps a full buffer of errors.+ * Insertion order is preserved.+ */+export const trimDiagnosticEntries = <T extends { kind: string }>(+ entries: T[],+): T[] => {+ if (entries.length <= DATA_APP_DIAGNOSTICS_LIMIT) {+ return entries;+ }++ const calls = entries+ .filter((entry) => entry.kind === "sdk-call")+ .slice(-DATA_APP_DIAGNOSTICS_CALL_LIMIT);+ const rest = entries+ .filter((entry) => entry.kind !== "sdk-call")+ .slice(-(DATA_APP_DIAGNOSTICS_LIMIT - calls.length));+ const kept = new Set<T>([...calls, ...rest]);++ return entries.filter((entry) => kept.has(entry));+};++export const truncateDiagnosticText = (+ value: string,+ max: number = DATA_APP_DIAGNOSTIC_MAX_CHARS,+): string =>+ value.length <= max+ ? value+ : `${value.slice(0, max)}… (truncated, ${value.length} chars)`;diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-limits.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-limits.unit.spec.tsnew file mode 100644index 00000000000..a9a8c20ff54--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-limits.unit.spec.ts@@ -0,0 +1,123 @@+import {+ DATA_APP_DIAGNOSTICS_CALL_LIMIT,+ DATA_APP_DIAGNOSTICS_LIMIT,+ DATA_APP_DIAGNOSTIC_MAX_CHARS,+} from "../constants/diagnostics-channel";++import {+ trimDiagnosticEntries,+ truncateDiagnosticText,+} from "./diagnostics-limits";++const call = (id: number) => ({ kind: "sdk-call", id });+const error = (id: number) => ({ kind: "error", id });+const many = (+ count: number,+ make: (id: number) => { kind: string; id: number },+) => Array.from({ length: count }, (_, index) => make(index + 1));++const kindsOf = (entries: { kind: string }[]) => ({+ calls: entries.filter((entry) => entry.kind === "sdk-call").length,+ rest: entries.filter((entry) => entry.kind !== "sdk-call").length,+});++describe("trimDiagnosticEntries", () => {+ it("returns the very same array while under the limit", () => {+ const entries = many(DATA_APP_DIAGNOSTICS_LIMIT, call);++ expect(trimDiagnosticEntries(entries)).toBe(entries);+ });++ it("leaves a buffer sitting exactly on the limit alone", () => {+ const entries = many(DATA_APP_DIAGNOSTICS_LIMIT, call);++ expect(trimDiagnosticEntries(entries)).toHaveLength(+ DATA_APP_DIAGNOSTICS_LIMIT,+ );+ });++ it("gives the whole buffer to other kinds when there are no requests", () => {+ const trimmed = trimDiagnosticEntries(+ many(DATA_APP_DIAGNOSTICS_LIMIT + 5, error),+ );++ expect(trimmed).toHaveLength(DATA_APP_DIAGNOSTICS_LIMIT);+ });++ it("holds requests to their own budget however loud they get", () => {+ const trimmed = trimDiagnosticEntries([+ error(1),+ ...many(DATA_APP_DIAGNOSTICS_LIMIT * 5, call),+ ]);++ expect(kindsOf(trimmed)).toEqual({+ calls: DATA_APP_DIAGNOSTICS_CALL_LIMIT,+ rest: 1,+ });+ });++ it("keeps the newest of each kind and drops the oldest", () => {+ const calls = many(DATA_APP_DIAGNOSTICS_LIMIT + 10, call);+ const trimmed = trimDiagnosticEntries([error(0), ...calls]);++ const keptCalls = trimmed.filter((entry) => entry.kind === "sdk-call");+ expect(keptCalls.at(-1)).toEqual(calls.at(-1));+ expect(keptCalls[0].id).toBe(+ calls.length - DATA_APP_DIAGNOSTICS_CALL_LIMIT + 1,+ );+ });++ it("preserves insertion order across kinds", () => {+ const interleaved = Array.from(+ { length: DATA_APP_DIAGNOSTICS_LIMIT + 20 },+ (_, index) => (index % 2 === 0 ? call(index) : error(index)),+ );++ const ids = trimDiagnosticEntries(interleaved).map((entry) => entry.id);++ // A poller reads this in order; re-sorting would make ids jump backwards.+ expect(ids).toEqual([...ids].sort((a, b) => a - b));+ });++ it("can total less than the limit, trading spare room for a bounded request log", () => {+ const trimmed = trimDiagnosticEntries([+ error(1),+ ...many(DATA_APP_DIAGNOSTICS_LIMIT * 2, call),+ ]);++ expect(trimmed.length).toBeLessThan(DATA_APP_DIAGNOSTICS_LIMIT);+ });+});++describe("truncateDiagnosticText", () => {+ it("leaves text within the limit untouched", () => {+ expect(truncateDiagnosticText("short")).toBe("short");+ expect(truncateDiagnosticText("")).toBe("");+ });++ it("leaves text sitting exactly on the limit untouched", () => {+ const exact = "x".repeat(DATA_APP_DIAGNOSTIC_MAX_CHARS);++ expect(truncateDiagnosticText(exact)).toBe(exact);+ });++ it("truncates one character past the limit, reporting the original length", () => {+ const over = "x".repeat(DATA_APP_DIAGNOSTIC_MAX_CHARS + 1);++ expect(truncateDiagnosticText(over)).toBe(+ `${"x".repeat(DATA_APP_DIAGNOSTIC_MAX_CHARS)}… (truncated, ${over.length} chars)`,+ );+ });++ it("honours a caller's own limit", () => {+ expect(truncateDiagnosticText("abcdef", 3)).toBe(+ "abc… (truncated, 6 chars)",+ );+ });++ it("is not idempotent, so callers must truncate once", () => {+ const once = truncateDiagnosticText("abcdef", 3);++ expect(truncateDiagnosticText(once, 3)).not.toBe(once);+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.tsnew file mode 100644index 00000000000..4ce86e2ed3b--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.ts@@ -0,0 +1,118 @@+import { match } from "ts-pattern";++import type { DevDiagnosticEntry } from "../types/diagnostics";+import type { DataAppDiagnosticEntry } from "../types/diagnostics-channel";++import { truncateDiagnosticText } from "./diagnostics-limits";++const isFailedSdkCall = (entry: DevDiagnosticEntry): boolean =>+ entry.kind === "sdk-call" &&+ (entry.error != null || (entry.status != null && entry.status >= 400));++export const isAlert = (entry: DevDiagnosticEntry): boolean =>+ entry.kind === "error" ||+ entry.kind === "blocked-api" ||+ entry.kind === "blocked-network" ||+ entry.kind === "csp-violation" ||+ isFailedSdkCall(entry);++export const formatDevDiagnostic = (entry: DevDiagnosticEntry): string =>+ // `.exhaustive()` makes a new `DevDiagnosticEvent` kind a compile error here+ // until it has a branch, rather than silently formatting as `[object Object]`.+ match(entry)+ .with({ kind: "error" }, { kind: "blocked-api" }, (entry) => entry.message)+ .with(+ { kind: "blocked-network" },+ (entry) =>+ `Blocked ${entry.api === "xhr" ? "XMLHttpRequest" : "fetch"} to ${entry.reason}`,+ )+ .with(+ { kind: "csp-violation" },+ (entry) =>+ `Content Security Policy (${entry.directive}) blocked ${entry.blockedUri || "inline content"}`,+ )+ .with({ kind: "sdk-call" }, (entry) => {+ // The reason goes on its own line so `toSummaryAndDetail` files it as the+ // collapsible detail instead of burying the endpoint behind it.+ const summary = `${entry.method} ${entry.endpoint} → ${entry.status ?? "failed"} (${entry.durationMs}ms)`;++ return entry.error ? `${summary}\n${entry.error}` : summary;+ })+ .exhaustive();++const CSP_DIRECTIVE_HINTS: Record<string, string> = {+ "connect-src":+ "Your app tried to call a URL it isn't allowed to reach. Add that URL's origin to allowed_hosts in data_app.yaml, then restart the dev server.",+ "form-action":+ "A form tried to submit to a URL the app isn't allowed to reach. Add that origin to allowed_hosts in data_app.yaml, or submit with fetch instead.",+ "frame-src":+ "Your app tried to embed another site in an iframe. Add that site's origin to allowed_hosts in data_app.yaml.",+ "script-src":+ "Your app tried to load a script from another site. Install the dependency and import it so it's bundled, instead of loading it from a CDN.",+ "style-src":+ "Your app tried to load a stylesheet from another site. Import the CSS so it's bundled instead.",+ "img-src":+ "Your app tried to load an image from a site it isn't allowed to reach. Add that origin to allowed_hosts in data_app.yaml, or bundle the image.",+ "font-src":+ "Your app tried to load a font from another site. Add that origin to allowed_hosts in data_app.yaml, or bundle the font.",+};++const CSP_FALLBACK_HINT =+ "Instance restricts what a data app may load or contact, and the dev server applies the same rules. Anything the app needs to reach must be listed under allowed_hosts in data_app.yaml.";++const getDevDiagnosticHint = (entry: DevDiagnosticEntry): string | null => {+ if (+ entry.kind === "blocked-network" &&+ entry.reason.includes("not in allowed_hosts")+ ) {+ try {+ return `Add ${new URL(entry.url).origin} to allowed_hosts in data_app.yaml (dev server restart required).`;+ } catch {+ return null;+ }+ }++ if (entry.kind === "csp-violation") {+ return CSP_DIRECTIVE_HINTS[entry.directive] ?? CSP_FALLBACK_HINT;+ }++ return null;+};++/**+ * Splits the formatted text at its first line break: readers show the summary in+ * a list and expand the detail on demand — a stack, or a failed call's response.+ */+const toSummaryAndDetail = (+ entry: DevDiagnosticEntry,+): { summary: string; detail: string | null } => {+ const text = formatDevDiagnostic(entry);+ const firstBreak = text.indexOf("\n");++ return firstBreak === -1+ ? { summary: text, detail: null }+ : {+ summary: text.slice(0, firstBreak),+ detail: text.slice(firstBreak + 1).replace(/\n+$/, ""),+ };+};++/**+ * No `eventId` — the dev server assigns it. `summary`/`detail` are re-truncated:+ * a `console.error` with many args can exceed the per-arg bound applied at+ * capture.+ */+export const toPayload = (+ entry: DevDiagnosticEntry,+): DataAppDiagnosticEntry => {+ const { summary, detail } = toSummaryAndDetail(entry);++ return {+ time: entry.time,+ kind: entry.kind,+ summary: truncateDiagnosticText(summary),+ detail: detail === null ? null : truncateDiagnosticText(detail),+ hint: getDevDiagnosticHint(entry),+ alert: isAlert(entry),+ };+};diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.tsnew file mode 100644index 00000000000..62fd2d27e6b--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.ts@@ -0,0 +1,83 @@+import { DATA_APP_DIAGNOSTIC_MAX_CHARS } from "../constants/diagnostics-channel";+import type {+ DevDiagnosticEntry,+ DevDiagnosticEvent,+} from "../types/diagnostics";++import { truncateDiagnosticText } from "./diagnostics-limits";+import { toPayload } from "./diagnostics-payload";++const entry = (event: DevDiagnosticEvent): DevDiagnosticEntry => ({+ id: 1,+ time: 1700000000000,+ ...event,+});++const sdkCall = (+ overrides: Partial<Extract<DevDiagnosticEvent, { kind: "sdk-call" }>> = {},+) =>+ entry({+ kind: "sdk-call",+ method: "POST",+ endpoint: "/api/dataset",+ status: 200,+ durationMs: 12,+ ...overrides,+ });++describe("toPayload for requests", () => {+ it("keeps a successful call off the alert path", () => {+ expect(toPayload(sdkCall())).toMatchObject({+ kind: "sdk-call",+ summary: "POST /api/dataset → 200 (12ms)",+ detail: null,+ alert: false,+ });+ });++ it("files the failure reason as the detail, leaving the endpoint in the summary", () => {+ const payload = toPayload(+ sdkCall({ status: 400, error: 'Table "orders" is not in the manifest' }),+ );++ // The toolbar collapses `detail` and the agent feed carries it as its own+ // field, so the reason must not be folded into the summary line.+ expect(payload.summary).toBe("POST /api/dataset → 400 (12ms)");+ expect(payload.detail).toBe('Table "orders" is not in the manifest');+ expect(payload.alert).toBe(true);+ });++ it("flags a transport failure, which never gets a status", () => {+ const payload = toPayload(+ sdkCall({ status: null, error: "Failed to fetch" }),+ );++ expect(payload.summary).toBe("POST /api/dataset → failed (12ms)");+ expect(payload.detail).toBe("Failed to fetch");+ expect(payload.alert).toBe(true);+ });++ it.each([+ [200, false],+ [304, false],+ // 4xx is the boundary the Queries filter and the toggle badge both key on.+ [308, false],+ [400, true],+ [404, true],+ [500, true],+ ])("treats status %i as an alert: %s", (status, alert) => {+ expect(toPayload(sdkCall({ status })).alert).toBe(alert);+ });++ it("re-truncates a reason that outgrew the per-field bound", () => {+ const reason = "x".repeat(DATA_APP_DIAGNOSTIC_MAX_CHARS + 100);++ expect(toPayload(sdkCall({ status: 400, error: reason })).detail).toBe(+ truncateDiagnosticText(reason),+ );+ });++ it("offers no hint for a request — the reason is already the answer", () => {+ expect(toPayload(sdkCall({ status: 400, error: "boom" })).hint).toBeNull();+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-reporter.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-reporter.tsnew file mode 100644index 00000000000..08a9488a1ca--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-reporter.ts@@ -0,0 +1,74 @@+import { devDiagnostics } from "../components/DevToolbar/diagnostics";+import { DATA_APP_DIAGNOSTICS_EVENT } from "../constants/diagnostics-channel";+import { DIAGNOSTICS_FLUSH_MS } from "../constants/timings";+import type { DataAppDiagnosticsMessage } from "../types/diagnostics-channel";++import { toPayload } from "./diagnostics-payload";++export interface DiagnosticsReporterHot {+ send: (event: string, data: DataAppDiagnosticsMessage) => void;+}++const getNextSessionId = (): string => {+ if (typeof globalThis.crypto?.getRandomValues !== "function") {+ throw new Error(+ "The data-app dev preview needs Web Crypto to identify a session.",+ );+ }++ const random = globalThis.crypto.getRandomValues(new Uint8Array(8));+ const suffix = Array.from(random, (byte) =>+ byte.toString(16).padStart(2, "0"),+ ).join("");++ return `${Date.now()}-${suffix}`;+};++/**+ * Mirrors the page's collector to the dev server over the HMR socket, so the+ * feed shows what the preview captured. Sends once on install to announce the+ * page, then a coalesced batch of whatever is new.+ */+export const installDiagnosticsReporter = (+ hot: DiagnosticsReporterHot,+): (() => void) => {+ const sessionId = getNextSessionId();++ let lastSentId = 0;+ let timer: ReturnType<typeof setTimeout> | null = null;++ const flush = () => {+ timer = null;++ const fresh = devDiagnostics+ .getEntries()+ .filter((entry) => entry.id > lastSentId);++ if (fresh.length > 0) {+ lastSentId = fresh[fresh.length - 1].id;+ }++ hot.send(DATA_APP_DIAGNOSTICS_EVENT, {+ sessionId,+ entries: fresh.map(toPayload),+ connection: devDiagnostics.getConnectionStatus(),+ });+ };++ const schedule = () => {+ timer ??= setTimeout(flush, DIAGNOSTICS_FLUSH_MS);+ };++ flush();++ const unsubscribe = devDiagnostics.subscribe(schedule);++ return () => {+ unsubscribe();++ if (timer) {+ clearTimeout(timer);+ timer = null;+ }+ };+};diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-reporter.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-reporter.unit.spec.tsnew file mode 100644index 00000000000..ac7f6fbabb8--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-reporter.unit.spec.ts@@ -0,0 +1,186 @@+import { devDiagnostics } from "../components/DevToolbar/diagnostics";+import { DATA_APP_DIAGNOSTICS_EVENT } from "../constants/diagnostics-channel";+import type { DataAppDiagnosticsMessage } from "../types/diagnostics-channel";++import { installDiagnosticsReporter } from "./diagnostics-reporter";++const setup = () => {+ const sent: DataAppDiagnosticsMessage[] = [];+ const cleanup = installDiagnosticsReporter({+ send: (_event, data) => {+ sent.push(data);+ },+ });+ return { sent, cleanup };+};++beforeEach(() => {+ jest.useFakeTimers();+ devDiagnostics.clear();+});++afterEach(() => {+ jest.useRealTimers();+});++describe("installDiagnosticsReporter", () => {+ it("reports immediately on install, so the server knows a client is alive", () => {+ const { sent, cleanup } = setup();++ expect(sent).toHaveLength(1);+ expect(sent[0].entries).toEqual([]);++ cleanup();+ });++ it("sends the toolbar's summary, detail and hint rather than raw fields", () => {+ const { sent, cleanup } = setup();++ devDiagnostics.record({+ kind: "csp-violation",+ directive: "connect-src",+ blockedUri: "https://api.example.com/v1",+ });+ jest.runOnlyPendingTimers();++ const [entry] = sent[sent.length - 1].entries;+ expect(entry.kind).toBe("csp-violation");+ expect(entry.alert).toBe(true);+ expect(entry.hint).toMatch(/allowed_hosts in data_app.yaml/);++ cleanup();+ });++ it("carries the allowed_hosts hint for a blocked request", () => {+ const { sent, cleanup } = setup();++ devDiagnostics.record({+ kind: "blocked-network",+ api: "fetch",+ url: "https://api.example.com/v1/data",+ reason: "api.example.com (not in allowed_hosts)",+ });+ jest.runOnlyPendingTimers();++ const [entry] = sent[sent.length - 1].entries;+ expect(entry.hint).toBe(+ "Add https://api.example.com to allowed_hosts in data_app.yaml (dev server restart required).",+ );++ cleanup();+ });++ it("splits a stack into summary and detail", () => {+ const { sent, cleanup } = setup();++ devDiagnostics.record({+ kind: "error",+ message: "TypeError: nope\n at App (src/App.tsx:1:1)",+ });+ jest.runOnlyPendingTimers();++ const [entry] = sent[sent.length - 1].entries;+ expect(entry.summary).toBe("TypeError: nope");+ expect(entry.detail).toBe(" at App (src/App.tsx:1:1)");++ cleanup();+ });++ it("marks a failed SDK call as an alert but not a successful one", () => {+ const { sent, cleanup } = setup();++ devDiagnostics.record({+ kind: "sdk-call",+ method: "POST",+ endpoint: "/api/dataset",+ status: 500,+ durationMs: 3,+ });+ devDiagnostics.record({+ kind: "sdk-call",+ method: "GET",+ endpoint: "/api/card/1",+ status: 200,+ durationMs: 3,+ });+ jest.runOnlyPendingTimers();++ const { entries } = sent[sent.length - 1];+ expect(entries.map((entry) => entry.alert)).toEqual([true, false]);++ cleanup();+ });++ it("batches a burst into one message and never re-sends an entry", () => {+ const { sent, cleanup } = setup();++ devDiagnostics.record({ kind: "error", message: "one" });+ devDiagnostics.record({ kind: "error", message: "two" });+ jest.runOnlyPendingTimers();++ expect(sent).toHaveLength(2);+ expect(sent[1].entries.map((entry) => entry.summary)).toEqual([+ "one",+ "two",+ ]);++ devDiagnostics.record({ kind: "error", message: "three" });+ jest.runOnlyPendingTimers();++ expect(sent[2].entries.map((entry) => entry.summary)).toEqual(["three"]);++ cleanup();+ });++ it("does not resend earlier entries after the toolbar's Clear", () => {+ const { sent, cleanup } = setup();++ devDiagnostics.record({ kind: "error", message: "before clear" });+ jest.runOnlyPendingTimers();++ devDiagnostics.clear();+ devDiagnostics.record({ kind: "error", message: "after clear" });+ jest.runOnlyPendingTimers();++ const summaries = sent.at(-1)?.entries.map((entry) => entry.summary);+ expect(summaries).toEqual(["after clear"]);++ cleanup();+ });++ it("stops sending once torn down", () => {+ const { sent, cleanup } = setup();+ cleanup();++ devDiagnostics.record({ kind: "error", message: "ignored" });+ jest.runOnlyPendingTimers();++ expect(sent).toHaveLength(1);+ });++ it("tags every message with a stable per-install sessionId", () => {+ const { sent, cleanup } = setup();+ devDiagnostics.record({ kind: "error", message: "one" });+ jest.runOnlyPendingTimers();++ expect(typeof sent[0].sessionId).toBe("string");+ expect(sent[0].sessionId).not.toBe("");+ // Same page load → same sessionId on every message.+ expect(sent[sent.length - 1].sessionId).toBe(sent[0].sessionId);++ cleanup();+ });++ it("uses the agreed channel event name", () => {+ const events: string[] = [];+ const cleanup = installDiagnosticsReporter({+ send: (event) => {+ events.push(event);+ },+ });++ expect(events).toEqual([DATA_APP_DIAGNOSTICS_EVENT]);++ cleanup();+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/instance-connection-check.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/instance-connection-check.tsnew file mode 100644index 00000000000..aa37d7636f3--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/instance-connection-check.ts@@ -0,0 +1,58 @@+import { devDiagnostics } from "../components/DevToolbar/diagnostics";+import { DATA_APP_MB_URL_ENV } from "../constants/env";+import type { InstanceConnectionStatus } from "../types/diagnostics-channel";++export interface InstanceConnectionCheckOptions {+ metabaseUrl: string | undefined;+ sdkVersion: string | null;+}++/**+ * Answers one question — is the instance URL reachable — and nothing else.+ */+export class InstanceConnectionCheck {+ async install({+ metabaseUrl,+ sdkVersion,+ }: InstanceConnectionCheckOptions): Promise<void> {+ const base = (metabaseUrl ?? "").replace(/\/+$/, "");+ const status: InstanceConnectionStatus = {+ checkedAt: Date.now(),+ metabaseUrl: base,+ reachable: false,+ sdkVersion,+ error: null,+ };++ if (!base) {+ status.error = `${DATA_APP_MB_URL_ENV} is not set — fill it in the repo-root .env.local and restart the dev server.`;+ devDiagnostics.setConnectionStatus(status);++ return;+ }++ // Without a scheme the browser resolves it against the preview origin, so+ // the dev server would answer and the instance would look reachable.+ if (!URL.canParse(base)) {+ status.error = `${DATA_APP_MB_URL_ENV} must be an absolute URL like http://localhost:3000, not "${base}".`;+ devDiagnostics.setConnectionStatus(status);++ return;+ }++ try {+ await window.fetch(base, { mode: "no-cors" });+ status.reachable = true;+ } catch (error) {+ status.error = `Could not reach ${status.metabaseUrl}: ${this.describeFailure(error)}`;+ }++ devDiagnostics.setConnectionStatus(status);+ }++ private describeFailure(error: unknown): string {+ return error instanceof Error ? error.message : String(error);+ }+}++export const instanceConnectionCheck = new InstanceConnectionCheck();diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/instance-connection-check.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/instance-connection-check.unit.spec.tsnew file mode 100644index 00000000000..7a637d97709--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/instance-connection-check.unit.spec.ts@@ -0,0 +1,90 @@+import { devDiagnostics } from "../components/DevToolbar/diagnostics";++import { instanceConnectionCheck } from "./instance-connection-check";++const METABASE_URL = "http://localhost:3000";++const run = (fetchFn: jest.Mock, metabaseUrl: string | undefined) => {+ window.fetch = fetchFn;++ return instanceConnectionCheck.install({ metabaseUrl, sdkVersion: "0.64.0" });+};++const realFetch = window.fetch;++beforeEach(() => devDiagnostics.clear());+afterEach(() => {+ window.fetch = realFetch;+});++describe("InstanceConnectionCheck", () => {+ it("reports the instance reachable when the ping resolves", async () => {+ await run(+ jest.fn(async () => new Response(null, { status: 200 })),+ METABASE_URL,+ );++ expect(devDiagnostics.getConnectionStatus()).toMatchObject({+ metabaseUrl: METABASE_URL,+ reachable: true,+ sdkVersion: "0.64.0",+ });+ expect(devDiagnostics.getConnectionStatus()?.error).toBeNull();+ });++ it("pings the instance URL itself and calls no API", async () => {+ const fetchFn = jest.fn(async () => new Response(null, { status: 200 }));++ await run(fetchFn, METABASE_URL);++ // Every endpoint this used to call was a contract with a Metabase the+ // package does not ship with. The author pins the package while the+ // instance moves on, so a renamed route would report a healthy instance as+ // broken — or a broken one as healthy.+ expect(fetchFn).toHaveBeenCalledTimes(1);+ expect(fetchFn).toHaveBeenCalledWith(METABASE_URL, { mode: "no-cors" });+ });++ it("reports unreachable when the ping rejects", async () => {+ await run(+ jest.fn(async () => {+ throw new TypeError("Failed to fetch");+ }),+ METABASE_URL,+ );++ expect(devDiagnostics.getConnectionStatus()).toMatchObject({+ reachable: false,+ });+ expect(devDiagnostics.getConnectionStatus()?.error).toContain(+ "Failed to fetch",+ );+ });++ it("reports an unset URL without probing anything", async () => {+ const fetchFn = jest.fn();++ await run(fetchFn, undefined);++ expect(fetchFn).not.toHaveBeenCalled();+ expect(devDiagnostics.getConnectionStatus()?.error).toContain(+ "DATA_APP_MB_URL is not set",+ );+ });++ it("rejects a URL without a scheme instead of probing the preview origin", async () => {+ const fetchFn = jest.fn();++ // The browser would resolve it against the dev server, which answers — and+ // the instance would be reported reachable when nothing had been reached.+ await run(fetchFn, "metabase.local");++ expect(fetchFn).not.toHaveBeenCalled();+ expect(devDiagnostics.getConnectionStatus()).toMatchObject({+ reachable: false,+ });+ expect(devDiagnostics.getConnectionStatus()?.error).toContain(+ "must be an absolute URL",+ );+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/sdk-call-capture.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/sdk-call-capture.tsnew file mode 100644index 00000000000..689bd79fdee--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/sdk-call-capture.ts@@ -0,0 +1,179 @@+import { devDiagnostics } from "../components/DevToolbar/diagnostics";+import { MAX_INSPECTED_BODY_CHARS } from "../constants/diagnostics-channel";++/**+ * Records every request the preview makes to the instance — method, endpoint,+ * status, duration, and the reason on a failure.+ *+ * Patching `window.fetch` keeps the capture inside the dev preview: hooking the+ * SDK's own client would put it within reach of any page embedding the SDK.+ */+export class SdkCallCapture {+ install(metabaseUrl: string | undefined): void {+ if (!metabaseUrl) {+ return;+ }++ let metabaseOrigin: string;+ let basePath: string;+ try {+ const parsed = new URL(metabaseUrl);+ metabaseOrigin = parsed.origin;+ // A sub-path deployment prefixes every path; strip it.+ basePath = parsed.pathname.replace(/\/+$/, "");+ } catch {+ return;+ }++ const originalFetch = window.fetch;++ // Patching is the easiest option that works for now, and `fetch` alone is+ // enough - Metabase no longer makes XHR calls.+ window.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {+ const url = this.resolveUrl(input);++ if (+ url?.origin !== metabaseOrigin ||+ (basePath && !url.pathname.startsWith(basePath))+ ) {+ return originalFetch(input, init);+ }++ const method = this.resolveMethod(input, init);+ const endpoint = url.pathname.slice(basePath.length) || "/";+ const startedAt = performance.now();+ const durationMs = () => Math.round(performance.now() - startedAt);++ try {+ const response = await originalFetch(input, init);+ const requestMs = durationMs();++ this.captureFailureReason(response).then((error) => {+ devDiagnostics.record({+ kind: "sdk-call",+ method,+ endpoint,+ status: response.status,+ durationMs: requestMs,+ error,+ });+ });++ return response;+ } catch (error) {+ if (!this.isAbortError(error)) {+ devDiagnostics.record({+ kind: "sdk-call",+ method,+ endpoint,+ status: null,+ durationMs: durationMs(),+ error: error instanceof Error ? error.message : String(error),+ });+ }++ throw error;+ }+ };+ }++ private resolveUrl(input: RequestInfo | URL): URL | null {+ try {+ if (typeof input === "string" || input instanceof URL) {+ return new URL(String(input), window.location.href);+ }++ return new URL(input.url, window.location.href);+ } catch {+ return null;+ }+ }++ private resolveMethod(+ input: RequestInfo | URL,+ init: RequestInit | undefined,+ ): string {+ const method =+ init?.method ?? (input instanceof Request ? input.method : "GET");++ return method.toUpperCase();+ }++ /**+ * The status code alone doesn't say what went wrong, and without the reason+ * the feed can only report *that* a call failed. A non-2xx carries its reason+ * in the body; a query that died after the status line was already sent+ * reports the failure in the body of a 2xx.+ */+ private async captureFailureReason(+ response: Response,+ ): Promise<string | undefined> {+ try {+ const body = await response.clone().text();++ if (!response.ok) {+ return body ? this.getErrorMessage(body) : undefined;+ }++ return body.length > MAX_INSPECTED_BODY_CHARS+ ? undefined+ : this.getQueryFailure(body);+ } catch {+ return undefined;+ }+ }++ /**+ * Metabase reports API errors as `{ message }`; anything else reads better raw.+ **/+ private getErrorMessage(responseBody: string): string {+ return (+ this.getStringField(this.parseResponseBody(responseBody), "message") ??+ responseBody+ );+ }++ /**+ * A query that failed after the response was already 2xx says so in its body.+ **/+ private getQueryFailure(responseBody: string): string | undefined {+ const body = this.parseResponseBody(responseBody);++ return this.getStringField(body, "status") === "failed"+ ? (this.getStringField(body, "error") ?? "Query failed")+ : undefined;+ }++ private parseResponseBody(+ responseBody: string,+ ): Record<string, unknown> | undefined {+ try {+ const parsed: unknown = JSON.parse(responseBody);++ if (typeof parsed !== "object" || parsed === null) {+ return undefined;+ }++ // Checked above to be a non-null object, and the values stay `unknown` —+ // `getStringField` narrows each one before it is used.+ return parsed as Record<string, unknown>;+ } catch {+ return undefined;+ }+ }++ private getStringField(+ body: Record<string, unknown> | undefined,+ key: string,+ ): string | undefined {+ const value = body?.[key];++ return typeof value === "string" ? value : undefined;+ }++ private isAbortError(error: unknown): boolean {+ return error instanceof DOMException && error.name === "AbortError";+ }+}++export const sdkCallCapture = new SdkCallCapture();diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/sdk-call-capture.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/sdk-call-capture.unit.spec.tsnew file mode 100644index 00000000000..d290f62e436--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/sdk-call-capture.unit.spec.ts@@ -0,0 +1,307 @@+import { devDiagnostics } from "../components/DevToolbar/diagnostics";+import { DATA_APP_DIAGNOSTIC_MAX_CHARS } from "../constants/diagnostics-channel";++import { truncateDiagnosticText } from "./diagnostics-limits";+import { sdkCallCapture } from "./sdk-call-capture";++const METABASE_URL = "http://localhost:3000";++const jsonResponse = (body: unknown) =>+ new Response(JSON.stringify(body), {+ status: 200,+ headers: { "Content-Type": "application/json" },+ });++const errorResponse = (status: number, body: unknown) =>+ new Response(JSON.stringify(body), {+ status,+ headers: { "Content-Type": "application/json" },+ });++const realFetch = window.fetch;++let originalFetch: jest.Mock<Promise<Response>, []>;++const setup = (metabaseUrl: string = METABASE_URL) => {+ originalFetch = jest.fn(async () => jsonResponse({}));+ window.fetch = originalFetch;+ sdkCallCapture.install(metabaseUrl);+};++// The capture records off the critical path (the app gets its response first),+// so let the background read settle before asserting on what was recorded.+const call = async (input: RequestInfo | URL, init?: RequestInit) => {+ const response = await window.fetch(input, init);+ await new Promise((resolve) => setTimeout(resolve));++ return response;+};++const calls = () =>+ devDiagnostics.getEntries().filter((entry) => entry.kind === "sdk-call");++describe("SdkCallCapture", () => {+ beforeEach(() => devDiagnostics.clear());+ afterEach(() => {+ window.fetch = realFetch;+ });++ it("records a Metabase call and ignores everything else", async () => {+ setup();++ await call(`${METABASE_URL}/api/card/1`);+ await call("https://example.com/thing");++ expect(calls()).toHaveLength(1);+ expect(calls()[0]).toMatchObject({ endpoint: "/api/card/1", status: 200 });+ });++ it("reads a successful response through a clone, never the original", async () => {+ setup();+ // A 2xx is inspected for a reported failure, so the original body has to be+ // left untouched for the caller.+ const exported = jsonResponse([{ a: 1 }]);+ const clone = jest.spyOn(exported, "clone");+ originalFetch.mockResolvedValue(exported);++ await call(`${METABASE_URL}/api/dataset/json`);++ expect(clone).toHaveBeenCalled();+ expect(exported.bodyUsed).toBe(false);+ });++ it("records the request method from init or a Request", async () => {+ setup();++ await call(`${METABASE_URL}/api/card/1`, { method: "post" });+ expect(calls()[0].method).toBe("POST");++ await call(new Request(`${METABASE_URL}/api/card/2`, { method: "PUT" }));+ expect(calls()[1].method).toBe("PUT");+ });++ it("reports why a request failed, not just that it did", async () => {+ setup();+ originalFetch.mockResolvedValue(+ errorResponse(400, { message: 'Table "orders" is not in the manifest' }),+ );++ await call(`${METABASE_URL}/api/dataset`);++ // The status alone leaves the author — and an agent reading the feed —+ // with "a query failed" and nowhere to go next.+ expect(calls()[0]).toMatchObject({+ status: 400,+ error: 'Table "orders" is not in the manifest',+ });+ });++ it("falls back to the raw body when the failure isn't a Metabase error", async () => {+ setup();+ originalFetch.mockResolvedValue(+ new Response("<html>502 Bad Gateway</html>", { status: 502 }),+ );++ await call(`${METABASE_URL}/api/dataset`);++ expect(calls()[0]).toMatchObject({+ status: 502,+ error: "<html>502 Bad Gateway</html>",+ });+ });++ it("reports a query that failed inside a 2xx, which the status alone hides", async () => {+ setup();+ originalFetch.mockResolvedValue(+ jsonResponse({ status: "failed", error: "Table does not exist" }),+ );++ await call(`${METABASE_URL}/api/dataset`);++ expect(calls()[0]).toMatchObject({+ status: 200,+ error: "Table does not exist",+ });+ });++ it("names a 2xx failure that carries no reason", async () => {+ setup();+ originalFetch.mockResolvedValue(jsonResponse({ status: "failed" }));++ await call(`${METABASE_URL}/api/dataset`);++ expect(calls()[0]).toMatchObject({ status: 200, error: "Query failed" });+ });++ it("leaves a completed result alone", async () => {+ setup();+ originalFetch.mockResolvedValue(+ jsonResponse({ status: "completed", data: { rows: [[1]] } }),+ );++ await call(`${METABASE_URL}/api/dataset`);++ expect(calls()[0]).toMatchObject({ status: 200, error: undefined });+ });++ it("gives up on a result too large to be an error", async () => {+ setup();+ // Reading it whole would pull the entire result into memory just to learn+ // it is not a failure map.+ originalFetch.mockResolvedValue(+ jsonResponse({ status: "failed", pad: "x".repeat(200 * 1024) }),+ );++ await call(`${METABASE_URL}/api/dataset`);++ expect(calls()[0]).toMatchObject({ status: 200, error: undefined });+ });++ it("leaves a 2xx body readable by the caller", async () => {+ setup();+ originalFetch.mockResolvedValue(+ jsonResponse({ status: "completed", rows: 1 }),+ );++ const response = await call(`${METABASE_URL}/api/dataset`);++ expect(await response.json()).toEqual({ status: "completed", rows: 1 });+ });++ it("records a failure with an empty body without inventing a reason", async () => {+ setup();+ originalFetch.mockResolvedValue(new Response("", { status: 500 }));++ await call(`${METABASE_URL}/api/dataset`);++ expect(calls()[0]).toMatchObject({ status: 500, error: undefined });+ });++ it("leaves the failure body readable by the caller", async () => {+ setup();+ originalFetch.mockResolvedValue(errorResponse(400, { message: "nope" }));++ const response = await call(`${METABASE_URL}/api/dataset`);++ // We read the body to report the reason. Reading the response itself rather+ // than a clone would leave the SDK's own error handling with a consumed+ // stream — every failure in the app would turn into a body-parse error.+ await expect(response.json()).resolves.toEqual({ message: "nope" });+ });++ it("truncates a huge failure body exactly once", async () => {+ setup();+ const message = "x".repeat(DATA_APP_DIAGNOSTIC_MAX_CHARS + 1000);+ originalFetch.mockResolvedValue(errorResponse(400, { message }));++ await call(`${METABASE_URL}/api/dataset`);++ // Truncating here as well as in the collector would re-truncate the already+ // truncated string and chop up its own "… (truncated)" marker.+ const { error } = calls()[0];+ expect(error).toBe(truncateDiagnosticText(message));+ expect(error).toContain(`truncated, ${message.length} chars`);+ });++ it("reports a large error body, truncated, rather than losing the reason", async () => {+ setup();+ // Unlike a 2xx result, an error is read whatever its size — the reason is at+ // the front, and `record` truncates what we keep.+ originalFetch.mockResolvedValue(+ new Response("x".repeat(200 * 1024), { status: 502 }),+ );++ await call(`${METABASE_URL}/api/dataset`);++ const { status, error } = calls()[0];+ expect(status).toBe(502);+ expect(error).toContain("truncated");+ });++ it("keeps the querystring out of the recorded endpoint", async () => {+ setup();++ await call(`${METABASE_URL}/api/card/1?token=secret&foo=bar`);++ // The feed is served over HTTP and read by tools outside the browser, so+ // anything credential-shaped in a query parameter must not reach it.+ expect(calls()[0].endpoint).toBe("/api/card/1");+ expect(JSON.stringify(calls()[0])).not.toContain("secret");+ });++ it("records the time the call took", async () => {+ setup();++ await call(`${METABASE_URL}/api/card/1`);++ expect(calls()[0].durationMs).toEqual(expect.any(Number));+ });++ it("ignores an aborted request rather than reporting a failure", async () => {+ setup();+ originalFetch.mockRejectedValue(+ new DOMException("The user aborted a request.", "AbortError"),+ );++ await expect(window.fetch(`${METABASE_URL}/api/dataset`)).rejects.toThrow();++ // StrictMode remounts and superseded queries abort routinely; badging those+ // as errors trains the author to ignore the badge.+ expect(calls()).toHaveLength(0);+ });++ it("still reports a genuine transport failure", async () => {+ setup();+ originalFetch.mockRejectedValue(new TypeError("Failed to fetch"));++ await expect(window.fetch(`${METABASE_URL}/api/dataset`)).rejects.toThrow();++ expect(calls()[0]).toMatchObject({+ status: null,+ error: "Failed to fetch",+ });+ });++ it("strips the base path of a sub-path deployment", async () => {+ setup("https://acme.com/metabase");++ await call("https://acme.com/metabase/api/dataset");++ // Without stripping, every endpoint reads `/metabase/api/...`, which matches+ // neither the paths the author knows nor the ones in the Metabase docs.+ expect(calls()[0]).toMatchObject({ endpoint: "/api/dataset" });+ });++ it("passes through a same-origin call that sits outside the base path", async () => {+ setup("https://acme.com/metabase");++ // Another app on the same host is not the Metabase deployment; recording it+ // would put a tenant's unrelated traffic into the data-app author's feed.+ await call("https://acme.com/other-app/api/dataset");++ expect(calls()).toHaveLength(0);+ });++ it("does nothing without a Metabase URL to watch", async () => {+ const untouched = jest.fn(async () => jsonResponse({}));+ window.fetch = untouched;++ sdkCallCapture.install(undefined);+ await call(`${METABASE_URL}/api/card/1`);++ // `fetch` is left alone, so nothing is recorded.+ expect(window.fetch).toBe(untouched);+ expect(calls()).toHaveLength(0);+ });++ it("does nothing when the Metabase URL cannot be parsed", async () => {+ const untouched = jest.fn(async () => jsonResponse({}));+ window.fetch = untouched;++ sdkCallCapture.install("not-a-url");+ await call(`${METABASE_URL}/api/card/1`);++ expect(window.fetch).toBe(untouched);+ expect(calls()).toHaveLength(0);+ });+});diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.tsnew file mode 100644index 00000000000..9d687259892--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.ts@@ -0,0 +1,46 @@+import type { DataAppManifestStatus } from "./manifest-status";++export interface InstanceConnectionStatus {+ checkedAt: number;+ metabaseUrl: string;+ reachable: boolean;+ sdkVersion: string | null;+ error: string | null;+}++export interface DataAppDiagnosticEntry {+ time: number;+ kind: string;+ summary: string;+ detail: string | null;+ hint: string | null;+ alert: boolean;+}++export interface DataAppDiagnosticPayload extends DataAppDiagnosticEntry {+ eventId: number;+}++export interface DataAppDiagnosticsMessage {+ sessionId: string;+ entries: DataAppDiagnosticEntry[];+ connection: InstanceConnectionStatus | null;+}++export interface DataAppDiagnosticsReport {+ entries: DataAppDiagnosticPayload[];+ connection: InstanceConnectionStatus | null;+ manifest: DataAppManifestStatus | null;+ clients: number;+ lastReportAt: number | null;+ lastRebuildAt: number | null;+ /** Cursor for the next poll (`?startEventId=`): the last event's id + 1. */+ nextEventId: number;+ sessionId: string | null;+}++/** The part of the report the store owns; the rest comes from the dev server. */+export type DiagnosticsStoreReport = Omit<+ DataAppDiagnosticsReport,+ "manifest" | "clients" | "lastRebuildAt"+>;diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.tsnew file mode 100644index 00000000000..7833165fb09--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.ts@@ -0,0 +1,25 @@+export type DevDiagnosticEvent =+ | { kind: "error"; message: string }+ | { kind: "blocked-api"; message: string }+ | {+ kind: "blocked-network";+ api: "fetch" | "xhr";+ url: string;+ reason: string;+ }+ | { kind: "csp-violation"; directive: string; blockedUri: string }+ | {+ kind: "sdk-call";+ method: string;+ endpoint: string;+ status: number | null;+ durationMs: number;+ // Why it failed: the response body on a non-2xx, the thrown message on a+ // transport failure. Absent on success.+ error?: string;+ };++export type DevDiagnosticEntry = {+ id: number;+ time: number;+} & DevDiagnosticEvent;diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/manifest-status.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/manifest-status.tsnew file mode 100644index 00000000000..9c9e21d556c--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/manifest-status.ts@@ -0,0 +1,10 @@+export interface DataAppManifestStatus {+ checkedAt: number;+ name: string | null;+ bundlePath: string | null;+ bundlePathExists: boolean;+ allowedHosts: string[];+ errors: string[];+ warnings: string[];+ restartRequired: boolean;+}diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.tsindex c34ddb9a54c..c9040197c20 100644--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts@@ -1,12 +1,14 @@interface ImportMetaEnv {- readonly DATA_APP_MB_URL: string;- readonly DATA_APP_MB_API_KEY: string;+ readonly DATA_APP_MB_URL: string | undefined;+ readonly DATA_APP_MB_API_KEY: string | undefined;}interface ImportMeta {readonly env: ImportMetaEnv;readonly hot?: {on(event: string, cb: (...args: unknown[]) => void): void;+ off(event: string, cb: (...args: unknown[]) => void): void;+ send(event: string, data?: unknown): void;};}@@ -15,4 +17,6 @@ declare module "virtual:metabase-data-app-dev-config" {export const appSlug: string;export const bundleUrl: string;export const rebuiltEvent: string;+ export const diagnosticsChangedEvent: string;+ export const sdkVersion: string | null;}diff --git a/skills/metabase-data-app-setup/SKILL.md b/skills/metabase-data-app-setup/SKILL.mdindex 1917d2e34c5..4bf3cdd8331 100644--- a/skills/metabase-data-app-setup/SKILL.md+++ b/skills/metabase-data-app-setup/SKILL.md@@ -5,7 +5,7 @@ description: Scaffold a new Metabase data-app into the connected remote-sync rep# Create a Metabase Data App-A Metabase **data-app** is a single JS bundle that the host loads inside a Near Membrane sandbox and renders inside its own React tree. The scaffold is a Vite + React + TypeScript project: source under `src/`, a dev server that previews the app against a real Metabase **through the same Near Membrane sandbox + distortion rules Metabase uses in production** — so `npm run dev` behaves like production, including for third-party libraries the app bundles — and `npm run build` producing a single `dist/index.js`. (Because the sandbox runs a built bundle, a change rebuilds it and does a *soft reload* — re-evaluates the bundle in the sandbox and remounts the app, keeping auth/SDK loaded — rather than hot-swapping modules; component state resets, but there's no full browser refresh.) The dev preview also shows a corner **⚠ Diagnostics** toolbar that captures runtime errors — including the sandbox's otherwise-opaque blocked-API messages — so failures surface instead of being swallowed.+A Metabase **data-app** is a single JS bundle that the host loads inside a Near Membrane sandbox and renders inside its own React tree. The scaffold is a Vite + React + TypeScript project: source under `src/`, a dev server that previews the app against a real Metabase **through the same Near Membrane sandbox + distortion rules Metabase uses in production** — so `npm run dev` behaves like production, including for third-party libraries the app bundles — and `npm run build` producing a single `dist/index.js`. (Because the sandbox runs a built bundle, a change rebuilds it and does a *soft reload* — re-evaluates the bundle in the sandbox and remounts the app, keeping auth/SDK loaded — rather than hot-swapping modules; component state resets, but there's no full browser refresh.) The dev preview also shows a corner **⚠ Diagnostics** toolbar that captures runtime errors — including the sandbox's otherwise-opaque blocked-API messages — so failures surface instead of being swallowed. The same data is served as JSON at `http://localhost:5174/__data-app/diagnostics`, which is how *you* read it (see "Reading the diagnostics feed" below) — you have a shell, not a browser, and these failures are invisible from the terminal otherwise.**Data apps are served from Git, not uploaded.** A single repository is connected to Metabase via remote-sync (Admin → Settings → Remote sync). Each app lives in its own directory `data_apps/<app>/` inside that repo — its source, a `data_app.yaml` (name/path), and the committed built bundle at the `path` its `data_app.yaml` declares (`dist/index.js` by default). On each remote-sync import Metabase materializes one app per directory and serves it at `/apps/<slug>` url, where the slug **is** the directory's name. So this skill always scaffolds **into the connected repo's `data_apps/<app>/` directory**, never as a standalone project.@@ -167,6 +167,15 @@ project scaffold and proving the starter bundle works.built bundle (`dist/index.js` by default) as committable files.4. If the user asked for a live preview, run `npm run dev` and confirm thestarter "Hello, data app" screen renders through the sandbox preview.+5. With the preview open, check the diagnostics feed once — it is the only place+ runtime failures appear to you (see *Reading the diagnostics feed*):++ ```bash+ curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"+ ```++ Expect `clients: 1` and no entries with `"alert": true`. `clients: 0` means no+ preview tab is open, so an empty feed proves nothing.Stop here if the user only asked to create, scaffold, or set up a data app.@@ -193,6 +202,49 @@ There is intentionally **no escape hatch** for extra Vite plugins, aliases, or `**Before handoff, re-check package hygiene.** `@metabase/embedding-sdk-react` should use the expected data-app SDK source/tag for the target environment, and `@types/react-datepicker` should not be installed unless the chosen `react-datepicker` version actually needs it.+## Reading the diagnostics feed++`npm run dev` serves everything the toolbar shows as JSON — the only way *you*+see runtime failures, since sandbox blocks, CSP refusals, failed queries and+uncaught errors reach neither the terminal nor `npm run typecheck`. Check it+after any change you can't verify by reading the code.++**Loop:** note `nextEventId` before editing → make the change (rebuilds+automatically) → re-read. `startEventId` is inclusive and survives page reloads.++```bash+curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"+```++```jsonc+{+ "entries": [{+ "eventId": 31, "kind": "blocked-network", "alert": true,+ "summary": "Blocked fetch to api.example.com (not in allowed_hosts)",+ "detail": null, // stack frames, when any+ "hint": "Add https://api.example.com to allowed_hosts in data_app.yaml …"+ }],+ "clients": 1, // connected preview tabs — 0 means nothing ran+ "nextEventId": 32 // pass back as ?startEventId=+}+```++**`clients: 0` does not mean healthy** — it means no preview tab is open, so an+empty `entries` proves nothing. Open `http://localhost:5174` first.++Triage by `kind` (always read `hint` — it names the exact fix; never soften a+`summary` when reporting it):++| `kind` | Fix |+|---|---|+| `blocked-network` / `csp-violation` | add the origin to `allowed_hosts` in `data_app.yaml`, then **restart** `npm run dev` (allowlist + CSP are read at boot) |+| `blocked-api` | blocked in production too — use an SDK API or drop the call, don't work around it |+| `sdk-call` + `alert: true` | a Metabase request failed; fix the query — `summary` has the endpoint and status |+| `error` | a real bug; `detail` has the stack |++Text is truncated and the buffer holds the last 200 events. `curl -X DELETE+.../__data-app/diagnostics` clears it for every reader.+## Source conventions### 1. Write TSX@@ -436,6 +488,8 @@ Data apps are delivered by Git, not uploaded — you commit the app directory an| `dist/index.js` doesn't assign to `__dataAppFactory__`. | `src/index.tsx` must `export default` the `DataAppFactory` — the preset wires that into the IIFE global. || `Cannot find module '@metabase/embedding-sdk-react'`. | Run `npm install` (or the equivalent for your package manager). Types come from the package directly. || Drill popups don't open / SDK components show empty / "MetabaseProvider not found" at runtime in dev. | `App.tsx` is rendering its own `<MetabaseProvider>` — remove it. The dev entry (SDK) and the production host provide the provider; wrapping it inside the bundle routes the SDK's state paths through the sandbox and breaks them. |-| Dev preview blank / `Bundle did not assign a function to __dataAppFactory__` / sandbox errors in dev. | `src/index.tsx` isn't default-exporting the factory, or your app code throws while the sandbox evaluates the bundle — open the dev toolbar's **Diagnostics** panel for the real error. |+| Dev preview blank / `Bundle did not assign a function to __dataAppFactory__` / sandbox errors in dev. | `src/index.tsx` isn't default-exporting the factory, or your app code throws while the sandbox evaluates the bundle. Read the real error from the diagnostics feed (`curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"`), or the dev toolbar's **Diagnostics** panel. |+| A network call works in `npm run dev` but is blocked after syncing to Metabase. | It was never allowed — you edited `allowed_hosts` without restarting the dev server, so the running sandbox and CSP still use the boot-time list. Restart `npm run dev`; the feed's `manifest` section flags this as `restartRequired`. |+| The SDK was rebuilt or reinstalled but the preview still behaves like the old version. | Vite pre-bundles the SDK into `node_modules/.vite` and keys that cache on the package version, so an in-place rebuild doesn't invalidate it. Stop the dev server, delete the `node_modules/.vite` directory, and start it again (or run `npx vite --force`). || Component state resets on every edit. | Expected: dev rebuilds the bundle and does a *soft reload* — re-evaluates it in the sandbox and remounts the app (auth/SDK stay loaded, no browser refresh). There's no module-level HMR / Fast Refresh because the app is an evaluated bundle in an isolated realm, so local component state resets. || URL changes but UI doesn't update in production (works in dev). | Import the routing primitives from `@metabase/embedding-sdk-react/data-app` (not the main entry) and keep using `dataAppConfig()` — it externalizes `/data-app` so its routing isn't inlined (inlining triggers the React-state-batching-through-Near-Membrane bug). |