@metabase/cli 0.3.0 → 0.3.1-alpha.transform-tests.3fbcf8b

package/skill-data/core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core
-description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` (add `--json` for machine-readable schemas), and the per-resource footguns (db, table, field, upload, card, dashboard, collection, segment, measure, timeline, alert, subscription, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
+description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` (add `--json` for machine-readable schemas), and the per-resource footguns (db, table, field, upload, content translation, card, dashboard, collection, segment, measure, timeline, alert, subscription, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -11,8 +11,8 @@ The official Metabase CLI (`mb`) drives a Metabase instance over its REST API: a
 Top-level command groups (run `mb <group> --help` to discover verbs):
 
 ```
-auth | db | table | field | upload | query | card | dashboard | snippet | segment | measure | collection | library
-document | timeline | timeline-event | transform | transform-job | transform-tag | alert | subscription | setting
+auth | db | table | field | upload | content-translation | query | card | dashboard | snippet | segment | measure | collection | library
+document | timeline | timeline-event | transform | transform-job | transform-tag | transform-test | alert | subscription | setting
 search | git-sync | setup | eid | uuid | upgrade | skills
 ```
 
@@ -129,8 +129,9 @@ Routine verb shapes (list / get / create / update), every flag, and output schem
 - **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; the underlying query_metadata response also carries FK targets and dimensions, visible under `--full`) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only (`base_type` isn't editable) — this is where you set a column's `semantic_type` or foreign-key target.
 - **upload (CSV → tables).** `upload csv --file <path>` creates a new table + model (prints `{model_id, table_id}`); `upload append <table-id>` / `upload replace <table-id> --file <path>` add to / overwrite a table **previously created by upload** (columns must match). The destination db+schema is admin-configured, not per-call — check with `mb setting get uploads-settings --json` (`db_id: null` ⇒ uploads off/unconfigured; needs admin to read). `--collection <id|root>` only sets the model's collection. Max 50 MB. Errors: **"The uploads database is not configured."** = no db has uploads enabled; **"Uploads are not enabled."** = the append/replace target isn't an uploaded table.
+- **content-translation.** EE-only (`content_translation` premium feature), admin-only, and separate from Remote Sync. `content-translation download > translations.csv` streams the complete active dictionary; `content-translation upload --file translations.csv` replaces every active translation with the file's contents. Always upload the canonical complete CSV, never a partial patch. An empty dictionary downloads as Metabase's four-row sample dictionary — don't re-upload it as real translations. Metabase limits dictionaries to 1.5 MiB.
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql`). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see `visualization`.
-- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body — lay out the whole dashboard in one call: negative ids for new cards, and `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
+- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). Every dashcard must include `card_id`, including existing rows; use `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create` accepts the **same** `dashcards` array in its initial body, so lay out the whole dashboard in one call. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
 - **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop and omitting a parameter deletes it. A parameter only filters a card once it is **mapped** onto that dashcard's `parameter_mappings` — an unmapped parameter is an inert widget. `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the full allowed set back to you. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches a widget's selectable values (`{values, has_more_values}`; `--query` is a case-insensitive substring search). Parameter types, ids, mapping targets, and value sources → the `dashboard` skill; load it before authoring a `parameters` array.
 - **alert / subscription are two unrelated systems.** `alert` watches one **card** and fires on a send condition (`/api/notification`: a cron string, `channel/email`-prefixed handlers, typed recipients); `subscription` delivers one **dashboard** on a schedule (`/api/pulse`: structured `schedule_type` + hour/day/frame, bare `email` channels, `{id}|{email}` recipients). The bodies are not interchangeable. Both silently deliver nowhere if the server has no SMTP / Slack app — check `mb setting get 'email-configured?'` (quote it; the `?` is a shell glob) before creating either. Their list-valued fields (`handlers`/`subscriptions`, `channels`/`cards`) **replace wholesale** on update, so adding one recipient is a read-modify-write. `mb card alerts <id>` and `mb dashboard subscriptions <id>` list what's already attached to a card/dashboard; `archive` deactivates rather than deletes. Load the `notification` skill before authoring either body.
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same for `--filter archived` on dashboard/collection.)
@@ -139,7 +140,7 @@ Routine verb shapes (list / get / create / update), every flag, and output schem
 - **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id; anything else is a client-side `ConfigError`. `collection items` pages the server endpoint, pulling only as far as the output cap can show — read `has_more`/`next_offset` to continue. `collection tree` is **JSON-only** (`--format text` is rejected). A transform collection needs `collection create --namespace transforms`.
 - **setting set** parses the value as **strict JSON**: a string is `'"value"'` (inner quotes), booleans `true`/`false`, numbers bare. Wrong quoting silently errors — confirm with `setting get <key>` after. `setting get --json` works on every value type (wrapping bare-text responses into `{key, value}`).
 - **search vs. list.** For plain enumeration of cards/dashboards/collections use the dedicated `… list` verbs; reach for `search --models <kind>` only for ranking against a query string or a cross-resource lookup.
