@metabase/cli 0.5.12 → 0.5.14-alpha.cover-more-endpoints-for-mbcode.5fc0688

package/skill-data/data-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-app
-description: Create, preview, release and manage a Metabase data app — a React app Metabase serves at /apps/<slug> from the synced git repository — scaffold it in the repository, run the dev preview and read its diagnostics feed, generate its questions and actions, build, push and import it, turn it off, move it to another instance, delete it. Triggers — "build a data app", "make an internal tool in Metabase", "scaffold a data app", "publish my data app", "update the app", "the app is blank". Start here; the UI is in `data-app-ui`, questions and charts in `data-app-data`, filter controls in `data-app-filters`, writes in `data-app-actions`.
+description: Create, preview, release and manage a Metabase data app — a React app Metabase serves at /apps/<slug> from the synced git repository — scaffold it in the repository, run the dev preview and read its diagnostics feed, generate its questions and actions, build, push and import it, turn it off, move it to another instance, delete it. Triggers — "build a data app", "make an internal tool in Metabase", "scaffold a data app", "publish my data app", "update the app", "the app is blank". Start here; the UI is in `data-app-ui`, questions and charts in `data-app-data`, filter controls in `data-app-filters`, writes in `data-app-actions`, tests in `data-app-testing`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataApps]
 ---
@@ -13,8 +13,8 @@ The work, in order:
 
 1. Scaffold the app in the synced repository and install the SDK.
 2. Give it data: fetch `src/metabase.schema.ts`, then define questions over the Library's published tables and metrics (`data-app-data`); writes are `data-app-actions`.
-3. Start the dev preview (_Dev preview_), then write the UI under `src/` (`data-app-ui`; filter controls in `data-app-filters`).
-4. Generate the collection, build, push and import (_Release_).
+3. Start the dev preview (_Dev preview_), then write the UI under `src/` (`data-app-ui`; filter controls in `data-app-filters`), with a test next to each component (`data-app-testing`).
+4. Pass the tests, then generate the collection, build, push and import (_Release_).
 
 For every later change: first pass the checks in _An existing project_ (_Scaffold and install_), then change the source, then release (_Release_). The live app changes only through the import.
 
@@ -54,7 +54,7 @@ cd data_apps/sales-overview &&
 
 `mb data-app sdk-version` reads the instance's version and, from the registry `npm install` uses, answers the SDK tag published for that Metabase major: its stable tag, or while it has none, its beta, then its alpha. Installing the tag writes the version it points at into `package.json` (`^0.65.1`), in place of the template's `*` or any version an existing project named. Run the block as one command: it stops at the first failure, so a refused tag installs nothing, where a plain `npm install` would install `latest` for the template's `*`. Never install a tag you picked yourself. When `package.json` already points the SDK at a local build (`file:` or `link:`), run only `npm install && npm run typecheck`. `sdk-version` fails on a development build (`vUNKNOWN`, `vLOCAL_DEV`, a `-SNAPSHOT` tag), which no published SDK matches: ask the user which SDK build to install. On any other failure, stop and tell the user what it says. The starter renders "Hello, data app".
 
-The template is the bundle contract. Don't edit `package.json` by hand, and never rewrite `vite.config.ts`, `tsconfig.json` or `src/index.tsx`: `vite.config.ts` stays `export default dataAppConfig()` (its only option is `port`), and `src/index.tsx` default-exports the `DataAppFactory` — change it only to add a `providerProps` key. Metabase and the dev preview each wrap the app in a `<MetabaseProvider>`, so the app never renders one.
+The template is the bundle contract. Don't edit `package.json` by hand, and never rewrite `vite.config.ts`, `vitest.config.ts`, `playwright.config.ts`, `tsconfig.json` or `src/index.tsx`: `vite.config.ts` stays `export default dataAppConfig()` (its only option is `port`), and `src/index.tsx` default-exports the `DataAppFactory` — change it only to add a `providerProps` key. Metabase and the dev preview each wrap the app in a `<MetabaseProvider>`, so the app never renders one.
 
 **An existing project.** Before changing an app you didn't scaffold in this session, pass four checks:
 
@@ -116,12 +116,13 @@ curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"
 - The feed answers for the running bundle: entries from replaced builds are counted in `staleEntries`, and anything still broken reports again under the new `buildId` (`?includeStale=true` shows the withheld ones). A failed build doesn't advance `buildId` and doesn't reach the feed — read the `npm run dev` terminal.
 - Quote `summary` as it is when you report it, and follow `hint` when there is one — except that you never add the Metabase URL to `allowed_hosts`. An origin goes in `allowed_hosts` in `data_app.yaml`, then restart `npm run dev`. A `frame-src` or `form-action` block can't be lifted in the preview (`data-app-ui`). The feed keeps the last 200 entries; `curl -X DELETE …/__data-app/diagnostics` clears it.
 
