@metabase/rde 0.1.6 → 0.1.7

package/README.md

@@ -30,7 +30,7 @@ The wizard shows its checklist first (`✓` done, `○` to do, `–` not applica
 ┌  rde init
 ✓ Check this machine
 ○ Install the Metabase CLI
-○ Install the rde skill for your coding agents
+○ Install the rde and data-app skills for your coding agents
 ○ Install Metabase
 ○ Start Metabase
 ○ Create the admin user
@@ -54,7 +54,7 @@ The git step reads `–` until a license with remote sync is active; it is check
 | --- | --- |
 | Check this machine | Platform, Node version, git, and a reachable Docker daemon or a Java 21+ runtime |
 | Install the Metabase CLI | `@metabase/cli` (`mb`) at the `alpha-fix-transform-test-ee-path` dist-tag, with the package manager that installed `rde` |
-| Install the rde skill | The `rde` skill from the `rde-skill` branch of `metabase/agent-skills` for the coding agents you pick at a terminal, from the ones found on this machine (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf) plus OpenCode, which is always offered: picked while missing, it is installed first (`opencode-ai` with the package manager that installed `rde`). Without a terminal, or with `--yes`, every agent found gets the skill; `--agents` picks a set ahead of time (`opencode` in it is installed when missing), `--skip-agents` none; `RDE_SKILL_SOURCE` installs it from another URL or a local directory |
+| Install the rde and data-app skills | The data-app skills (`metabase-data-app-setup`, `-routing`, `-actions`, `-semantic-layer`) from `metabase/metabase/skills#master`, then the `rde` and `rde-data-apps` skills from the `rde-generic-skills` branch of `metabase/agent-skills` (the rde skill hands an explicit app request to `rde-data-apps`, which hands the build to the data-app skills), for the coding agents you pick at a terminal, from the ones found on this machine (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf) plus OpenCode, which is always offered: picked while missing, it is installed first (`opencode-ai` with the package manager that installed `rde`). Without a terminal, or with `--yes`, every agent found gets the skills; `--agents` picks a set ahead of time (`opencode` in it is installed when missing), `--skip-agents` none; `RDE_SKILL_SOURCE` installs the two rde skills from another URL or a local checkout of `metabase/agent-skills` |
 | Install Metabase | **Docker** when it is available: pulls `metabase/metabase-enterprise-head:latest` (or `--image`) and creates the container. **Jar** otherwise, or with `--runtime jar`: downloads the latest enterprise release (or the tag or `.jar` path given as `--jar`) into `~/.rde/jars/` and runs it with your Java. Either way on port 3100, or the first free port above it, or `--port` |
 | Start Metabase | Starts the container or the jar and waits for `/api/health`, showing Metabase's own progress |
 | Create the admin user | `admin@metabase.local` with a generated password that `rde credentials` shows, or your own with `--admin prompted`, see [Credentials](#credentials) |
@@ -71,7 +71,7 @@ The second run on the same machine detects every step as done and prints the sum
 ┌  rde init
 ✓ Check this machine
 ✓ Install the Metabase CLI
-✓ Install the rde skill for your coding agents
+✓ Install the rde and data-app skills for your coding agents
 ✓ Install Metabase
 ✓ Start Metabase
 ✓ Create the admin user
@@ -95,14 +95,14 @@ The second run on the same machine detects every step as done and prints the sum
 │  rde skill: installed for Claude Code                                              │
 │  Start working:                                                                    │
 │    claude  (Claude Code)                                                           │
-│  Lifecycle: rde status, rde stop, rde start                                        │
+│  Lifecycle: rde status (--json for scripts), rde stop, rde start                   │
 │                                                                                    │
 ├────────────────────────────────────────────────────────────────────────────────────╯
 │
 └  rde init finished
 ```
 
-Ctrl-C at any prompt stops the run; `rde init` again continues from the first step that is not done. `rde init --from license` re-runs from a step on, `rde init --only databases` runs one step.
+Ctrl-C at any prompt stops the run; `rde init` again continues from the first step that is not done. A step that fails ends the run with exit code 1 (2 for a missing answer) and a last line naming the step and the command that resumes there: `rde init stopped at "Connect a sample database": <reason>. Resume with rde init --from sample-database.` `rde init --from license` re-runs from a step on, `rde init --only databases` runs one step.
 
 ## The sample database
 
@@ -122,7 +122,7 @@ The admin user is `admin@metabase.local` with a password `rde` generates: 32 ran
 Login: admin@metabase.local (rde credentials shows the password)
 ```
 
-`rde credentials` prints the Metabase URL, the email, and the password, wherever its output goes, so a coding agent you ask for the login can run it and tell you; `rde credentials --json` prints the same as an object (`url`, `email`, `password`, and a `note`). Nothing else prints the password: not the summary, `rde status` (text or `--json`), `rde doctor`, a log, or an error message. To use your own login instead, run `rde init --admin prompted` (or pass `--admin-email` / `--admin-password`, or an `admin-user` section in the answers file): the email and password are asked once, sent to Metabase, and never written anywhere by `rde`, and `rde credentials` says so.
+`rde credentials` prints the Metabase URL, the email, and the password, wherever its output goes, so a coding agent you ask for the login can run it and tell you; `rde credentials --json` prints the same as an object (`url`, `email`, `password`, and a `note`). `rde credentials --api-key` prints the API key and nothing else, for a script to hand to another tool without showing it, such as the `DATA_APP_MB_API_KEY` a data app reads from its repository's `.env.local`. Nothing else prints the password: not the summary, `rde status` (text or `--json`), `rde doctor`, a log, or an error message. To use your own login instead, run `rde init --admin prompted` (or pass `--admin-email` / `--admin-password`, or an `admin-user` section in the answers file): the email and password are asked once, sent to Metabase, and never written anywhere by `rde`, and `rde credentials` says so.
 
 In both variants `rde` creates an API key named `rde` in the Administrators group and keeps it in the same secrets file. That key is what `mb` and `rde` itself use afterwards; `state.json` and `rde status --json` never carry it. If Metabase stops accepting it (someone regenerated or revoked it in the admin settings), `rde init --only api-key` or `rde doctor --fix` makes a new one with the stored admin login and logs `mb` in again, asking nothing; with a prompted admin it asks for the password once.
 
@@ -151,7 +151,7 @@ The sample database's own credentials (`metabase` / `metasample123`) are baked i
 
 Three things are never written to disk or to a log by `rde`: the license token (it goes to Metabase, which keeps it in its own application database), a password you typed for a prompted admin user, and a git access token for a hosted remote (Metabase encrypts it on its side). The `mb` profile lives where `mb` keeps its profiles, under `$XDG_CONFIG_HOME` or `~/.config`.
 
-The instance listens on `127.0.0.1` only (the container's published port, or the jar's `MB_JETTY_HOST`), so it is reachable from this machine and from nothing else on the network; the sample database's container is published the same way. Two containers belong to the instance: `rde-metabase-default` (Metabase, with `data/` mounted) and `rde-sampledb-default` (Postgres, no mount).
+The instance listens on `127.0.0.1` only (the container's published port, or the jar's `MB_JETTY_HOST`), so it is reachable from this machine and from nothing else on the network; the sample database's container is published the same way. Two containers belong to the instance: `rde-metabase-default` (Metabase, with `data/` mounted) and `rde-sampledb-default` (Postgres, no mount). Those are the names under `~/.rde`; with `RDE_HOME` set to another directory both names end in a tag derived from that directory, such as `rde-metabase-default-3fa9c1d2`, so two homes never share a container.
 
 ### Docker or jar
 
@@ -163,12 +163,12 @@ Docker is used whenever it is available: the image is self-contained, and the co
 | --- | --- |
 | `rde start` | Starts the sample database and the instance, and waits until Metabase is healthy |
 | `rde stop` | Stops both; the data stays |
-| `rde status` | The login email, the `mb` profile, the init checklist, runtime state, health, databases with their sync state, the sample database's container and connection string, remote sync state; `--json` for scripts and agents (`mbProfile`, `adminEmail`, never a secret) |
-| `rde credentials` | The Metabase URL, admin email, and password; `--json` for scripts and agents |
+| `rde status` | The login email, the `mb` profile, the init checklist, whether setup is complete (or the first step `init` did not finish, with the `rde init --from` command that resumes there), runtime state, health, databases with their sync state, the sample database's container and connection string, remote sync state and the content repository's working directory (`contentRepository`); `--json` for scripts and agents (`mbProfile`, `adminEmail`, `setup`, never a secret); exit 0 whatever it reports |
+| `rde credentials` | The Metabase URL, admin email, and password; `--json` for scripts and agents; `--api-key` for the API key alone |
 | `rde logs` | The container's log, or the jar's `metabase.log`; `-f` keeps streaming |
 | `rde open` | Opens the instance in the browser |
 | `rde db add` | The database wizard: pick the engine, paste a connection string or fill the fields, review, test, add |
-| `rde db list` | The connected databases; `--json` for scripts |
+| `rde db list` | The connected databases; `--json` for scripts; a bare `rde db` does the same |
 | `rde doctor` | One table of checks with a fix hint per failure; `--fix` re-runs the init steps behind them; `--json` for scripts and the rde skill (every row's `id`, `status`, `detail`, `hint`, and `fix`: the `rde` command that repairs it, or null when you have to act); exit 1 while anything fails |
 | `rde upgrade` | Moves the instance to a newer Metabase after backing up its data; see [Upgrading](#upgrading) |
 | `rde uninstall` | Removes the instance, its data, and the `mb` profile; see [Resetting](#resetting) |
@@ -196,7 +196,7 @@ With a license that includes remote sync, the last step connects a git repositor
 - **Local remote inside `~/.rde`** (default): a bare repository at `instances/default/data/content.git`, mounted into the container and reached as `file:///rde/content.git`. No account, no token. Your working directory gets it as `origin` (or as `rde-remote` when `origin` already points elsewhere).
 - **Hosted remote**: a GitHub, GitLab, or Bitbucket `https://` URL plus a token with read and write access. `rde` tests the connection through Metabase before saving anything.
 
-A repository that already holds Metabase content is imported on the spot. Afterwards:
+A fresh repository gets a first commit with a `README.md` and a `.gitignore` that keeps out what a data app built in it must not push: `.env`, `.env.local`, `.env.*.local`, `node_modules/`, `.vite/`, the rde skill's `.scratch/`, and `.DS_Store` (a data app's built `dist/` stays tracked, since that bundle is what Metabase serves); a `.gitignore` already there keeps its lines and gets the missing ones, and a repository that already has commits is left as it is. A repository that already holds Metabase content is imported on the spot. Afterwards:
 
 ```sh
 cd <your working directory>
@@ -220,13 +220,13 @@ rde init --skip-license \
 | Flag | Answers |
 | --- | --- |
 | `--agents claude-code,codex` / `--skip-agents` | Which agents get the skill, instead of asking at a terminal or taking the ones found on the machine; a missing `opencode` is installed |
-| `--runtime docker\|jar`, `--image`, `--jar`, `--port` | How Metabase runs, the Docker image or the jar (`latest`, a release tag, or a `.jar` path), and the host port, instead of Docker when available, `metabase/metabase-enterprise-head:latest`, the latest release, and the first free port from 3100; `--image` implies `docker` and `--jar` implies `jar` |
+| `--runtime docker\|jar`, `--image`, `--jar`, `--port` | How Metabase runs, the Docker image or the jar (`latest`, a release tag, or a `.jar` path), and the host port, instead of Docker when available, `metabase/metabase-enterprise-head:latest`, the latest release, and the first free port from 3100; `--image` implies `docker` and `--jar` implies `jar`; the sample database always runs in Docker |
 | `--admin generated\|prompted`, `--admin-email`, `--admin-password` | The admin user, `generated` unless given; an email or password implies `prompted` |
 | `--license-token` / `--skip-license` | The license |
-| `--database <engine>=<connection string>` (repeatable) / `--skip-databases` | The warehouses |
+| `--database <engine>=<connection string>` (repeatable) / `--skip-databases` | Your own databases; `--skip-databases` connects none of them, and the sample database is still connected |
 | `--git-dir`, `--git-remote local\|hosted`, `--git-url`, `--git-token` / `--skip-git` | The content repository; a remote or URL without `--git-dir` means the current directory |
 | `--mb-profile default\|rde` | The `mb` profile when `default` already points at another Metabase; `default` (replace it) unless given |
-| `--yes` | Every confirmation (skipping databases), and the recommended choice of a question (replacing `default`) |
+| `--yes` | Every confirmation, and the recommended choice of a question (replacing `default`); skips the question about your own databases, and the sample database is still connected |
 
 A secret flag (`--admin-password`, `--license-token`, `--git-token`) takes `-` to read one line from stdin, the way `mb auth login` takes its key, or a literal `$VAR` (single-quoted, so the shell leaves it alone) to read the environment; either keeps the value out of your shell history and process listings. Only one flag can read stdin.
 
@@ -284,11 +284,11 @@ If Metabase does not become healthy on the new version, nothing is rolled back a
 ```sh
 rde uninstall                  # container or process, mb profile, ~/.rde/instances/default
 rde uninstall --keep-data      # container or process and profile only; the data and secrets.json stay, and `rde init` reinstalls from them
-rde uninstall --remove-skill   # also the rde skill from your coding agents
+rde uninstall --remove-skill   # also the rde skills from your coding agents
 rde uninstall --remove-image   # also the Docker images or the downloaded jar (otherwise they stay for the next init)
 ```
 
-Running it twice is a no-op. It also works with no `~/.rde` at all, so a leftover `rde-metabase-default` or `rde-sampledb-default` container, a Metabase process recorded in a stray pid file, or an `mb` profile from a half-finished run is cleaned up the same way. Anything it could not remove is listed at the end and the command exits with 1.
+Running it twice is a no-op. It also works with no `~/.rde` at all, so a leftover `rde-metabase-default` or `rde-sampledb-default` container, a Metabase process recorded in a stray pid file, or an `mb` profile from a half-finished run is cleaned up the same way. A container labelled with another `RDE_HOME` is left alone, and the warning names that home. Anything it could not remove is listed at the end and the command exits with 1.
 
 ## Troubleshooting
 
@@ -347,7 +347,7 @@ Start Docker (or `colima start`), or install Java, and run `rde init` again. `rd
                    plain `mb` uses prod (MB_PROFILE): prod.acme.example
 ```
 
-**The agent follows an old copy of the skill.** The `rde skill copies` row lists every copy of the skill the `skills` CLI knows, global and in the current directory's project, with where it came from, and fails when one did not come from rde's source (the branch is read from the `skills` lock file; against a local `RDE_SKILL_SOURCE` the copy's `SKILL.md` is compared). With several copies it says which one Claude Code started in that directory loads (a personal skill wins over a project one). `rde init --only agents-skills` reinstalls the global copy; restart the agent session afterwards.
+**The agent follows an old copy of the skill.** The `rde skill copies` row lists every copy of the skill the `skills` CLI knows, global and in the current directory's project, with where it came from, and fails when one did not come from rde's source (the branch is read from the `skills` lock file; against a local `RDE_SKILL_SOURCE` the copy's `SKILL.md` is compared with the checkout's `skills/rde/SKILL.md`). With several copies it says which one Claude Code started in that directory loads (a personal skill wins over a project one). `rde init --only agents-skills` reinstalls the global copy; restart the agent session afterwards.
 
 **The license token is rejected.** Activation ends with `Metabase reports the token as invalid` (or another status Metabase returned). Check the token, and check that the container can reach `token-check.metabase.com`: activation needs outbound network access. Run `rde init --from license` to try again; press Enter at the prompt to skip the license and carry on without remote sync.
 
@@ -357,7 +357,7 @@ Start Docker (or `colima start`), or install Java, and run `rde init` again. `rd
 bun install
 bun run check                 # tsc, oxlint + boundary linter, oxfmt, unit tests
 bin/rde-dev init              # runs from source with RDE_HOME and the mb config under .dev-state/
-RDE_SKILL_SOURCE=~/agent-skills/skills/rde bin/rde-dev init --only agents-skills   # the skill from a local checkout
+RDE_SKILL_SOURCE=~/agent-skills bin/rde-dev init --only agents-skills   # the rde skills from a local checkout
 ```
 
 The end-to-end lane runs the built binary against real Docker: a seeded Postgres 16 sidecar on `127.0.0.1:15432` (`RDE_E2E_PG_PORT` to change it) and a fresh instance under `.e2e-state/`, with a fake `HOME` so the skill installer never touches your agents. `bun run build` must precede `bun run test:e2e`, and `python3` must be on `PATH`: the lane answers one `init` question through a pseudo-terminal it opens with Python's `pty` module. With `RDE_E2E_JAR` pointing at a Metabase jar (a local build) the lane also runs the jar runtime through init, doctor, stop, start, and uninstall with the host's Java; without it those tests are reported as skipped.