rde-data-apps

rde-data-apps

A data app is a React bundle Metabase serves at /apps/<slug> from data_apps/<slug>/ in the repository connected through remote sync. The metabase-data-apps skill builds it. This skill answers its questions from what rde already knows, so the user is asked only what rde cannot know, makes sure the content the app reads is in that repository before the app is built, then hands over. Sections 4 to 6 override the data-apps skill wherever they differ: the schema scope, the order of commits and pushes, and the confirmation before any sync.

1. The instance

rde status --json: url is the instance (not a secret) and version must be v65+ or a head build. mb auth list --json names the profile whose url matches; use it as $PROFILE. Metabase serves apps only under a license with remote sync and data apps: rde doctor --json, row license. Without one, the user activates it in their own terminal with rde init --only license (or ! rde init --only license in this session); the token never enters the chat. Syncing content needs remote-sync-type set to read-write (mb setting get remote-sync-type --json); switching it is a sync change, confirmed like one (section 6).

2. The repository

contentRepository in rde status --json is the working directory of the remote-sync repository, and the answer to Step 1 of the metabase-data-apps setup guide: name it and use it, do not ask. When it is null and the license has remote sync, ask where the repository should live, then run rde init --only git-sync --git-dir <path> --git-remote local (a bare remote inside ~/.rde, no account). A hosted remote needs a git token, so the user runs rde init --only git-sync themselves. A repository rde creates already ignores .env.local, node_modules/, and the rest a data app must not push.

3. The credentials

The data-apps skill reads DATA_APP_MB_URL and DATA_APP_MB_API_KEY from .env.local at the repository root and forbids the key in the conversation. rde stores the API key mb uses, and rde credentials --api-key prints it alone. When its setup guide reaches the credentials step, or its check prints MISSING, fill the file with this command instead of asking the user, <url> from step 1 and <repo> from step 2. It prints only creds written, keeps the file's other lines, and makes sure .env.local is ignored:

ROOT="$(git -C "<repo>" rev-parse --show-toplevel)" && KEY="$(rde credentials --api-key)" &&
{ grep -qxF .env.local "$ROOT/.gitignore" 2>/dev/null || echo .env.local >> "$ROOT/.gitignore"; } &&
{ if [ -f "$ROOT/.env.local" ]; then grep -v -e '^DATA_APP_MB_URL=' -e '^DATA_APP_MB_API_KEY=' "$ROOT/.env.local"; fi
  printf 'DATA_APP_MB_URL=%s\nDATA_APP_MB_API_KEY=%s\n' "<url>" "$KEY"; } > "$ROOT/.env.local.tmp" &&
mv "$ROOT/.env.local.tmp" "$ROOT/.env.local" && chmod 600 "$ROOT/.env.local" && echo "creds written"

Never run rde credentials --api-key where its output comes back to you, and never print .env.local. The key belongs to rde's admin, so the dev preview sees every table; say so when the app is meant for a narrower audience.

4. The repository is the source of truth

A data app exists only through remote sync, so here it is a requirement, not a suggestion: section 2 sets it up when it is missing, and that is the only place rde proposes remote sync unprompted, because the user asked for an app. Record it in STATE.md as remote_sync. Outside an app, the rde skill raises syncing only when remote sync is already configured.

The bundle refers to Metabase objects by id and through the typed schema. An app built on content that lives only in the instance works there and nowhere else: importing the repository into another instance brings the app without the definitions it reads, and its queries fail. So everything the app reads is in the repository before the app is built, and everything the build creates goes there with the app.

• What the app may read. Library-published tables with their field metadata, measures, and segments; metrics filed in the Library's Metrics collection; models whose actions the app runs, in a synced collection. Nothing else.
• What "in the repository" means. The Library collections carry is_remote_synced: true (synced_collections in mb git-sync status --json), the content has been exported, and git pull has brought it into the working tree: the files are there under databases/…/tables/<table>/ and collections/…, checked, not assumed.
• Measures and segments need a published table (the rde skill's references/remote-sync.md, "What belongs in git"). Without the Library (mb library get --json fails), file metrics in a synced collection and say that measures and segments cannot be carried.
• The app's own collection is synced too. npm run build runs sync-resources, which saves each queries/ definition as a question in Data App: <slug>. Flag that collection for sync with the app, and after every build that creates or changes questions, mb git-sync dirty --json lists them for export. If they never appear there, say so in the hand-back rather than working around it.
• Schema scope. Generate metabase.data.ts from Library scopes only: include-data-library=true, include-metric-library=true, or library-collections=<ids>, plus include-models=true when the app runs actions. Never database=<id>: it reads tables straight off the instance, synced or not, and is how an app ends up built on content the repository does not have.
• A missing entity found mid-build (a measure, a segment, a metric, a published table, an action) goes back to the rde skill: create it in the Library, pass its gate, sync it (sections 5 and 6), git pull, regenerate the schema, then continue. Never create it ad hoc to unblock the UI.
• Before the first line of app code, every entity the app needs is in the schema generated from Library scopes and its file is in the working tree. When one is missing, stop and go back to rde.

5. Syncing safely

Remote sync merges nothing and resolves no conflicts. The instance side (what to check before every import or export, which goes first, never --force without the user's yes) and the staging hand-back: the rde skill's references/remote-sync.md, "Before each step" and "Staging". Here a git push behind a Metabase export is rejected too, and two writers push to the same remote, Metabase's export and the app's commits, so keep them in step:

• Working-tree side. The app's commits touch only data_apps/<slug>/; exported Metabase YAML is never edited by hand. Before pulling a Metabase export: git stash --include-untracked, git pull --ff-only, git stash pop. Before every git push: git pull --ff-only again. A pull that cannot fast-forward is a stop: report both histories, do not merge or force.
• Delivery order, each step starting from a clean state: npm run build (may create app questions) → export the instance's dirty set (the app's questions and any new definition) → stash, pull, pop in the working tree → commit the app, resources_metadata.json included → pull, push → mb git-sync import → open <url>/apps/<slug>.
• Branch. The instance tracks one branch (mb git-sync status --json, branch). Export or push to main or master only with an explicit yes; otherwise mb git-sync create-branch agent/<slug> and push the app to the same branch, so the content and the app travel together.

6. Ask before anything touches sync

Every sync step, every git push to the synced remote included, is approved first, one checkpoint per sync point: the rde skill's references/remote-sync.md, "Ask before every sync step". "Yes for the rest of this job" is recorded and not asked again; anything less is asked again at the next sync point.

"Not now" before the build leaves one path: a dev preview only, labelled as working on this instance alone and breaking wherever the repository is imported. Nothing is pushed to the synced branch until the content it reads is synced.

7. Hand off

The metabase-data-apps skill has one guide per step; follow it for the app's code, with sections 4 to 6 taking precedence:

8. The data behind it

The app reads what the semantic layer publishes to the Library. A number it shows with no metric or measure behind it yet goes back to the rde skill first (its semantic-layer playbook, clean tables before that when the source is raw), then through sections 4 to 6 into the repository, so the app queries the definition by id and never re-derives it in queries/. When the rde skill keeps ./.scratch/STATE.md, record there the app's slug, the ids it reads, the synced collections, and each sync decision.

9. Delivery

The setup guide ends with a commit and a push; make them in section 5's order, after section 6's question. With rde's local remote the push lands in the bare repository inside ~/.rde; mb --profile $PROFILE git-sync import --json then brings the app into Metabase, and it opens at <url>/apps/<slug>. The hand-back names what was synced, to which branch, and at which commit.