-| `kind`                             | Fix                                                                                                                 |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `blocked-network`, `csp-violation` | An external API: `data-app-ui`, _External APIs_. A `script-src` or `style-src` violation: bundle the asset instead. |
-| `blocked-api`                      | Blocked in Metabase too: use the replacement in `data-app-ui`.                                                      |
-| `sdk-call` with `alert: true`      | A Metabase request failed; `summary` names it.                                                                      |
-| `error`                            | A bug; `detail` has the stack.                                                                                      |
+| `kind`                                | Fix                                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `blocked-network`, `csp-violation`    | An external API: `data-app-ui`, _External APIs_. A `script-src` or `style-src` violation: bundle the asset instead. |
+| `blocked-api`                         | Blocked in Metabase too: use the replacement in `data-app-ui`.                                                      |
+| `sdk-call` with `alert: true`         | A Metabase request failed; `summary` names it.                                                                      |
+| `sdk-call` for `/api/analytics-proxy` | Metabase's own usage analytics, not the app's: ignore it.                                                           |
+| `error`                               | A bug; `detail` has the stack.                                                                                      |
 
 ## Release
 
@@ -129,8 +130,8 @@ Build the bundle last, test it in the dev preview, then push it with the source
 
 1. On a read-write instance, `mb git-sync is-dirty --profile <name> --json`: when it reports unexported changes (a table just published to the Library, say), export them first (`git-sync`, its branch guard included), or the import refuses; then `git pull --ff-only` in `<repo>`.
 2. In `<repo>`, `mb data-app generate-queries <slug> --profile <name>` and `mb data-app generate-actions <slug> --profile <name>`. They load the exports of `src/metabase.queries.ts` and of `src/metabase.actions.ts` with the app's Vite, so `npm install` runs in the app first, and each replaces its kind of file in `collections/data_apps/data_app__<slug>/`: one YAML file per question or action, named after its export in lowercase and carrying its `entityId`. A generated question shows as a table in Metabase whatever the app makes of it. Nothing changes in Metabase.
-3. In the app, `npm run typecheck && npm run build`, which writes `dist/index.js`.
-4. With `npm run dev` running and a preview tab open, read the diagnostics feed (_Dev preview_) with every page mounted; fix what it reports, then generate and build again.
+3. In the app, pass the tests (`data-app-testing`, _Before handoff_), then `npm run typecheck && npm run build`, which writes `dist/index.js`.
+4. With `npm run dev` running, run `npm run test:e2e` (`data-app-testing`), which reuses that preview, then read the diagnostics feed (_Dev preview_): the run mounted every page, and the feed keeps what they reported after its tabs close. Fix what it reports, then generate and build again.
 5. Commit `data_apps/<slug>/` — the source, `package.json`, `package-lock.json`, `data_app.yaml` and `dist/index.js` — and `collections/data_apps/` together, and push.
 6. `mb git-sync import --profile <name>`, whatever a cached `has-remote-changes` says. The bundle, questions and actions are live at once.
 
@@ -142,17 +143,18 @@ A viewer needs one of their groups assigned to the app (otherwise "You don't hav
 
 ## Pitfalls
 
-| Symptom                                                             | Fix                                                                                                                                   |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| The app still runs the old bundle                                   | `dist/index.js` isn't in the pushed commit, or the push wasn't imported: build, commit, push, import.                                 |
-| Works in the preview, a question or action fails in Metabase        | `generate-queries` or `generate-actions` didn't run after the last change, or the files weren't committed with the bundle: _Release_. |
-| Blank app, `Bundle did not assign a function to __dataAppFactory__` | `src/index.tsx` must `export default` the factory and nothing else; otherwise the diagnostics feed has the real error.                |
-| "Failed to fetch the user, the session might be invalid."           | A bad key in `<repo>/.env.local`, or CORS (_Dev preview_).                                                                            |
-| A bundle of several MB                                              | `vite.config.ts` doesn't use `dataAppConfig()`, or the SDK isn't the tag `mb data-app sdk-version` answers.                           |
-| "Invalid hook call"                                                 | A second React got bundled: nothing may add another `react` or `react-dom`.                                                           |
-| Drill-through popups don't open                                     | The app renders its own `<MetabaseProvider>`: remove it.                                                                              |
-| An upgraded SDK still behaves like the old one                      | Vite caches it: stop `npm run dev`, delete `node_modules/.vite`, start again.                                                         |
-| A viewer's query or action fails with 403                           | It reads a table not published to the Library on that instance, or the viewer lacks data access to its tables.                        |
+| Symptom                                                                           | Fix                                                                                                                                   |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| The app still runs the old bundle                                                 | `dist/index.js` isn't in the pushed commit, or the push wasn't imported: build, commit, push, import.                                 |
+| Works in the preview, a question or action fails in Metabase                      | `generate-queries` or `generate-actions` didn't run after the last change, or the files weren't committed with the bundle: _Release_. |
+| Blank app, `Bundle did not assign a function to __dataAppFactory__`               | `src/index.tsx` must `export default` the factory and nothing else; otherwise the diagnostics feed has the real error.                |
+| "Failed to fetch the user, the session might be invalid."                         | A bad key in `<repo>/.env.local`, or CORS (_Dev preview_).                                                                            |
+| The app stays on loading; the terminal says "Failed to load Embedding SDK bundle" | No `<repo>/.env.local`, or a wrong `DATA_APP_MB_URL` in it (_Dev preview_).                                                           |
+| A bundle of several MB                                                            | `vite.config.ts` doesn't use `dataAppConfig()`, or the SDK isn't the tag `mb data-app sdk-version` answers.                           |
+| "Invalid hook call"                                                               | A second React got bundled: nothing may add another `react` or `react-dom`.                                                           |
+| Drill-through popups don't open                                                   | The app renders its own `<MetabaseProvider>`: remove it.                                                                              |
+| An upgraded SDK still behaves like the old one                                    | Vite caches it: stop `npm run dev`, delete `node_modules/.vite`, start again.                                                         |
+| A viewer's query or action fails with 403                                         | It reads a table not published to the Library on that instance, or the viewer lacks data access to its tables.                        |
 
 ## Change, move, delete
 

package/skill-data/data-app/template/README.md

@@ -25,7 +25,9 @@ In the app:
 
 ```bash
 npm run dev         # preview at http://localhost:5174, in the sandbox Metabase runs apps in
-npm run typecheck   # type-checks src/ and vite.config.ts
+npm run typecheck   # type-checks src/ and the configs
+npm run test:unit   # runs the unit tests next to the components
+npm run test:e2e    # runs the Playwright specs in e2e/ against the preview
 npm run build       # builds dist/index.js, the app's bundle
 ```
 
@@ -44,3 +46,8 @@ included, with the files `generate-queries` and `generate-actions` write under
 
 `npm run dev` reads `DATA_APP_MB_URL` and `DATA_APP_MB_API_KEY` from
 `.env.local` at the repository root; `.env.local.example` lists them.
+
+`npm run test:e2e` starts the preview, or reuses one already running; the first
+run on a machine needs `npx playwright install chromium`. In CI, set
+`DATA_APP_MB_URL` and `DATA_APP_MB_API_KEY` in the job's environment, against the
+instance `src/metabase.schema.ts` was generated from.

package/skill-data/data-app/template/e2e/app.spec.ts

@@ -0,0 +1,6 @@
+import { expect, test } from "@playwright/test";
+
+test("app renders", async ({ page }) => {
+  await page.goto("");
+  await expect(page.getByRole("heading", { name: "Hello, data app" })).toBeVisible();
+});

package/skill-data/data-app/template/gitignore

@@ -2,3 +2,6 @@ node_modules
 .env.local
 .vite
 .idea
+.scratch
+test-results
+playwright-report

package/skill-data/data-app/template/package.json

@@ -6,7 +6,9 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build --outDir dist",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:unit": "vitest run",
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@metabase/embedding-sdk-react": "*",
@@ -14,12 +16,20 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.2",
+    "jsdom": "^30.1.3",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
     "vite-plugin-css-injected-by-js": "^3.5.2",
-    "vite-plugin-svgr": "^5.2.0"
+    "vite-plugin-svgr": "^5.2.0",
+    "vitest": "^5.0.5"
   }
 }

