Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

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.tsx
index 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.ts
index 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.tsx
index 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() {
<button
type="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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
similarity index 90%
rename from enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/serve-index-html.ts
rename to enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/index-html-middleware.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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 the
starter "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). |