-- **transform.** Iterate with `transform update <id>`, never `delete` + `create` (keeps the row, `entity_id`, materialized table, and YAML filename — avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. (→ `transform`.)
+- **transform.** Iterate with `transform update <id>`, never `delete` + `create` (keeps the row, `entity_id`, materialized table, and YAML filename — avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. `transform-test run <id>` checks a transform against fixtures in temp tables — no real table is read — and exits non-zero unless it passes (v64+). (→ `transform`.)
 - **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
 - **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json`. Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help) — for those, use `--body '{"entity_ids":{"card":["-…"]}}'` (the id is a JSON string value, immune to flag parsing).
 - **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder — it's how you tell people (and agents) "start from these, they're trusted." `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent** (no collection id to find); each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. Publish status shows on the table: `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Good candidates are finished, analysis-ready tables — clean/combine via transforms first, then publish the polished result. Publishing does not put the Data collection in the git-sync scope: on a remote-sync instance, `mb git-sync add-collection <data-collection-id>` is what makes exports carry the published tables' metadata (see the `git-sync` skill).

package/skill-data/dashboard/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 A dashboard starts as cards on a grid; it becomes an **app** when filters drive the cards, charts cross-filter each other, and clicks navigate. This skill owns both: the grid layout and the interactive layer.
 
-**`core` owns the transport mechanics** — the whole-array replace semantics (editing `dashcards` or `parameters` replaces the entire set; omitted entries are deleted; new cards use negative ids), `update-dashcard` for a single safe patch vs. `update --body` for a full replace, and the `parameter-values` verb. Read it first (`mb skills get core`). **`visualization`** owns each card's chart and the full `click_behavior` key catalog.
+**`core` owns the transport mechanics** — the whole-array replace semantics (editing `dashcards` or `parameters` replaces the entire set; omitted entries are deleted; every dashcard carries `card_id`, with `null` for virtual cards; new cards use negative ids), `update-dashcard` for a single safe patch vs. `update --body` for a full replace, and the `parameter-values` verb. Read it first (`mb skills get core`). **`visualization`** owns each card's chart and the full `click_behavior` key catalog.
 
 Inspect before you wire: `mb dashboard get <id> --json` hydrates `parameters`, `dashcards`, and `tabs`; `mb dashboard cards <id>` lists just the dashcards.
 
@@ -123,7 +123,7 @@ Set the **driver** chart's whole-card click behavior to `crossfilter`, mapping t
 - **Auto-connect / the missing map:** a filter that "does nothing" or "won't show" is almost always unmapped, or mapped only to cards on another tab.
 - **Time-grouping parameters** (`temporal-unit`) bind only to a datetime column in the query's **last** stage — add one after a time-bucketed summary and it can't attach.
 - **Required + default:** a `required: true` parameter with no `default` blocks its cards until a value is chosen; give it a `default` for expensive queries you don't want running unfiltered.
-- **Whole-array replace:** never send a partial `parameters`/`dashcards` array to `update` — you'll delete what you omit. Use `update-dashcard` for a single-card change.
+- **Whole-array replace:** never send a partial `parameters`/`dashcards` array to `update` — you'll delete what you omit. Include `card_id` on every dashcard (`null` for virtual cards). Use `update-dashcard` for a single-card change.
 
 ## Don't
 

package/skill-data/transform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: transform
-description: Author and run Metabase transforms via `mb` — body shape (native SQL or structured MBQL), create + run-with-wait, run inspection, dependencies, cancel, the `update`-vs-recreate iteration rule, the writable-keys-only PATCH contract, plus transform tags and tag-driven transform-job schedules. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "list transform runs", "cancel a running transform", "manage transform tags", "run a transform job", or anything `mb transform …` / `mb transform-job …` / `mb transform-tag …`.
+description: Author and run Metabase transforms via `mb` — body shape (native SQL or structured MBQL), create + run-with-wait, run inspection, dependencies, cancel, the `update`-vs-recreate iteration rule, the writable-keys-only PATCH contract, transform tests (fixtures and expectations run against temp tables), plus transform tags and tag-driven transform-job schedules. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "test a transform", "list transform runs", "cancel a running transform", "manage transform tags", "run a transform job", or anything `mb transform …` / `mb transform-job …` / `mb transform-tag …` / `mb transform-test …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -172,6 +172,60 @@ mb transform run "$ID" --wait --profile <n> --json     # → succeeded
 
 If you really must `create + delete` instead, do the `delete` **before** the first `git-sync export` so the failed entity never lands in git history — an export of a soft-failed state is noise that needs a follow-up cleanup commit. See `git-sync`, "Read state before mutating", for the ordering rule.
 
+## Transform tests (v64+)
+
+A transform test replaces every table the transform reads with a fixture, runs it into a temp table, and checks that output. No real table is read or written.
+
+```bash
+mb transform-test list --transform <id> --profile <n> --json  # --transform is optional
+mb transform-test get <id> --full --profile <n> --json        # --full for inputs/expectations
+mb transform-test create --file ./.scratch/test.json --profile <n> --json
+mb transform-test update <id> --file ./.scratch/patch.json --profile <n> --json
+mb transform-test delete <id> --yes --profile <n>
+mb transform-test run <id> --profile <n> --json               # exits non-zero unless it passes
+```
+
+**`inputs`** — one per table the transform reads, each naming a `table` plus either `format: "sql"` with `sql`, or `format: "rows"` with `columns` (each a `name` and a `database_type` the warehouse takes as a `CAST` target) and `rows`.
+
+**`expectations`** — `type: "empty"` with the `sql` that must return no rows, or `type: "equals"`, which needs the same `format` split as an input (`"rows"` with `columns`/`rows`, or `"sql"` with a query). An `equals` without a `format` is refused.
+
+```json
+{
+  "transform_id": 1,
+  "name": "adults only",
+  "inputs": [
+    {
+      "table": { "schema": "public", "name": "people" },
+      "format": "rows",
+      "columns": [
+        { "name": "id", "database_type": "INTEGER" },
+        { "name": "age", "database_type": "INTEGER" }
+      ],
+      "rows": [
+        { "id": 1, "age": 30 },
+        { "id": 2, "age": 12 }
+      ]
+    }
+  ],
+  "expectations": [
+    {
+      "type": "equals",
+      "name": "exactly one row, id 1",
+      "format": "rows",
+      "columns": [{ "name": "id", "database_type": "INTEGER" }],
+      "rows": [{ "id": 1 }]
+    },
+    {
+      "type": "empty",
+      "name": "no null ids",
+      "sql": "SELECT * FROM public.adults WHERE id IS NULL"
+    }
+  ]
+}
+```
+
+Create and update bodies are closed — strip `id`, `entity_id`, `creator_id`, `created_at` and `updated_at` from a `get --full` body before sending it back.
+
 ## Drop the materialized table (keep the transform)
 
 ```bash

package/dist/git-sync-MQQYRYLg.mjs

@@ -1,28 +0,0 @@
-import { t as defineCommandGroup } from "./group-DBM87IgC.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-BhswxJL1.mjs").then((mod) => mod.default),
-		"is-dirty": () => import("./is-dirty-DYeJYhBz.mjs").then((mod) => mod.default),
-		"has-remote-changes": () => import("./has-remote-changes-C684Redh.mjs").then((mod) => mod.default),
-		dirty: () => import("./dirty-DNYoM6Bp.mjs").then((mod) => mod.default),
-		"current-task": () => import("./current-task-MpBFGttd.mjs").then((mod) => mod.default),
-		"cancel-task": () => import("./cancel-task-C5CU1pxU.mjs").then((mod) => mod.default),
-		wait: () => import("./wait-DoMDH226.mjs").then((mod) => mod.default),
-		import: () => import("./import-Rmmttboo.mjs").then((mod) => mod.default),
-		export: () => import("./export-BjfoZRDJ.mjs").then((mod) => mod.default),
-		stash: () => import("./stash-D0S4JmAz.mjs").then((mod) => mod.default),
-		branches: () => import("./branches-DchlyU0i.mjs").then((mod) => mod.default),
-		"create-branch": () => import("./create-branch-CYo6jZth.mjs").then((mod) => mod.default),
-		"add-collection": () => import("./add-collection-B3Ty8SzB.mjs").then((mod) => mod.default),
-		"remove-collection": () => import("./remove-collection-BOnxYvhj.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { git_sync_default as default };

package/dist/transform-Bs0EWijQ.mjs

@@ -1,28 +0,0 @@
-import { t as defineCommandGroup } from "./group-DBM87IgC.mjs";
-//#region src/commands/transform/index.ts
-var transform_default = defineCommandGroup({
-	name: "transform",
-	description: "Manage Metabase transforms",
-	skills: [{
-		skill: "transform",
-		purpose: "body shape, run-with-wait, iterate"
-	}, {
-		skill: "mbql",
-		purpose: "MBQL source.query bodies"
-	}],
-	subCommands: {
-		list: () => import("./list-C5Zs8nrb.mjs").then((mod) => mod.default),
-		get: () => import("./get-ByBOq30r.mjs").then((mod) => mod.default),
-		dependencies: () => import("./dependencies-Bj3QrGIm.mjs").then((mod) => mod.default),
-		create: () => import("./create-DJmXXQoq.mjs").then((mod) => mod.default),
-		update: () => import("./update-BCS5FxKr.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-Ck0q4Dzp.mjs").then((mod) => mod.default),
-		"delete-table": () => import("./delete-table-DuyhGrvA.mjs").then((mod) => mod.default),
-		run: () => import("./run-C3DkS6NP.mjs").then((mod) => mod.default),
-		cancel: () => import("./cancel-BMQa5R1Z.mjs").then((mod) => mod.default),
-		"get-run": () => import("./get-run-Cnux9ln0.mjs").then((mod) => mod.default),
-		runs: () => import("./runs-CUNWiidL.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { transform_default as default };

package/dist/transform-job-BcLChRup.mjs

@@ -1,22 +0,0 @@
-import { t as defineCommandGroup } from "./group-DBM87IgC.mjs";
-//#region src/commands/transform-job/index.ts
-var transform_job_default = defineCommandGroup({
-	name: "transform-job",
-	description: "Manage Metabase transform jobs",
-	skills: [{
-		skill: "transform",
-		purpose: "tag-driven job schedules"
-	}],
-	subCommands: {
-		list: () => import("./list-BzVTHOoH.mjs").then((mod) => mod.default),
-		get: () => import("./get-DRvsATp-.mjs").then((mod) => mod.default),
-		create: () => import("./create-Beh-2uoN.mjs").then((mod) => mod.default),
-		update: () => import("./update-CmDTljK-.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-DFmX7jTp.mjs").then((mod) => mod.default),
-		run: () => import("./run-DdGJ544X.mjs").then((mod) => mod.default),
-		transforms: () => import("./transforms-oU4zizbO.mjs").then((mod) => mod.default),
-		"set-active": () => import("./set-active-BD8L1lPX.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { transform_job_default as default };