package/skill-data/data-app/template/playwright.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const BASE_URL = process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:5174/";
+const PORT = Number(new URL(BASE_URL).port);
+
+export default defineConfig({
+  testDir: "e2e",
+  use: { ...devices["Desktop Chrome"], baseURL: BASE_URL },
+  webServer: {
+    command: `npm run dev -- --port ${PORT} --strictPort`,
+    port: PORT,
+    reuseExistingServer: true,
+  },
+});

package/skill-data/data-app/template/src/App.test.tsx

@@ -0,0 +1,10 @@
+import { screen } from "@testing-library/react";
+import { expect, it } from "vitest";
+
+import App from "./App";
+import { renderWithProviders } from "./test/render";
+
+it("renders the starter page", () => {
+  renderWithProviders(<App />);
+  expect(screen.getByRole("heading", { name: "Hello, data app" })).toBeInTheDocument();
+});

package/skill-data/data-app/template/src/metabase.actions.ts

@@ -1,3 +1 @@
 import { defineAction } from "@metabase/embedding-sdk-react/data-app";
-
-import { schema } from "./metabase.schema";

package/skill-data/data-app/template/src/metabase.queries.ts

@@ -1,3 +1 @@
 import { defineQuery } from "@metabase/embedding-sdk-react/data-app";
-
-import { schema } from "./metabase.schema";

package/skill-data/data-app/template/src/test/render.tsx

@@ -0,0 +1,10 @@
+import {
+  MetabaseTestProvider,
+  type MetabaseTestProviderProps,
+} from "@metabase/embedding-sdk-react/testing";
+import { render } from "@testing-library/react";
+import type { ReactElement } from "react";
+
+export function renderWithProviders(ui: ReactElement, options: MetabaseTestProviderProps = {}) {
+  return render(<MetabaseTestProvider {...options}>{ui}</MetabaseTestProvider>);
+}

package/skill-data/data-app/template/src/test/setup.ts

@@ -0,0 +1,5 @@
+import "@testing-library/jest-dom/vitest";
+import { cleanup } from "@testing-library/react";
+import { afterEach } from "vitest";
+
+afterEach(cleanup);

package/skill-data/data-app/template/tsconfig.json

@@ -19,7 +19,7 @@
     "noUnusedLocals": false,
     "noUnusedParameters": false,
     "noFallthroughCasesInSwitch": true,
-    "types": ["vite/client"]
+    "types": ["vite/client", "node"]
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "e2e", "vite.config.ts", "vitest.config.ts", "playwright.config.ts"]
 }

package/skill-data/data-app/template/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    include: ["src/**/*.test.{ts,tsx}"],
+    setupFiles: ["src/test/setup.ts"],
+  },
+});

package/skill-data/data-app-actions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-app-actions
-description: Make a Metabase data app write data — a table action that inserts, updates or deletes a row of a published table, defined with `defineAction` in `src/metabase.actions.ts`, and the `useAction` hook from `@metabase/embedding-sdk-react/data-app` behind a form or a button, with inputs typed from each parameter, the server's error shown as it comes, and every affected query refreshed. Triggers — "a form that saves a row", "a button that updates a record", "delete an entry from the app", "submit doesn't refresh the list", "the action fails in the app". Reads are `data-app-data`.
+description: Make a Metabase data app write data — a table action that inserts, updates or deletes a row of a published table, defined with `defineAction` in `src/metabase.actions.ts`, and the `useAction` hook from `@metabase/embedding-sdk-react/data-app` behind a form or a button, with inputs typed from each parameter, the server's error shown as it comes, and every affected query refreshed. Triggers — "a form that saves a row", "a button that updates a record", "delete an entry from the app", "submit doesn't refresh the list", "the action fails in the app". Reads are `data-app-data`; tests are `data-app-testing`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataApps]
 ---
@@ -12,16 +12,16 @@ A data app writes through **table actions**: an insert, update or delete of one
 ```ts
 import { defineAction } from "@metabase/embedding-sdk-react/data-app";
 
-import { schema } from "./metabase.schema";
+import { orders } from "./metabase.schema";
 
 export const updateOrder = defineAction({
   entityId: "J2mXq8sLb0vT5nYcW4kRd",
   kind: "row/update",
-  table: schema.tables.orders,
+  table: orders,
 });
 ```
 
-- `kind` is `row/create`, `row/update` or `row/delete`; `table` is a table of `schema` (`data-app-data`). The table needs exactly one primary key, and its database needs data actions turned on (_Data actions on the database_): settle both before writing the export. Show the user the table and kind and add it once they agree; a request that already names the write ("let me add a note") is that agreement.
+- `kind` is `row/create`, `row/update` or `row/delete`; `table` is a table of `src/metabase.schema.ts`, imported by its name, or `schema.tables.<table>` when the file exports only `schema`. The table needs exactly one primary key, and its database needs data actions turned on (_Data actions on the database_): settle both before writing the export. Show the user the table and kind and add it once they agree; a request that already names the write ("let me add a note") is that agreement.
 - `entityId` comes from `mb nano-id`, never invented; keep it when editing the export. The export's name is the action's name in Metabase.
 - There are no query actions and no SQL: a write a table action can't do (a computed value, several rows, a row matched by another column) is out of reach for the app — say so. Never copy an action from a data actions collection.
 - To drop an action, delete its export.
@@ -122,4 +122,6 @@ After a write succeeds, refetch every query on screen it could have changed: `aw
 3. The screen doesn't update: see _Refresh_.
 4. It works in the preview but not in Metabase: the app was released without running `mb data-app generate-actions` (`data-app`, _Release_).
 
-Then release the app (`data-app`, _Release_).
+## Test
+
+Every form and button that runs an action gets a unit test that mocks the action, drives the inputs, and checks the parameters it sends and the refresh that follows, plus one with `mockDataAppActionError` for the error shown as it comes (`data-app-testing`, _Actions_). The page's Playwright spec opens each form and checks its fields, and submits it only when the user has said the app's database may be written to (`data-app-testing`, _End-to-end tests_). Then release the app (`data-app`, _Release_).

package/skill-data/data-app-data/SKILL.md

@@ -32,7 +32,7 @@ When the app needs a table or metric the Library lacks, stop: name what's missin
 cd <repo> && mb data-app generate-schema <slug> --profile <name>
 ```
 
-From the repository root, this writes `data_apps/<slug>/src/metabase.schema.ts`: the Library's published tables with their fields, segments and measures, and the Library's metrics, each keyed by its camelCased name, with its numeric ID. It exports `schema` (`import { schema } from "./metabase.schema"`). Fetch it again after the user publishes a table or changes its metadata, then `npm run typecheck`, which catches code still using a renamed or removed field. Never edit the file.
+From the repository root, this writes `data_apps/<slug>/src/metabase.schema.ts`: the Library's published tables with their fields, segments and measures, and the Library's metrics, each keyed by its camelCased name, with its numeric ID. Fetch it again after the user publishes a table or changes its metadata, then `npm run typecheck`, which catches code still using a renamed or removed table, metric or field. Never edit the file.
 
 The numeric IDs are that instance's, so the dev preview runs against it alone; a production build runs each question by its `entityId` instead, on every instance the app is imported to.
 
@@ -44,7 +44,7 @@ The file runs to thousands of lines. Every table, field, segment, measure and me
    grep -n -B2 -E 'type: "(table|segment|measure|metric)"' src/metabase.schema.ts
    ```
 
-   Choose the definitions from this list: `schema.tables.<table>.segments.<key>`, `schema.tables.<table>.measures.<key>`, `schema.metrics.<key>`.
+   Choose the definitions from this list. A table or metric listed as `export const <name> = {` is its own export: import the ones the app uses by that name (`import { orders, revenue } from "./metabase.schema"`), and reach a table's segments and measures as `orders.segments.<key>` and `orders.measures.<key>`. The bundle then holds only what the app imports, while `schema`, which the file also exports, holds every table and metric: never import it. A file whose tables and metrics are listed without `export const` (`orders: {`) exports only `schema`: there, write `schema.tables.<table>` and `schema.metrics.<key>` wherever the examples below import a table or metric by name.
 
 2. Read each table or metric the question uses from its line to the next line in the list: a table's fields, each with its metadata line, or a metric's dimensions.
 
@@ -60,9 +60,7 @@ import {
   orderBy,
 } from "@metabase/embedding-sdk-react/data-app";
 
-import { schema } from "./metabase.schema";
-
-const orders = schema.tables.orders;
+import { orders, reviews } from "./metabase.schema";
 
 export const revenueByMonth = defineQuery({
   entityId: "Vh3kq0wYc8TnS2aJm1LxR",
@@ -73,13 +71,13 @@ export const revenueByMonth = defineQuery({
 
 export const latestReviews = defineQuery({
   entityId: "pW9dE4uNq7Zb1fGhK3sTy",
-  source: schema.tables.reviews,
-  orderBys: [orderBy(schema.tables.reviews.fields.createdAt, "desc")],
+  source: reviews,
+  orderBys: [orderBy(reviews.fields.createdAt, "desc")],
   limit: 20,
 });
 ```
 
-- `source` is a table of `schema`; `aggregations`, `breakouts`, `filters`, `orderBys`, `limit` and `fields` (the columns to keep) take its fields, its segments and measures, and the metrics of `schema.metrics` as aggregations (`aggregations: [schema.metrics.revenue]`). A field that isn't the table's, or an operator its type doesn't take, fails to compile.
+- `source` is a table of `src/metabase.schema.ts`; `aggregations`, `breakouts`, `filters`, `orderBys`, `limit` and `fields` (the columns to keep) take its fields, its segments and measures, and the file's metrics as aggregations (`aggregations: [revenue]`). A field that isn't the table's, or an operator its type doesn't take, fails to compile.
 - The export's name is the question's name in Metabase, as written (`customerList`).
 - Each `entityId` comes from `mb nano-id` (`mb nano-id --count <n>` for several), never invented or copied. Keep an export's `entityId` when you edit it: a new one replaces the question with another.
 
@@ -97,7 +95,7 @@ A result column's `name` keys the rows and names the column in runtime clauses:
 
 - A column reached through a foreign key keeps its own name (`CATEGORY`, not `PRODUCTS__via__PRODUCT_ID__CATEGORY`).
 - A foreign key that Metabase displays as a name returns that name as an extra column: `USER_ID` comes with a `NAME` column whose `displayName` is "User ID". Show `NAME`; filter by `USER_ID`.
-- A `Date` column's values arrive as ISO strings.
+- A `Date` column's values arrive as ISO strings, though the row type is `string | Date`: format them through `new Date(value)`.
 
 ## Rows: `useMetabaseQuery`
 
@@ -159,7 +157,7 @@ return <StaticQuestion card={card} height={360} />;
 
 ## Runtime clauses
 
-Both hooks take a second argument: one object with the clauses the UI changes, and `enabled`. They run on top of the question and name its columns:
+Both hooks take a second argument: one object with the clauses the UI changes, and `enabled`. They run on top of the question and name its columns. Keep them in a `<Component>.query.ts` file next to the component, so its test mocks the same clauses (`data-app-testing`):
 
 ```tsx
 import { aggregations, filter, orderBy } from "@metabase/embedding-sdk-react/data-app";
@@ -174,7 +172,7 @@ const { query } = useMetabaseQueryObject(orderRows, {
 });
 ```
 
-- A column is `{ type: "column", name }` with a result column's `name`, or a field of `schema`; a wrong name, or an operator its type doesn't take, fails to compile. A date breakout takes a `unit` (`day`, `week`, `month`, `quarter`, `year`).
+- A column is `{ type: "column", name }` with a result column's `name`, or a table's field (`orders.fields.total`); a wrong name, or an operator its type doesn't take, fails to compile. A date breakout takes a `unit` (`day`, `week`, `month`, `quarter`, `year`).
 
   | Column type | Operators                                                                                                             |
   | ----------- | --------------------------------------------------------------------------------------------------------------------- |

package/skill-data/data-app-filters/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-app-filters
-description: Build the filter controls of a Metabase data app — the filter contract, which cards a filter reaches, All by default, options from their own question, a searchable combobox for entities, date presets, `DateRangePopover` and `DateRangeCalendar` with labels from `useDateFormatter`, and a single-date picker. Triggers — "add a filter to the app", "filter the chart by date", "a date range picker", "filter by customer", "a dropdown of categories", "the filter doesn't change the chart", "the date shows the previous day". The query side — runtime clauses and their limits — is in `data-app-data`.
+description: Build the filter controls of a Metabase data app — the filter contract, which cards a filter reaches, All by default, options from their own question, a searchable combobox for entities, date presets, `DateRangePopover` and `DateRangeCalendar` with labels from `useDateFormatter`, and a single-date picker. Triggers — "add a filter to the app", "filter the chart by date", "a date range picker", "filter by customer", "a dropdown of categories", "the filter doesn't change the chart", "the date shows the previous day". The query side — runtime clauses and their limits — is in `data-app-data`; tests are `data-app-testing`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataApps]
 ---
@@ -21,7 +21,7 @@ Before any control, write one row per filter: the question that gives its option
 - A filter in the page's global bar changes every panel that can take it. One that can't reach a panel is scoped to its section, visibly, or left out. A KPI and its detail table about the same thing take the same filters, unless the UI says why not.
 - A KPI on an aggregated question shows one complete bucket (`data-app-data`, _Runtime clauses_): it gets its own control of one-bucket presets starting at the last complete bucket, never All time, rather than a shared bar's ranges.
 - One date control per scope. Never a global date range beside a page-specific date where one of the two does nothing; a page whose cards use another date column gets one control for that column.
-- Build each panel's clauses from its own question's columns, inline at its hook call. Never reuse an array built for another question.
+- Build each panel's clauses from its own question's columns, as a function of the filter state in the panel's `<Component>.query.ts` (`data-app-data`, _Runtime clauses_). Never reuse clauses built for another question.
 
 ## Values and options
 
@@ -57,7 +57,7 @@ import { DateRangePopover, filter, useDateFormatter } from "@metabase/embedding-
 const { formatDateRange } = useDateFormatter();
 const [range, setRange] = useState<[string | null, string | null]>([null, null]);
 const [start, end] = range;
-// at the hook: filters: start && end ? [filter({ type: "column", name: "CREATED_AT" }, "between", [start, end])] : []
+// in the panel's .query.ts: filters: start && end ? [filter({ type: "column", name: "CREATED_AT" }, "between", [start, end])] : []
 
 <DateRangePopover value={range} onChange={setRange}>
   <button className="filter-button">{formatDateRange(range) || "Custom"}</button>
@@ -92,4 +92,6 @@ const lastCompleteMonths = (n: number): [string, string] => {
 
 ## Check
 
-For every visible filter except a KPI's own date control: All runs the unfiltered question, or its All question; its options come from a question; each option changes every panel the contract says it reaches, and no other; a preset bar ends with Custom unless it filters an aggregated question; and no scope has two date controls. Search the filter controls for `<select` and `type="date"` — an action form keeps its date inputs. Then release the app (`data-app`, _Release_).
+For every visible filter except a KPI's own date control: All runs the unfiltered question, or its All question; its options come from a question; each option changes every panel the contract says it reaches, and no other; a preset bar ends with Custom unless it filters an aggregated question; and no scope has two date controls. Search the filter controls for `<select` and `type="date"` — an action form keeps its date inputs.
+
+Every filter gets a unit test: its options question mocked, and each panel it reaches mocked with that panel's clauses for All and for one picked value, checking the panel shows that value's rows after the pick (`data-app-testing`, _Runtime clauses_). The page's Playwright spec picks a value in each filter and checks that a panel it reaches changes (`data-app-testing`, _End-to-end tests_). Then release the app (`data-app`, _Release_).

package/skill-data/data-app-testing/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: data-app-testing
+description: Test a Metabase data app — a unit test next to each component with Vitest, Testing Library and the SDK's `MetabaseTestProvider`, its questions and actions mocked from the exports of `src/metabase.queries.ts` and `src/metabase.actions.ts`, and runtime clauses in a `<Component>.query.ts` file the component and its test share; a Playwright spec per page against the dev preview and real data. Triggers — "test the data app", "add tests", "mock a query", "the test fails with No mock for query", "add an e2e test", "run the Playwright tests". Creating and releasing the app is `data-app`; its hooks are `data-app-data` and `data-app-actions`.
+allowed-tools: Read, Write, Edit, Bash
+requires: [dataApps]
+---
+
+# Testing a data app
+
+## Unit tests
+
+Every component that renders data or runs an action gets a test next to it, `<Component>.test.tsx`. `npm run test:unit` runs them with Vitest, jsdom and Testing Library, with no Metabase instance: `renderWithProviders` in `src/test/render.tsx` wraps the component in `MetabaseTestProvider` from `@metabase/embedding-sdk-react/testing`, and the test passes the answer to every question and action the component runs. Add the app's own providers (theme, router) to `renderWithProviders`; leave the rest of the file as it is. The template's `src/App.test.tsx` checks the starter heading: rewrite it for the app's `App` once the starter page goes.
+
+```tsx
+import { mockDataAppQuery } from "@metabase/embedding-sdk-react/testing";
+import { screen } from "@testing-library/react";
+import { expect, it } from "vitest";
+
+import { ordersList } from "../metabase.queries";
+import { renderWithProviders } from "../test/render";
+
+import { OrdersTable } from "./OrdersTable";
+
+it("shows orders", async () => {
+  renderWithProviders(<OrdersTable />, {
+    dataAppQueries: [mockDataAppQuery(ordersList, [{ ID: 1, STATUS: "paid" }])],
+  });
+
+  expect(await screen.findByText("paid")).toBeInTheDocument();
+});
+```
+
+- Rows are typed from the question's export, and partial: give the columns the test asserts on. The mock answers with the query's columns, and the ones a row leaves out come back as `null`.
+- Assert what the user sees, found by role or text, and wait for data with `findBy…`. Drive interactions with `@testing-library/user-event`.
+- `mockDataAppQueryError` and `mockDataAppActionError` answer with an error, for the error state of a component that runs the query with `useMetabaseQuery` or the action with `useAction`. A query with runtime clauses takes them as the second argument, as `mockDataAppQuery` does: `mockDataAppQueryError(ordersList, ordersByStatus, { status: 500, message: "Query failed" })`.
+- An SDK component such as `StaticQuestion` renders only its children unless the test passes one: `StaticQuestion: () => <p>Revenue chart</p>`. A panel it draws still needs its query mocked, since `useMetabaseQueryObject` resolves it (the rows don't matter); its query runs inside the component, so that panel's error state is the end-to-end tests' to check.
+
+### Runtime clauses: `<Component>.query.ts`
+
+A mock answers a query only when its runtime clauses equal what the component passes (`enabled` aside). So a component keeps its clauses in a `<Component>.query.ts` file next to it, and the component and its test import the same value:
+
+```ts
+// OrdersByStatus.query.ts
+import { aggregations, filter } from "@metabase/embedding-sdk-react/data-app";
+
+export const ordersByStatus = {
+  breakouts: [{ type: "column", name: "STATUS" }],
+  aggregations: [aggregations.count()],
+} as const;
+
+export function ordersWithStatus(status: string) {
+  return { filters: [filter({ type: "column", name: "STATUS" }, "=", status)] } as const;
+}
+```
+
+```tsx
+// OrdersByStatus.tsx
+const { data } = useMetabaseQuery(ordersList, ordersByStatus);
+
+// OrdersByStatus.test.tsx
+renderWithProviders(<OrdersByStatus />, {
+  dataAppQueries: [mockDataAppQuery(ordersList, ordersByStatus, [{ STATUS: "paid", count: 12 }])],
+});
+```
+
+Clauses built from state are a function of that state, as `ordersWithStatus` is: the test mocks the call for each value it selects. A request no mock matches fails with `No mock for query "<entityId>"`: the clauses differ from every mock, or the query has none.
+
+### Actions
+
+```tsx
+import { mockDataAppAction } from "@metabase/embedding-sdk-react/testing";
+import userEvent from "@testing-library/user-event";
+
+import { updateOrder } from "../metabase.actions";
+
+const updateOrderMock = mockDataAppAction(updateOrder, { "rows-updated": 1 });
+
+renderWithProviders(<OrderPage />, { dataAppActions: [updateOrderMock] });
+
+await userEvent.click(screen.getByRole("button", { name: "Mark as refunded" }));
+expect(updateOrderMock.lastCall()?.parameters).toEqual({ id: 1, status: "refunded" });
+```
+
+The response is what the action's kind answers (`data-app-actions`): `created-row` for an insert, `rows-updated` for an update, `rows-deleted` for a delete. `calls()` lists every call, `lastCall()` the latest. A parameter that isn't a column of the action's table, or whose value doesn't match the column's `jsType`, fails the call instead of reaching the mock.
+
+## End-to-end tests
+
+The specs in `e2e/` are Playwright tests against the dev preview (`data-app`, _Dev preview_) and the instance's real data: they check that the pieces fit — every page opens, its questions return rows, its actions exist — not that the numbers are right. `npm run test:e2e` starts the preview, or reuses one already running, so it needs `<repo>/.env.local` like `npm run dev`; the first run on a machine needs `npx playwright install chromium`.
+
+Write one spec per page in `e2e/`. The template's `e2e/app.spec.ts` checks the starter heading: once the starter page goes, make it the first page's spec:
+
+```ts
+import { expect, test } from "@playwright/test";
+
+test("orders page shows warehouse data", async ({ page }) => {
+  await page.goto("orders");
+  await expect(page.getByRole("row")).not.toHaveCount(0);
+});
+
+test("status filter updates orders table", async ({ page }) => {
+  await page.goto("orders");
+  await page.getByRole("combobox", { name: "Status" }).fill("refunded");
+  await page.getByRole("option", { name: "refunded" }).click();
+  await expect(page.getByRole("cell", { name: "paid" })).toHaveCount(0);
+});
+```
+
+- Assert data, not only headings: rows, values and chart contents are what a failed query takes away. Then each interaction — a filter, sorting, a link to another page — and the view it changes.
+- Locate by role and accessible name (`getByRole`, `getByLabel`), as a user finds things. A name matches as a substring unless `exact: true` is passed: "Ship order 12" also finds "Ship order 120".
+- Navigate with relative paths (`page.goto("orders")`, `page.goto("")` for the first page), never `/orders`.
+- An action spec opens the action's form and checks its fields. Submit it only when the user has said the app's database may be written to: a submitted action changes real data.
+- A failure whose cause isn't on the page is in the diagnostics feed (`data-app`, _Dev preview_).
+
+The same specs run in CI, with `DATA_APP_MB_URL` and `DATA_APP_MB_API_KEY` set in the job's environment, against the instance `src/metabase.schema.ts` was generated from: the preview runs each question and action by that instance's numeric IDs. CI installs the SDK from `package.json`, so it needs a published version there: a `file:` path to a local build resolves only on the machine that has it.
+
+## Before handoff
+
+Run `npm run test:unit` and `npm run typecheck` after every round of edits, and `npm run test:e2e` once the pages render data; all three pass before the app is released (`data-app`, _Release_).

package/skill-data/data-app-ui/SKILL.md

@@ -128,4 +128,4 @@ Metabase mirrors each route to `/apps/<slug>/<path>`, and a reload there opens t
 
 ## Before handoff
 
-`npm run dev` only transpiles: run `npm run typecheck` after every round of edits and fix what it reports, and report the result, errors grouped by cause. Search the changed files and fix what turns up: `card={{` (every `card` comes from `useMemo`), `row[0]` and `as unknown as` (rows are keyed by column name), `<select` for a list from a question (`data-app-filters`), `type="date"` and `new Date("` (a date string parsed as UTC) in a date filter, and `* 100` or a number followed by `%` in rendered text (`grep -nE '[0-9}]\s*%'`, then skip CSS sizes such as `"100%"`). Read the diagnostics feed with every panel mounted, then release the app (`data-app`, _Release_).
+`npm run dev` only transpiles: run `npm run typecheck` after every round of edits and fix what it reports, and report the result, errors grouped by cause. Search the changed files and fix what turns up: `card={{` (every `card` comes from `useMemo`), `row[0]` and `as unknown as` (rows are keyed by column name), `<select` for a list from a question (`data-app-filters`), `type="date"` and `new Date("` (a date string parsed as UTC) in a date filter, and `* 100` or a number followed by `%` in rendered text (`grep -nE '[0-9}]\s*%'`, then skip CSS sizes such as `"100%"`). Pass the tests (`data-app-testing`, _Before handoff_) with `npm run dev` running, read the diagnostics feed right after the e2e run, which mounts every panel, then release the app (`data-app`, _Release_).

package/dist/git-sync-BY0dqrLE.mjs

@@ -1,29 +0,0 @@
-import { t as defineCommandGroup } from "./group-DxaqX3Gg.mjs";
-//#region src/commands/git-sync/index.ts
-var git_sync_default = defineCommandGroup({
-	name: "git-sync",
-	description: "Sync Metabase content with a git remote",
-	skills: [{
-		skill: "git-sync",
-		purpose: "import/export round-trip and dirty checks"
-	}],
-	subCommands: {
-		status: () => import("./status-C7_WDust.mjs").then((mod) => mod.default),
-		"is-dirty": () => import("./is-dirty-DgrWNWdj.mjs").then((mod) => mod.default),
-		"has-remote-changes": () => import("./has-remote-changes-CMMXEsXa.mjs").then((mod) => mod.default),
-		dirty: () => import("./dirty-DEsgt8QN.mjs").then((mod) => mod.default),
-		"current-task": () => import("./current-task-CYWaDg5P.mjs").then((mod) => mod.default),
-		"cancel-task": () => import("./cancel-task-0N0qb4_g.mjs").then((mod) => mod.default),
-		wait: () => import("./wait-D9yIDRpl.mjs").then((mod) => mod.default),
-		import: () => import("./import-DZmfmoBw.mjs").then((mod) => mod.default),
-		export: () => import("./export-CikXGxZP.mjs").then((mod) => mod.default),
-		"export-preflight": () => import("./export-preflight-2RkCrd6x.mjs").then((mod) => mod.default),
-		stash: () => import("./stash-CREL1rEx.mjs").then((mod) => mod.default),
-		branches: () => import("./branches-wa3G1T3B.mjs").then((mod) => mod.default),
-		"create-branch": () => import("./create-branch-CQHIvpmr.mjs").then((mod) => mod.default),
-		"add-collection": () => import("./add-collection-Bdnq6dfy.mjs").then((mod) => mod.default),
-		"remove-collection": () => import("./remove-collection-C_nLjEG6.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { git_sync_default as default };

package/dist/table-Be5Vl7JT.mjs

@@ -1,26 +0,0 @@
-import { t as defineCommandGroup } from "./group-DxaqX3Gg.mjs";
-//#region src/commands/table/index.ts
-var table_default = defineCommandGroup({
-	name: "table",
-	description: "Manage Metabase tables",
-	skills: [{
-		skill: "metadata",
-		purpose: "table and column metadata, semantic types, visibility"
-	}],
-	subCommands: {
-		list: () => import("./list-CcFPkvbL.mjs").then((m) => m.default),
-		get: () => import("./get-c5S1A1KR.mjs").then((m) => m.default),
-		fields: () => import("./fields-30XWd-y0.mjs").then((m) => m.default),
-		fks: () => import("./fks-DbCuuP96.mjs").then((m) => m.default),
-		update: () => import("./update-Dmfimhno.mjs").then((m) => m.default),
-		"sync-schema": () => import("./sync-schema-Bw5lh64d.mjs").then((m) => m.default),
-		"rescan-values": () => import("./rescan-values-B_5r6t7K.mjs").then((m) => m.default),
-		"discard-values": () => import("./discard-values-CkGnpZB3.mjs").then((m) => m.default),
-		"bulk-edit": () => import("./bulk-edit-BPFITnRN.mjs").then((m) => m.default),
-		"bulk-sync-schema": () => import("./bulk-sync-schema-C_HNWZpZ.mjs").then((m) => m.default),
-		"bulk-rescan-values": () => import("./bulk-rescan-values-DaeLpv7G.mjs").then((m) => m.default),
-		"bulk-discard-values": () => import("./bulk-discard-values-BHryu-rZ.mjs").then((m) => m.default)
-	}
-});
-//#endregion
-export { table_default as default };