Skip to content

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

Bot infrastructure and orchestrator (#73126)

Nathan Voxland9e8194f56dba
diff --git a/.claude/commands/autobot-list.md b/.claude/commands/autobot-list.md
new file mode 100644
index 00000000000..53d2f9c6323
--- /dev/null
+++ b/.claude/commands/autobot-list.md
@@ -0,0 +1,5 @@
+List all autobot sessions with status information.
+
+Run: `./bin/mage -autobot-list`
+
+Present the output to the user.
diff --git a/.claude/commands/autobot-quit.md b/.claude/commands/autobot-quit.md
new file mode 100644
index 00000000000..15da253bd7b
--- /dev/null
+++ b/.claude/commands/autobot-quit.md
@@ -0,0 +1,17 @@
+Tear down and remove an autobot session (worktree, Docker containers, and tmux).
+
+The user provided: `$ARGUMENTS`
+
+Run this from the **current working directory** (don't `cd` anywhere) — `./bin/mage` works from any worktree, and the no-argument case relies on being inside the worktree you want to remove:
+
+```
+./bin/mage -autobot-quit $ARGUMENTS
+```
+
+The mage command handles both cases:
+- **With an argument**: uses it as the session name. If no session matches, mage prints the available sessions and exits non-zero.
+- **Without an argument**: auto-detects the current worktree's session from its path. If the caller is in the main repo (not a worktree), mage prints a usage error and exits non-zero.
+
+Do NOT preemptively run `-autobot-list` and ask the user to pick. Just run `-autobot-quit` with whatever the user gave you (or nothing) and show the output.
+
+Show the user the full stdout+stderr of the command.
diff --git a/.claude/commands/autobot-result.md b/.claude/commands/autobot-result.md
new file mode 100644
index 00000000000..126b0c73221
--- /dev/null
+++ b/.claude/commands/autobot-result.md
@@ -0,0 +1,26 @@
+Print the most recent `result.md` for an autobot session, so the user can see how a bot is doing without attaching to its tmux session.
+
+The user provided: `$ARGUMENTS`
+
+Parse as: `<branch> <bot>`
+
+- First word: branch name (e.g., `uxw-291-skip-ldap-for-non-ldap`)
+- Second word: bot name (e.g., `qabot`, `fixbot`, `uxbot`, `reprobot`, `cibot`)
+
+If either is missing, show usage and stop:
+```
+Usage: /autobot-result <branch> <bot>
+Example: /autobot-result uxw-291-skip-ldap-for-non-ldap qabot
+```
+
+Run:
+```
+./bin/mage -autobot-result <BRANCH> <BOT>
+```
+
+The command will:
+- Find the worktree for the branch (via `workmux list`)
+- Find the most recent `result.md` file under `<worktree>/.bot/<bot>/*/result.md`
+- Print its contents along with the absolute path
+
+Show the user the full output of the command.
\ No newline at end of file
diff --git a/.claude/commands/autobot-stop.md b/.claude/commands/autobot-stop.md
new file mode 100644
index 00000000000..a9a9ae4ab21
--- /dev/null
+++ b/.claude/commands/autobot-stop.md
@@ -0,0 +1,17 @@
+Stop an autobot session (kill tmux and dev environment, but keep the worktree).
+
+The user provided: `$ARGUMENTS`
+
+Run this from the **current working directory** (don't `cd` anywhere) — `./bin/mage` works from any worktree, and the no-argument case relies on being inside the worktree you want to stop:
+
+```
+./bin/mage -autobot-stop $ARGUMENTS
+```
+
+The mage command handles both cases:
+- **With an argument**: uses it as the session name. If no session matches, mage prints the available sessions and exits non-zero.
+- **Without an argument**: auto-detects the current worktree's session from its path. If the caller is in the main repo (not a worktree), mage prints a usage error and exits non-zero.
+
+Do NOT preemptively run `-autobot-list` and ask the user to pick. Just run `-autobot-stop` with whatever the user gave you (or nothing) and show the output.
+
+Show the user the full stdout+stderr of the command.
diff --git a/.claude/commands/autobot.md b/.claude/commands/autobot.md
new file mode 100644
index 00000000000..3c560e7f53a
--- /dev/null
+++ b/.claude/commands/autobot.md
@@ -0,0 +1,89 @@
+Launch a bot command in an isolated autobot session with its own worktree, backend, and frontend.
+
+The user provided: `$ARGUMENTS`
+
+## Steps
+
+### 1. Parse arguments
+
+Parse as: `<branch-name-or-pr-env-url> [from <base-branch>] <inner-command> [inner-args...]`
+
+The first token can be either a branch name OR a PR preview environment URL:
+
+- **Branch name** (e.g., `master`, `my-feature-branch`) — launches a local dev environment in a worktree (normal mode).
+- **PR preview env URL** matching the exact pattern `https://pr<NUMBER>.coredev.metabase.com` (with optional trailing `/`) — launches in **remote mode**. No local backend/frontend is booted; the bot talks to the deployed preview environment instead. The URL must match the anchored regex `^https://pr(\d+)\.coredev\.metabase\.com/?$`; reject anything else (e.g., extra subdomains, different hosts, or paths) — do not pass it to `-autobot-go`.
+
+If the first token matches the PR-env URL pattern:
+1. Extract the PR number from the anchored regex above (the digits after `pr`).
+2. Resolve the branch name by running `gh pr view <PR_NUMBER> --json headRefName` and reading `headRefName`.
+3. Use that branch for the worktree (so the bot has access to the PR's source code).
+4. Set `PR_ENV_URL` to the matched URL.
+5. Pass `--pr-env-url <URL>` to `-autobot-go` in step 4.
+
+**Note:** PR preview environments are reachable only from the Metabase Tailscale network. If `gh pr view` or the preview URL itself hangs or times out, tell the user to check their Tailscale connection.
+
+If the next two words after the branch/URL are `from <base>`: use `<base>` as the base branch. The `from <base>` clause is the signal that autobot should **create the branch** from `<base>` if it doesn't exist. If the branch already exists, passing `from <base>` is an error (the base would be silently ignored otherwise). Pass `--base <base>` to `-autobot-go` in step 4.
+
+Without `from`, the branch must already exist locally or on origin.
+
+Next word starting with `/`: inner command (e.g., `/qabot`, `/fixbot`).
+Remaining words: arguments to pass to the inner command.
+
+Examples:
+- `/autobot master /qabot` → branch=master (must exist), command="/qabot"
+- `/autobot my-new-branch from origin/master /qabot` → **create** branch=my-new-branch from origin/master, command="/qabot"
+- `/autobot my-new-branch from existing-branch /qabot` → **create** branch=my-new-branch from existing-branch, command="/qabot"
+- `/autobot my-branch /fixbot MB-12345` → branch=my-branch (must exist), command="/fixbot MB-12345"
+- `/autobot https://pr383713.coredev.metabase.com /qabot` → **PR-env mode**: PR=383713, branch=(resolved from PR), command="/qabot", pr-env-url=https://pr383713.coredev.metabase.com
+
+Extract the bot name from the inner command by stripping the leading `/` (e.g., `/qabot` → `qabot`).
+
+### 2. Preflight checks
+
+#### Autobot infrastructure checks
+
+Verify these are available (stop if any fail):
+- `workmux --version` — workmux is installed (`cargo install workmux`)
+
+#### Inner bot precheck
+
+If a `/<bot-name>-precheck` skill exists (e.g., `/qabot-precheck` for `/qabot`), run it before launching. If the precheck reports failures, stop and show the results — do not launch the session.
+
+If no precheck skill exists for the inner bot, skip this step.
+
+### 3. Discover context
+
+Run the `/<bot-name>-discover` skill, passing the inner-args as its arguments. For example, if the command is `/fixbot MB-12345`, run `/fixbot-discover MB-12345`.
+
+This will:
+- Gather external context (Linear issues, PR descriptions, etc.)
+- Determine the correct app database
+- Write results to `.bot/<bot-name>/discover/result.env`
+
+After the discover skill completes, read `.bot/<bot-name>/discover/result.env` and extract the `APP_DB` value. If the file doesn't exist or APP_DB is missing, default to `postgres`.
+
+### 4. Launch the autobot session
+
+Run (append `--pr-env-url <URL>` if in PR-env mode, `--base <base>` only if the user supplied `from <base>`):
+```
+./bin/mage -autobot-go <BRANCH_NAME> --bot <BOT_NAME> --app-db <APP_DB> --command "<INNER_COMMAND> <INNER_ARGS>" [--base <BASE_BRANCH>] [--pr-env-url <PR_ENV_URL>]
+```
+
+Only pass `--base` when the user explicitly wrote `from <base>`. Omitting it means "branch must already exist."
+
+This will:
+- Create a worktree based on the branch (or reuse an existing one)
+- Set up the dev environment with the correct database
+- Start backend + frontend dev servers in tmux panes
+- Launch Claude with the inner command as its prompt
+
+If a session already exists for this bot+branch, it will tell you to stop it first.
+
+### 5. Report
+
+Tell the user:
+- The session has been launched
+- How to attach: `tmux attach -t <session-name>`
+- How to stop: `/autobot-stop <session-name>` (or `/autobot-stop` from inside the session)
+- How to list all sessions: `/autobot-list`
+- How to remove: `/autobot-quit <session-name>`
diff --git a/.gitignore b/.gitignore
index ad41d0335a5..5075cef65a9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,8 +11,9 @@
*.xcworkspacedata
.DS_Store
.\#*
-.cpcache/
+.cpcache
.eastwood
+.bot
.idea/
.nrepl-port
.portal
@@ -40,10 +41,11 @@
/classes
/coverage
/crate-*
+/jars
/cypress
cypress.env.json
/deploy/artifacts/*
-**/node_modules/
+**/node_modules
/docs/**/package.json
/docs/**/yarn.lock
/docs/embedding/sdk/api/
@@ -178,3 +180,4 @@ __pycache__/
.mcp.json
.claude/worktrees
.claude/scheduled_tasks.lock
+.playwright-mcp
diff --git a/bb.edn b/bb.edn
index effd98b60e3..e856966872a 100644
--- a/bb.edn
+++ b/bb.edn
@@ -10,6 +10,7 @@
org.babashka/json {:mvn/version "0.1.6"} ;; json parsing
table/table {:mvn/version "0.5.0"} ;; table printing
}
+ :pods {org.babashka/postgresql {:version "0.1.0"}}
:tasks
{:requires [[mage.cli :as cli]
[mage.color :as c]]
@@ -260,7 +261,7 @@
{:doc "Generate XML configuration for Cursive's symbol resolution based on the current clj-kondo lint-as configuration."
:examples [["./bin/mage generate-cursive-resolve-as" "Generate resolve-as XML configuration"]
["./bin/mage generate-cursive-resolve-as > /Users/bgrabow/Library/Application\\ Support/JetBrains/IntelliJIdea2025.3/options/ClojureResolveSettings.xml"
- "Generate resolve-as XML configuration and install it in your global editor configuration"]]
+ "Generate resolve-as XML configuration and install it in your global editor configuration"]]
:requires [[mage.cursive-resolve-as :as cursive-resolve-as]]
:task (task! (cursive-resolve-as/do-it))}
@@ -598,6 +599,36 @@
[nil "--fresh" "Recreate containers from scratch"]]
:task (task! (jds-dev-env/dev-env! parsed))}
+ -bot-dev-env
+ {:doc "Stand up (or tear down) an isolated dev environment for this worktree. Interactive prompts when flags omitted."
+ :examples [["./bin/mage -bot-dev-env" "Interactive TUI to configure infra (saves config)"]
+ ["./bin/mage -bot-dev-env --run" "Configure + launch backend/frontend"]
+ ["./bin/mage -bot-dev-env --run --no-frontend" "Configure + backend only"]
+ ["./bin/mage -bot-dev-env --down" "Stop everything for this worktree"]
+ ["./bin/mage -bot-dev-env --status" "Show running containers and processes"]]
+ :requires [[mage.bot.dev-env :as jds-dev-env]]
+ :options [["-e" "--edition EDITION" "ee or oss (default: prompt)"]
+ ["-t" "--token TOKEN" "Token type: all-features, starter-cloud, pro-cloud, pro-self-hosted, none"]
+ [nil "--app-db DB" "App database: h2, postgres, mysql, mariadb (default: prompt)"]
+ [nil "--with SERVICE" "Warehouse service (repeatable): postgres, mysql, mariadb, mongo, clickhouse, ldap, maildev"
+ :multi true :default nil :update-fn conj]
+ [nil "--bot BOT" "Bot name (enables bot-specific config: Docker containers, bot dirs, Playwright dirs)"]
+ [nil "--run" "Also launch backend + frontend in background"]
+ [nil "--no-frontend" "Skip frontend dev server (only with --run)"]
+ [nil "--down" "Stop everything for this worktree"]
+ [nil "--status" "Show current env status"]
+ [nil "--slot SLOT" "Override port slot (0-99)" :parse-fn Integer/parseInt]
+ [nil "--fresh" "Recreate containers from scratch"]
+ [nil "--worktree PATH" "Target a different worktree (default: current)"]]
+ :task (task! (jds-dev-env/dev-env! parsed))}
+
+ -bot-setup-worktree
+ {:doc "Run final configuration steps after a new worktree is created."
+ :examples [["./bin/mage -bot-setup-worktree --worktree $(pwd)" "Set up the current directory as a worktree"]]
+ :options [[nil "--worktree PATH" "Path to the worktree to set up (required)"]]
+ :requires [[mage.bot.setup-worktree :as setup-worktree]]
+ :task (task! (setup-worktree/setup-worktree! parsed))}
+
-bgrabow-ci-test-repl
{:doc "Start a REPL replicating a CI test job environment (Docker + env vars)"
:examples [["./bin/mage -bgrabow-ci-test-repl" "Interactive selection with fzf"]
@@ -606,6 +637,157 @@
:requires [[mage.bgrabow.ci-test-repl :as ci-test-repl]]
:options [["-n" "--dry-run" "Print docker, env, and clojure commands without executing"]]
:task (task!
- (let [wj (first (:arguments parsed))
- [workflow job] (when wj (clojure.string/split wj (re-pattern "/") 2))]
- (ci-test-repl/ci-test-repl {:workflow workflow :job job :dry-run? (:dry-run (:options parsed))})))}}}
+ (let [wj (first (:arguments parsed))
+ [workflow job] (when wj (clojure.string/split wj (re-pattern "/") 2))]
+ (ci-test-repl/ci-test-repl {:workflow workflow :job job :dry-run? (:dry-run (:options parsed))})))}
+
+ -bot-status
+ {:doc "Watch and display bot status"
+ :requires [[mage.bot.status :as status]]
+ :arg-schema [:? [:string {:name "file-path"}]]
+ :task (task! (status/run! parsed))}
+
+ -bot-generate-prompt
+ {:doc "Fill a template with placeholders and write an agent prompt"
+ :examples [["./bin/mage -bot-generate-prompt --template dev/bot/fixbot-agent.md --output .bot/fixbot/20260410/prompt.md --set ISSUE_ID=MB-123"
+ "Generate fixbot prompt"]]
+ :requires [[mage.bot.prompt :as bot-prompt]]
+ :options [[nil "--template FILE" "Template file path"]
+ [nil "--output FILE" "Output file path"]
+ [nil "--set KEY=VALUE" "Set a template variable (can be repeated)"
+ :multi true :default [] :update-fn conj]
+ [nil "--set-from-file KEY=PATH" "Set a template variable from a file's contents (can be repeated)"
+ :multi true :default [] :update-fn conj]]
+ :task (task! (bot-prompt/generate-prompt! parsed))}
+
+ ;;; Unified autobot session management
+
+ -autobot-go
+ {:doc "Launch a bot in an autobot session with its own worktree, backend, and frontend (or remote PR env)"
+ :examples [["./bin/mage -autobot-go master --bot qabot --command /qabot"
+ "Launch qabot in an autobot session"]
+ ["./bin/mage -autobot-go my-branch --bot fixbot --command '/fixbot MB-12345' --app-db mysql"
+ "Launch fixbot with MySQL"]
+ ["./bin/mage -autobot-go uxw-291 --bot qabot --command /qabot --pr-env-url https://pr383713.coredev.metabase.com"
+ "Launch qabot against a remote PR preview environment"]]
+ :requires [[mage.bot.autobot :as autobot]]
+ :arg-schema [:tuple [:string {:name "branch-name"}]]
+ :options [[nil "--bot BOT" "Bot name (qabot, fixbot, uxbot, reprobot, cibot)"]
+ [nil "--command CMD" "Inner command to run (e.g., /qabot, '/fixbot MB-12345')"]
+ [nil "--app-db DB" "App database" :default "postgres"]
+ [nil "--base BASE" "Base branch/commit to branch from. If set and the branch does not exist, it will be created from this base."]
+ [nil "--pr-env-url URL" "PR preview environment URL (enables remote mode, no local dev-env)"]]
+ :task (task! (autobot/go! parsed))}
+
+ -bot-pr-env
+ {:doc "Configure a worktree for a remote PR preview environment (writes .bot/pr-env.env + caches session token)"
+ :examples [["./bin/mage -bot-pr-env --url https://pr383713.coredev.metabase.com --pr 383713"
+ "Set up this worktree to talk to the given PR preview environment"]]
+ :requires [[mage.bot.pr-env :as pr-env]]
+ :options [[nil "--url URL" "PR preview environment URL"]
+ [nil "--pr PR" "PR number"]]
+ :task (task! (pr-env/setup! parsed))}
+
+ -autobot-stop
+ {:doc "Stop an autobot session (kill tmux + dev env, keep worktree). No args = stop current session."
+ :examples [["./bin/mage -autobot-stop qabot-master" "Stop named session"]
+ ["./bin/mage -autobot-stop" "Stop current session (from inside an autobot session)"]]
+ :requires [[mage.bot.autobot :as autobot]]
+ :arg-schema [:? [:string {:name "name-or-id"}]]
+ :task (task! (autobot/stop! parsed))}
+
+ -autobot-list
+ {:doc "List all autobot sessions with status"
+ :examples [["./bin/mage -autobot-list" "List all sessions"]]
+ :requires [[mage.bot.autobot :as autobot]]
+ :task (task! (autobot/list-all! parsed))}
+
+ -autobot-result
+ {:doc "Print the most recent result.md for a branch+bot combination"
+ :examples [["./bin/mage -autobot-result uxw-291-skip-ldap-for-non-ldap qabot"
+ "Print qabot's latest result.md for the given branch"]]
+ :requires [[mage.bot.autobot :as autobot]]
+ :arg-schema [:tuple [:string {:name "branch"}] [:string {:name "bot"}]]
+ :task (task! (autobot/result! parsed))}
+
+ -autobot-quit
+ {:doc "Tear down and remove an autobot session. No args = remove current session."
+ :examples [["./bin/mage -autobot-quit qabot-master" "Remove named session"]
+ ["./bin/mage -autobot-quit" "Remove current session (from inside an autobot session)"]]
+ :requires [[mage.bot.autobot :as autobot]]
+ :arg-schema [:? [:string {:name "name-or-id"}]]
+ :task (task! (autobot/quit! parsed))}
+
+ ;;; Shared bot tasks
+
+ -bot-fetch-issue
+ {:doc "Fetch a Linear issue by identifier (shared across bots)"
+ :examples [["./bin/mage -bot-fetch-issue MB-12345" "Fetch and display issue"]]
+ :requires [[mage.bot.linear :as bot-linear]]
+ :arg-schema [:tuple [:string {:name "issue-id"}]]
+ :task (task! (bot-linear/print-issue! parsed))}
+
+ -bot-server-info
+ {:doc "Print server configuration (ports, config file, users, API keys) for bot agents"
+ :examples [["./bin/mage -bot-server-info" "Show server info"]]
+ :requires [[mage.bot.server-info :as server-info]]
+ :task (task! (server-info/server-info! parsed))}
+
+ -bot-preflight
+ {:doc "Run prerequisite checks for a bot workflow"
+ :examples [["./bin/mage -bot-preflight --bot fixbot" "Run checks for fixbot (Linear required)"]
+ ["./bin/mage -bot-preflight --bot qabot" "Run checks for qabot (Linear optional)"]]
+ :options [[nil "--bot BOT" "Bot name (fixbot, qabot, uxbot, reprobot, cibot)"]]
+ :requires [[mage.bot.preflight :as preflight]]
+ :task (task! (preflight/preflight! parsed))}
+
+ -bot-preflight-health
+ {:doc "Wait for Metabase backend to become healthy (retries for up to 5 minutes)"
+ :examples [["./bin/mage -bot-preflight-health" "Wait for backend health"]]
+ :requires [[mage.bot.preflight :as preflight]]
+ :task (task! (preflight/preflight-health! parsed))}
+
+ -bot-timestamp
+ {:doc "Print the current wall-clock time as YYYYMMDD-HHMMSS (no other output)"
+ :examples [["./bin/mage -bot-timestamp" "Print e.g. 20260413-143022"]]
+ :task (task! (println (.format (java.time.LocalDateTime/now)
+ (java.time.format.DateTimeFormatter/ofPattern "yyyyMMdd-HHmmss"))))}
+
+ -bot-repl-eval
+ {:doc "Evaluate Clojure code against the best-available REPL (nREPL first, socket REPL fallback)"
+ :examples [["./bin/mage -bot-repl-eval '(+ 1 2)'" "Auto-discover and eval"]
+ ["./bin/mage -bot-repl-eval --type socket '(metabase.config/current-version)'" "Force socket REPL"]
+ ["./bin/mage -bot-repl-eval --port 50666 '(+ 1 2)'" "Force a specific port"]]
+ :requires [[mage.bot.repl-eval :as repl-eval]]
+ :arg-schema [:? [:string {:name "code"}]]
+ :options [[nil "--code CODE" "Clojure code to eval (alternative to positional arg)"]
+ [nil "--port PORT" "Override discovery and use this port"]
+ [nil "--host HOST" "Override discovery and use this host (socket REPL only)"]
+ [nil "--type TYPE" "Force backend: 'nrepl' or 'socket'. Default: auto-detect."]
+ [nil "--refresh" "Ignore .bot/repl.env cache and re-run discovery"]]
+ :task (task! (repl-eval/repl-eval! parsed))}
+
+ -bot-api-call
+ {:doc "Make an API call to the local Metabase instance"
+ :examples [["./bin/mage -bot-api-call /api/health" "Health check"]
+ ["./bin/mage -bot-api-call /api/card --api-key mb_admin_apikey" "List cards as admin"]
+ ["./bin/mage -bot-api-call /api/card --method POST --api-key mb_admin_apikey --body '{\"dataset_query\":{}}'" "Create a card"]]
+ :requires [[mage.bot.api-call :as api-call]]
+ :arg-schema [:tuple [:string {:name "api-path"}]]
+ :options [[nil "--method METHOD" "HTTP method (GET, POST, PUT, DELETE)" :default "GET"]
+ [nil "--api-key KEY" "API key for x-api-key header"]
+ [nil "--body JSON" "JSON request body"]
+ [nil "--pretty BOOL" "Pretty-print JSON (default true)" :default "true"]
+ [nil "--raw" "Suppress diagnostic preamble on stderr (pure-body stdout for jq/python piping)"]]
+ :task (task! (api-call/api-call! parsed))}
+
+ -bot-md-to-pdf
+ {:doc "Convert a markdown file to PDF using md-to-pdf"
+ :examples [["./bin/mage -bot-md-to-pdf report.md" "Convert report.md to report.pdf"]
+ ["./bin/mage -bot-md-to-pdf .bot/qabot/20260410/report.md" "Convert with full path"]]
+ :arg-schema [:tuple [:string {:name "file"}]]
+ :task (task!
+ (let [md-file (first (:arguments parsed))
+ dir (.getParent (java.io.File. ^String md-file))
+ fname (.getName (java.io.File. ^String md-file))]
+ (babashka.tasks/shell {:dir (or dir ".")} "npx" "-y" "md-to-pdf" fname)))}}}
diff --git a/dev/bot/common/environment-discovery.md b/dev/bot/common/environment-discovery.md
new file mode 100644
index 00000000000..0cb203cf8c5
--- /dev/null
+++ b/dev/bot/common/environment-discovery.md
@@ -0,0 +1,179 @@
+## Initial Setup
+
+1. If you have not already, read `CLAUDE.md` in the project root for test commands and conventions.
+2. **Create all directories and files that later steps will Read or Write.** Run this single Bash command up front so the rest of the phases don't trip over missing paths:
+ ```bash
+ mkdir -p .bot/autobot {{OUTPUT_DIR}}/output {{OUTPUT_DIR}}/tmp && touch .bot/autobot/llm-status.txt
+ ```
+ - `.bot/autobot/llm-status.txt` is displayed in the status pane in autobot mode. Nothing else creates it, so it must be touched here. In direct-run mode no one reads it but having it present is harmless.
+ - `{{OUTPUT_DIR}}/output/` is where Playwright screenshots and API-response captures land. Playwright calls fail with `ENOENT` if this doesn't exist before the first screenshot.
+ - `{{OUTPUT_DIR}}/tmp/` is where intermediate files go (prompt fragments, etc).
+3. Read `.bot/autobot/llm-status.txt` using the `Read` tool — it now exists (from step 2) so Read will succeed, and this unlocks later `Write` calls to the same file (the Write tool requires a prior Read on existing files).
+4. Wait for backend: run `./bin/mage -bot-preflight-health` (retries for up to 5 minutes). If it times out, **STOP and tell the user** to check the backend logs. In PR-env mode the backend is already running remotely; this still works because preflight only polls the health endpoint.
+5. Load Playwright MCP tools:
+ ```
+ ToolSearch: select:mcp__playwright__browser_navigate,mcp__playwright__browser_snapshot,mcp__playwright__browser_click,mcp__playwright__browser_fill,mcp__playwright__browser_type,mcp__playwright__browser_press_key,mcp__playwright__browser_hover,mcp__playwright__browser_take_screenshot,mcp__playwright__browser_close,mcp__playwright__browser_evaluate,mcp__playwright__browser_console_messages,mcp__playwright__browser_network_requests
+ ```
+ If ToolSearch says "MCP servers still connecting," wait 10 seconds and retry up to 3 times. If it still fails, **STOP and tell the user**: "Playwright MCP tools are not available."
+
+ **Always load Playwright, even for backend-only diffs.** Backend changes can produce surprising frontend behavior — wrong response shapes, broken error flows, changed permissions, auth regressions, etc. Part of your job is to exercise the backend changes through the UI and look for anything a user would find surprising or broken, regardless of whether the diff touches any frontend files.
+
+## Fail-Fast on Tool Issues
+
+If any of these fail during setup or at any point, **STOP immediately** and tell the user what you tried and what failed. Do NOT attempt to fix infrastructure — the user is responsible for providing a working environment.
+
+- Playwright MCP tools unavailable or erroring → STOP
+- Backend server not responding to health check → STOP
+- API calls returning connection errors → STOP
+- nREPL not responding (`-bot-server-info` reports `NREPL_PORT=NONE` AND `.nrepl-port` is absent in the project root) → STOP. **Exception:** in PR-env mode (see below) `NREPL_PORT=NONE` is expected and is NOT a STOP condition — use the socket REPL instead.
+- Linear API unreachable → continue without Linear context (optional)
+
+## Remote PR Environment Mode
+
+If `./bin/mage -bot-server-info` prints `MODE=pr-env` in a "Remote PR Environment" section, you are NOT running against a local dev server — you are running against a pre-deployed PR preview environment at a URL like `https://pr383713.coredev.metabase.com`. In this mode:
+
+- **API calls** — use `./bin/mage -bot-api-call` exactly as you would locally. It transparently detects PR-env mode, sends requests to `BASE_URL` from `-bot-server-info`, and authenticates using the cached session token. You do not need to pass `--api-key` or `--base-url`. If the session expires, the wrapper refreshes it automatically on a 401.
+- **Browser testing** — Playwright MCP should navigate to `BASE_URL` from `-bot-server-info`, not `http://localhost:*`. The preview site is served over HTTPS; there is no local frontend running.
+- **REPL access** — use `./bin/mage -bot-repl-eval '<code>'` as usual. It detects PR-env mode automatically and routes the eval through the remote socket REPL at `repl.coredev.metabase.com:<PR_NUM>`. `clj-nrepl-eval` does NOT work in PR-env mode; the wrapper is your only REPL path. Send **one top-level form per call** — the socket REPL is not session-managed like nREPL. To evaluate multiple forms together, wrap them in `(do ...)`.
+- **Database access** — there is no local database. Query data through API endpoints (`/api/dataset`, `/api/card/<id>/query`, `/api/user`, etc.) instead of via Toucan2 in the REPL.
+- **Logs** — use `/api/logger/logs` (admin API) instead of REPL-based `(logger/messages)`.
+- **Backend restart** — you cannot restart the backend. If you hit a configuration issue that requires a restart, STOP and tell the user.
+
+**Tailscale is required.** PR preview environments are only reachable from the Metabase Tailscale network. If API calls, Playwright navigation, or `nc` hang or time out, the most likely cause is a missing Tailscale connection — tell the user to check their Tailscale status. Do not spend time debugging network issues yourself.
+
+**Destructive tests on shared PR envs.** A PR preview is typically shared with other QA/UX bot sessions and the PR author. Before performing actions that mutate persistent state — disconnecting a provider, deleting a database connection, changing `site-url` or `admin-email`, clearing a cache, dropping a collection, rewriting a permission group, etc. — consider whether the change will affect other users of the env. Prefer read-only verifications or revert-on-exit patterns:
+
+1. **Snapshot first.** Read the current value (e.g. `GET /api/setting/llm-anthropic-api-key`) and store it in `{{OUTPUT_DIR}}/output/` as evidence before mutating.
+2. **Mutate.** Perform the test.
+3. **Revert.** Restore the original value. Confirm the revert took effect with another GET.
+4. **If revert is impossible** (the test destroyed something unrecoverable, like a dropped table or a deleted saved question), **do not perform the test.** Instead, mark the finding `CONFIRMED_STATIC` with a note explaining why dynamic repro was skipped. That is a valid and honest status — do not downgrade it to SUSPECTED just because you couldn't run the destructive test.
+
+## Output and Work Directory
+
+Your base output directory is `{{OUTPUT_DIR}}`. Use this path for ALL output files.
+
+Even temporary files should go in `{{OUTPUT_DIR}}/tmp`
+
+## Discover Environment & Instance Setup
+
+Run `./bin/mage -bot-server-info` to discover everything about the running instance:
+- **Ports**: Jetty backend, frontend dev server, nREPL, database
+- **Config file**: path and contents (users, passwords, API keys)
+- **Environment variables**: edition, tokens, connection URIs
+
+Do NOT hardcode ports, credentials, or API key values — always discover them from `-bot-server-info`.
+
+Use `http://localhost:$MB_JETTY_PORT` for all API calls and browser navigation. The instance auto-creates users and API keys on first startup via the config file — no manual setup or `/api/setup` calls needed.
+
+## REPL Access
+
+The backend runs a Clojure REPL — either nREPL or a socket REPL, depending on the mode. Use `./bin/mage -bot-repl-eval '<code>'` as the single canonical wrapper; it auto-detects the right backend and falls back automatically:
+
+```bash
+./bin/mage -bot-repl-eval '(+ 1 2)'
+```
+
+**Auto-detect order:**
+1. **nREPL** via `clj-nrepl-eval` — used when `.nrepl-port` or `clj-nrepl-eval --discover-ports` finds a server. Normal case in local-dev mode.
+2. **Socket REPL** via a direct TCP connection — used when nREPL isn't available. The socket REPL host/port comes from `MB_SOCKET_REPL_PORT` in local mode, or from `REPL_HOST`/`REPL_PORT` in `.bot/pr-env.env` in PR-env mode (`repl.coredev.metabase.com:<PR_NUM>`).
+3. **Error** if neither is available — STOP and tell the user.
+
+You can force a specific backend with `--type nrepl` or `--type socket`, or override discovery with `--port` / `--host`.
+
+Use the REPL for:
+- Evaluating Clojure expressions against the running backend
+- Requiring namespaces with `:reload` to pick up code changes
+- Testing functions interactively
+- Checking compilation
+
+**Send one expression per eval call** in socket REPL mode — the socket REPL is stateless per-connection and returns output by reading until a short timeout. In nREPL mode multiple statements in a single call are fine, but for consistency and parallelizability, one form per call is still the best default. To evaluate multiple forms together, wrap them in `(do ...)`.
+
+**Do not use `clj-nrepl-eval` directly.** It only speaks nREPL and will fail silently or hang in PR-env mode. Use `-bot-repl-eval` instead, and let it pick the backend.
+
+If the wrapper itself reports "No REPL available", run `./bin/mage -bot-server-info` to see what discovery found, then decide whether to STOP or retry after waiting.
+
+
+
+## Database Access
+
+In **local-dev mode**, the app database connection URI is in `MB_DB_CONNECTION_URI` (from `-bot-server-info`). Always interact with the database through Clojure JDBC via the REPL — do NOT use `psql`, `mysql`, or other CLI database tools.
+
+```bash
+./bin/mage -bot-repl-eval '(do (require (quote [toucan2.core :as t2])) (t2/select :model/Card :id 1))'
+```
+
+```bash
+./bin/mage -bot-repl-eval '(do (require (quote [toucan2.core :as t2])) (t2/query "SELECT id, name FROM report_card LIMIT 5"))'
+```
+
+In **PR-env mode** there is no direct database access — query data through API endpoints (`/api/dataset`, `/api/card/<id>/query`, `/api/user`, etc.) instead. The socket REPL can still run Clojure forms that hit the database, but you'll only have access to the running instance's connection, not a separate psql/mysql shell.
+
+## Log Access
+
+### View and capture logs (REPL)
+
+```clojure
+(require '[metabase.logger.core :as logger])
+(logger/messages) ;; last 250 log entries
+(logger/set-ns-log-level! 'metabase.some-ns :debug) ;; increase verbosity
+(logger/set-ns-log-level! 'metabase.some-ns :info) ;; reset
+```
+
+Levels (least→most verbose): `:off` `:fatal` `:error` `:warn` `:info` `:debug` `:trace`
+
+Or via API: `./bin/mage -bot-api-call /api/logger/logs --api-key $ADMIN_API_KEY`
+
+**Workflow:** Set debug level → reproduce issue → capture logs → reset level.
+
+Use logs for:
+- Debugging startup failures (check if backend/frontend started successfully)
+- Looking for error messages or stack traces
+- Verifying that your code changes were picked up by hot reload
+
+Save logs as evidence:
+```clojure
+(spit "{{OUTPUT_DIR}}/output/server-logs-CONTEXT.txt"
+ (->> (logger/messages)
+ (map #(str (:timestamp %) " " (:level %) " [" (:fqns %) "] " (:msg %)))
+ (clojure.string/join "\n")))
+```
+
+## Status Tracking
+
+Write to `.bot/autobot/llm-status.txt` when your status changes meaningfully. This is displayed in a status pane visible to the user. Examples:
+- "Analyzing diff"
+- "Reproducing issue"
+- "Writing tests"
+- "Waiting for CI"
+- "Blocked: <what's blocking>"
+
+**Rules:**
+- Keep it to **1-3 short lines** — the pane is small
+- Only update when visible state meaningfully changes — don't spam
+- Overwrite the whole file each time
+
+## Result File
+
+Maintain a `result.md` file in your output directory (`{{OUTPUT_DIR}}/result.md`) that summarizes what you've done so far. This is what the user sees when they run `/autobot-result <branch> <bot>` — they check it instead of attaching to tmux to see how you're doing.
+
+**Format:** exactly two paragraphs.
+- **Paragraph 1 — What's done.** Concrete, past-tense summary of what you've completed so far: phases finished, files read, tests run, findings so far, decisions made. Be specific: "Analyzed the diff (3 backend files, 1 migration), built a truth table for the new auth gate, found 1 SEVERE regression." Not vague: "Reviewed the PR."
+- **Paragraph 2 — What's next / current state.** What you're currently doing and what comes next, OR (if you're blocked or finished) a clear statement of that. If blocked, name what you need.
+
+**After the two paragraphs, list every artifact you've produced so far as a bulleted list of absolute paths.** Include reports, screenshots, API responses, log captures, fix plans, prompt files — anything you've written to disk during this session. Paths must be absolute so the user can click or copy them directly. Add new items as you produce them; do NOT remove items from previous updates. Example format:
+
+```markdown
+## Artifacts
+
+- `/Users/.../metabase-4__worktrees/<branch>/.bot/qabot/20260413-211500/diff-summary.md` — Phase 1 diff analysis
+- `/Users/.../metabase-4__worktrees/<branch>/.bot/qabot/20260413-211500/initial-review.md` — Phase 2 static findings
+- `/Users/.../metabase-4__worktrees/<branch>/.bot/qabot/20260413-211500/output/issue-01-before.png` — baseline screenshot
+```
+
+**When to update:** write `result.md` as soon as you start (even if the first version just says "Starting up, loading environment."), then overwrite it at every meaningful milestone — phase boundaries, finding a bug, finishing a major step, hitting a blocker. Don't wait for the end.
+
+**Rules:**
+- Overwrite the whole file each time — don't append
+- Plain Markdown, no banners or boxes
+- Never truncate to a placeholder like "TODO" — if you don't know what to say, write what you actually just did
+- Keep the two-paragraph section tight; the artifact list can grow long
diff --git a/dev/bot/common/metabase-patterns.md b/dev/bot/common/metabase-patterns.md
new file mode 100644
index 00000000000..8e85d2fc900
--- /dev/null
+++ b/dev/bot/common/metabase-patterns.md
@@ -0,0 +1,82 @@
+## Metabase Development Patterns & Gotchas
+
+### REPL Recipes
+
+**Inspect tables**: `(t2/select [:model/Table :id :name :db_id] :db_id 1)`
+
+**Check settings**: `(t2/select-one :model/Setting :key "site-name")`
+
+**Look up field IDs** (needed for MBQL queries):
+```clojure
+(t2/select [:model/Field :id :name :table_id] :table_id 3)
+```
+
+**Run native SQL query**:
+```clojure
+(require '[metabase.query-processor :as qp])
+(qp/process-query {:database 1 :type :native :native {:query "SELECT * FROM ORDERS LIMIT 5"}})
+```
+
+**Compile MBQL to SQL** (useful for debugging query generation):
+```clojure
+(require '[metabase.query-processor.compile :as qp.compile])
+(qp.compile/compile {:database 1 :type :query :query {:source-table 1 :filter [:= [:field 1 nil] 42]}})
+```
+
+**Pretty-print SQL**: `(dev/pprint-sql {:database 1 :type :query :query {...}})`
+
+**Check permissions**: `(t2/select :model/Permissions :group_id 1)`
+
+### Key test/dev namespaces
+
+Test and dev namespaces are available on the classpath — no manual setup needed:
+- `metabase.test` (`mt`) — `mt/user-http-request`, `mt/id`, `mt/with-temp`, `mt/process-query`
+- `dev` — `dev/pprint-sql`, `dev/explain-query`, `dev/restart!`
+
+### Common Gotchas
+
+**Card creation**: Never use `t2/insert-returning-instance!` for `:model/Card` — it silently returns `nil` when internal pMBQL validation rejects the query format. Always use `./bin/mage -bot-api-call` or `mt/user-http-request` which give clear error messages on schema violations.
+
+**Feature flag toggle**: `(t2/update! :model/Setting :key "enable-pivoted-filters" {:value "true"})` — may return `0` even when successful. Always verify with `(t2/select-one :model/Setting :key "enable-pivoted-filters")`.
+
+**Visualization settings**: `graph.tooltip_columns` values must use column reference format: `["[\"name\",\"COLUMN_NAME\"]"]`, not bare names.
+
+**Dashboard inline filters**: To configure card-specific inline filters via API, use `PUT /api/dashboard/:id` with `dashcards[].inline_parameters` (array of parameter IDs) and `dashcards[].parameter_mappings`. The parameter must also exist in `dashboard.parameters`.
+
+**Pivot tables**: "Old pivot" = `table.pivot: true` on Table visualization (3-column only). "New pivot" = `PivotTable` visualization type. Separate code paths, separate bugs.
+
+### Server Lifecycle (via REPL)
+
+**Restart the server** (without killing the JVM):
+```clojure
+;; Full restart — stops web server, reinitializes DB/plugins/scheduler, restarts web server
+(dev/restart!)
+
+;; Or step by step:
+(dev/stop!) ; stops Jetty + Malli dev tools
+(dev/start!) ; starts Jetty + runs full init (migrations, plugins, scheduler, etc.)
+```
+
+After `(dev/restart!)`, the backend will be temporarily unavailable. Wait for it to come back — poll with `./bin/mage -bot-api-call /api/health` until it succeeds.
+
+**Refresh settings without restart:**
+```clojure
+(metabase.settings.core/restore-cache!)
+```
+
+**When to restart vs refresh:**
+- **Setting changed via API/UI**: No restart needed — cache auto-updates
+- **Setting changed via env var or directly in the DB**: Use `(metabase.settings.core/restore-cache!)`
+- **Code changed that affects initialization** (e.g., startup logic, plugin loading): Use `(dev/restart!)`
+- **Need a clean state for testing**: Use `(dev/restart!)`
+- **Testing startup behavior** (e.g., what happens on first boot with a new setting): Use `(dev/restart!)`
+
+### H2-Specific Constraints
+
+If the dev environment uses H2 (the default for inline mode):
+- Does NOT support `report-timezone`
+- Reserves SQL keywords (`value`, `count`, `key`, `type`) as column/alias names — use alternatives
+- May reject NULL insertions even after dropping NOT NULL constraints
+- No `DATETRUNC()` — use `CAST(col AS DATE)` for date-typed columns
+- `FORMATDATETIME()` returns text, not a date type
+- In Sample Database, `CATEGORY` is in `PRODUCTS`, not `ORDERS` — join via `PRODUCTS P ON O.PRODUCT_ID = P.ID`
diff --git a/dev/bot/common/playwright-guide.md b/dev/bot/common/playwright-guide.md
new file mode 100644
index 00000000000..8a9e00634b5
--- /dev/null
+++ b/dev/bot/common/playwright-guide.md
@@ -0,0 +1,78 @@
+## Browser Automation with Playwright MCP
+
+A Playwright MCP server is configured in `.mcp.json`. Load the tool schemas first with `ToolSearch`: `select:mcp__playwright__browser_navigate,mcp__playwright__browser_snapshot,mcp__playwright__browser_click,mcp__playwright__browser_fill,mcp__playwright__browser_type,mcp__playwright__browser_press_key,mcp__playwright__browser_hover,mcp__playwright__browser_take_screenshot,mcp__playwright__browser_close`
+
+If ToolSearch says "MCP servers still connecting," wait a few seconds and retry — the server takes a moment to start on first use.
+
+### Core pattern: Snapshot → Act → Check
+
+1. **`browser_snapshot`** — see what's on screen, get element refs
+2. **Act** — `browser_click`, `browser_fill`, `browser_type`, etc. using refs from the snapshot
+3. **Check the inline response** — every action returns a snapshot in its response. Read it.
+
+**When to take a separate `browser_snapshot` after acting:**
+- The inline response snapshot looks wrong, empty, or unchanged — take a fresh one (async rendering may not have completed)
+- You need refs for your NEXT action — the inline snapshot's refs are valid, use them directly
+- You're unsure if the action worked — take one more snapshot to confirm
+
+**When you do NOT need a separate snapshot after acting:**
+- The inline response already shows the expected change (e.g., you clicked a link and the response shows the new page)
+- You're about to take a screenshot anyway (`browser_take_screenshot` shows the current state)
+- You're doing a chain of actions on the same form (e.g., filling multiple fields) — snapshot once at the end, not after each fill
+
+**Element refs go stale after every action.** Use refs from the most recent snapshot or inline response — never from an earlier one.
+
+### How to interact with Metabase's UI components
+
+Metabase uses Mantine UI components. Most interactions work with a plain `browser_click`. The hover-before-click pattern is only needed for specific component types.
+
+**Regular buttons, links, form inputs, checkboxes, tabs:**
+Just `browser_click` them directly. No hover needed.
+
+**Buttons that open dropdown menus (e.g., "+ New", "..." action menus, filter type pickers):**
+These use Mantine's `<Menu>` component which has a race condition with direct clicks. **Hover before clicking** these:
+1. `browser_hover` on the button
+2. `browser_click` on the button
+3. Check the inline response — if the menu appeared, use its refs directly
+
+How to tell if a button opens a dropdown menu: it usually has a chevron/arrow icon, a "..." label, or is labeled as creating something new (like "+ New"). If unsure, try a direct click first — if it doesn't work, retry with hover.
+
+**Select and dropdown components (e.g., database picker, column picker):**
+Mantine Select/MultiSelect are NOT native `<select>` elements. `browser_select_option` will NOT work. Instead:
+1. `browser_click` on the input/trigger
+2. `browser_click` on the option you want (use refs from the inline response)
+
+You can also type into the input to filter options before clicking.
+
+**Modals and dialogs:**
+To dismiss: `browser_click` the close/action button, or `browser_press_key` with `Escape`.
+
+### Login
+
+1. `browser_navigate` to `http://localhost:$MB_JETTY_PORT/auth/login`
+2. `browser_snapshot` → `browser_fill` email and password → `browser_click` sign-in button
+3. **`browser_navigate` to `http://localhost:$MB_JETTY_PORT/`** — always navigate explicitly to the home page after login. Do NOT rely on the login redirect alone. The redirect can leave the browser session in a state where clicks don't register.
+4. `browser_snapshot` to confirm you're logged in
+
+### Quick login via API (alternative)
+
+Get a session token via API and set it as a cookie — faster than filling the login form:
+```bash
+./bin/mage -bot-api-call /api/session --method POST --body '{"username":"<email>","password":"<password>"}'
+```
+Extract the `id` from the response, then use `browser_evaluate` with script:
+```javascript
+document.cookie = 'metabase.SESSION=<token>;path=/'
+```
+Then `browser_navigate` to the target page. Use the credentials from `./bin/mage -bot-server-info`.
+
+### When clicks don't work
+
+1. Take a fresh snapshot (async rendering). 2. Try hover + click (menu triggers). 3. Try keyboard (focus + Enter). 4. After 3 attempts, report and move on.
+
+### Rules
+
+- Always use `http://localhost:$MB_JETTY_PORT`
+- Close the browser when done
+- Use inline response snapshots when sufficient — only take separate `browser_snapshot` when needed
+- Browser is pre-configured: 1440x900 viewport, full snapshot mode, isolated session, 10s action timeout
diff --git a/dev/bot/common/report-generation.md b/dev/bot/common/report-generation.md
new file mode 100644
index 00000000000..2ea98910d06
--- /dev/null
+++ b/dev/bot/common/report-generation.md
@@ -0,0 +1,7 @@
+## PDF Report Generation
+
+Use relative paths for images (`![desc](output/screenshot.png)`). Generate PDF from the report directory:
+```bash
+./bin/mage -bot-md-to-pdf <report-directory>/report.md
+```
+For large API responses (>100 lines), save to `output/` and reference the filename. Report absolute paths to both `.md` and `.pdf` files.
diff --git a/dev/bot/common/reproduction-strategies.md b/dev/bot/common/reproduction-strategies.md
new file mode 100644
index 00000000000..c1fbae14e79
--- /dev/null
+++ b/dev/bot/common/reproduction-strategies.md
@@ -0,0 +1,26 @@
+## Reproduction Strategy Selection
+
+Choose the fastest verification path for each issue type:
+
+| Issue Type | Primary Strategy | Secondary |
+|------------|-----------------|-----------|
+| UI / frontend behavior | Playwright + REPL for data setup | API |
+| Setup steps in issue | REPL for data setup, Playwright for UI verification | API |
+| API / endpoint behavior | REPL (invoke handlers directly) or `./bin/mage -bot-api-call` | Code analysis |
+| Query results / SQL generation | REPL: `qp/process-query` or `qp.compile/compile` | Code analysis |
+| Wrong data / DB state | REPL: `t2/select` to inspect | API |
+| Permissions / auth flows | REPL + Playwright | Code analysis |
+| Code logic / edge case | REPL: read source then invoke functions | Direct code comparison |
+| Checking if fixed | Compare source + REPL to test both versions | API verification |
+
+### Efficiency budgets
+
+- **Code search**: Use at most 3-5 Grep calls with broad patterns. Parallelize independent searches. Don't iterate narrow patterns — broaden instead.
+- **Code analysis**: Compare files in at most 5-7 targeted file reads. If root cause isn't clear, pivot to runtime verification. Don't trace full git history.
+- **Backend bugs**: Limit Playwright to 1-2 screenshots for evidence. Don't iterate on UI reproduction if REPL already confirmed the bug.
+
+### Special cases
+
+- **Timing / race conditions**: If reproduction requires simulating slow responses or race conditions that can't be triggered locally, proceed with code analysis. Note that root cause is confirmed via code review but not empirically observable in a single-instance environment.
+- **Time-series bugs**: Test at multiple data densities: ~12 points (monthly/1yr), ~36 (monthly/3yr), ~60 (monthly/5yr). Bug often manifests at specific density where ECharts switches interval logic.
+- **External dependency bugs**: If the bug requires a remote database, LDAP, SMTP, S3, or other external service not available locally, classify as INCONCLUSIVE and note the required infrastructure.
diff --git a/dev/bot/common/test-strategy.md b/dev/bot/common/test-strategy.md
new file mode 100644
index 00000000000..2f978585ee5
--- /dev/null
+++ b/dev/bot/common/test-strategy.md
@@ -0,0 +1,46 @@
+## Test Type Selection
+
+| Bug Type | Test Type | Location |
+|----------|-----------|----------|
+| Backend logic, query processor, API | **Clojure unit test** | `test/metabase/...` |
+| Frontend UI behavior, rendering | **Jest unit/component test** | Co-located `*.unit.spec.tsx` or `frontend/test/...` |
+| End-to-end user workflow, UI interaction | **Cypress acceptance test** | `e2e/test/scenarios/...` |
+| Mixed (backend + frontend) | **Both** — Clojure test for data + frontend/e2e test for UI |
+
+### Find the right test file
+
+- **Backend**: `src/metabase/foo/bar.clj` → `test/metabase/foo/bar_test.clj`
+- **Frontend**: `frontend/src/metabase/foo/Bar.tsx` → `frontend/src/metabase/foo/Bar.unit.spec.tsx`
+- **E2E**: UI workflow → `e2e/test/scenarios/<category>/foo.cy.spec.ts`
+
+Search for existing tests of the buggy function/component first — add to the existing file when possible.
+
+### Backend test approach
+
+| Root Cause Type | Test Approach |
+|----------------|--------------|
+| Query processor bug | `mt/process-query` or `qp/process-query` |
+| API endpoint bug | `mt/user-http-request` |
+| Model / data bug | `mt/with-temp` + `t2/select` |
+| Pure logic / edge case | Direct function call with specific inputs |
+
+### Frontend test approach
+
+| Root Cause Type | Test Approach |
+|----------------|--------------|
+| Component rendering | Jest + React Testing Library — render, assert DOM |
+| User interaction | Cypress — visit page, interact, assert visible result |
+| Data display / formatting | Jest unit test on the formatting/transform function |
+| State management | Jest — test reducer/action/selector with specific inputs |
+
+### Naming conventions
+
+- **Clojure**: `(deftest issue-12345-test ...)` — reference the issue ID
+- **Jest**: `it("should handle X (issue #12345)")` or `it("should not show X when Y (metabase#12345)")`
+- **Cypress**: Descriptive scenario name with issue reference in comment
+
+### Running tests
+
+- **Backend**: `./bin/test-agent :only '[metabase.foo-test/issue-12345-test]'`
+- **Frontend unit**: `bun run test-unit-keep-cljs path/to/file.unit.spec.ts`
+- **Cypress**: `npx cypress run --spec e2e/test/scenarios/category/file.cy.spec.ts`
diff --git a/dev/bot/common/ux-evaluation-criteria.md b/dev/bot/common/ux-evaluation-criteria.md
new file mode 100644
index 00000000000..4f576988ee6
--- /dev/null
+++ b/dev/bot/common/ux-evaluation-criteria.md
@@ -0,0 +1,19 @@
+### UX Evaluation Checklist
+
+For each affected area, evaluate:
+
+- **Visual quality**: Layout correctness, spacing, alignment, typography
+- **Interactive behavior**: Buttons, dropdowns, modals work smoothly; no jank
+- **Loading states**: Spinner/skeleton while data loads, no flash of empty content
+- **Error states**: Clear, helpful error messages when things go wrong
+- **Empty states**: Reasonable display when there's no data
+- **Keyboard navigation**: Tab through interactive elements, correct focus management
+- **Responsive behavior**: Works at different viewport sizes
+- **Light vs. dark mode**: Verify usability in both themes — contrast, legibility, icon/border visibility, no hard-coded colors that break in one mode
+
+### Evidence gathering
+
+- Take screenshots at key moments (before/after actions, unexpected states)
+- Use descriptive filenames (e.g., `03-dropdown-wont-open.png`, `issue-01-before.png`)
+- Always capture the current URL before screenshots
+- Note what works well, not just what's broken — reports should be balanced
diff --git a/dev/bot/workmux-template-pr-env.yaml b/dev/bot/workmux-template-pr-env.yaml
new file mode 100644
index 00000000000..7b2a38bfd7e
--- /dev/null
+++ b/dev/bot/workmux-template-pr-env.yaml
@@ -0,0 +1,25 @@
+agent: "claude --permission-mode auto"
+
+# Empty prefix: tmux session name == --name value, so autobot's session-name
+# lookups (find-session, tmux-session-running?, stop!, quit!) match exactly.
+window_prefix: ""
+
+post_create:
+ # Trust mise.toml early so pane shells don't prompt with "config not trusted"
+ - mise trust
+ # Pull latest changes from origin so the worktree matches the PR commit (only if branch tracks a remote)
+ - bash -c 'git rev-parse --abbrev-ref --symbolic-full-name @{u} >/dev/null 2>&1 && git pull --ff-only || echo "No upstream branch — skipping pull"'
+ # Set up worktree (symlinks, copied files, postgres DB)
+ - bash -c 'MAIN=$(git rev-parse --git-common-dir | sed "s|/\\.git$||"); "$MAIN/bin/mage" -bot-setup-worktree --worktree "$PWD"'
+ # Write PR-env config (URL, PR#, creds) and cache a session token from the remote instance
+ - ./bin/mage -bot-pr-env --url {{PR_ENV_URL}} --pr {{PR_NUM}}
+
+pre_remove: []
+
+panes:
+ - command: <agent>
+ focus: true
+
+ - command: ./bin/mage -bot-status .bot/autobot/llm-status.txt
+ split: vertical
+ size: 10
diff --git a/dev/bot/workmux-template.yaml b/dev/bot/workmux-template.yaml
new file mode 100644
index 00000000000..094c7e82cc2
--- /dev/null
+++ b/dev/bot/workmux-template.yaml
@@ -0,0 +1,33 @@
+agent: "claude --permission-mode auto"
+
+# Empty prefix: tmux session name == --name value, so autobot's session-name
+# lookups (find-session, tmux-session-running?, stop!, quit!) match exactly.
+window_prefix: ""
+
+post_create:
+ # Trust mise.toml early so pane shells don't prompt with "config not trusted"
+ - mise trust
+ # Pull latest changes from origin so the worktree is up to date (only if branch tracks a remote)
+ - bash -c 'git rev-parse --abbrev-ref --symbolic-full-name @{u} >/dev/null 2>&1 && git pull --ff-only || echo "No upstream branch — skipping pull"'
+ # Set up worktree (symlinks, copied files, postgres DB)
+ - bash -c 'MAIN=$(git rev-parse --git-common-dir); MAIN=${MAIN%/.git}; "$MAIN/bin/mage" -bot-setup-worktree --worktree "$PWD"'
+ # Dev environment (DB, mise.local.toml, bot dirs)
+ - ./bin/mage -bot-dev-env --app-db {{APP_DB}} --bot {{BOT_NAME}}
+
+pre_remove:
+ - ./bin/mage -bot-dev-env --down
+
+panes:
+ - command: <agent>
+ focus: true
+
+ - command: clj -M:dev:dev-start:drivers:drivers-dev:ee:ee-dev 2>&1 | tee .bot/autobot/backend-$(date +%Y%m%d-%H%M%S).log
+ split: horizontal
+ percentage: 30
+
+ - command: bun run build-hot 2>&1 | tee .bot/autobot/frontend-$(date +%Y%m%d-%H%M%S).log
+ split: vertical
+
+ - command: ./bin/mage -bot-status .bot/autobot/llm-status.txt
+ split: vertical
+ size: 7
diff --git a/dev/src/user.clj b/dev/src/user.clj
index 58da00321b7..ec145c97f93 100644
--- a/dev/src/user.clj
+++ b/dev/src/user.clj
@@ -2,6 +2,7 @@
(:require
[cider.nrepl :as cider-nrepl]
[clojure.java.io :as io]
+ [clojure.string :as str]
[clojure.tools.cli :as cli]
[environ.core :as env]
[hashp.preload]
@@ -13,6 +14,68 @@
(set! *warn-on-reflection* true)
+(defn- parse-toml-value
+ "Parse a TOML scalar value (RHS of `key = value`). Returns the unquoted string
+ for basic strings (with `\\\"` and `\\\\` escapes), the inner text for literal
+ strings, or the raw token for bare values (integers, booleans). Returns nil for
+ values we don't handle (multi-line strings, arrays, inline tables).
+
+ Mirrors mage.bot.env/parse-toml-value — duplicated here so REPL boot doesn't
+ depend on the mage namespace classpath. Keep the two in sync."
+ [v]
+ (let [v (str/trim v)]
+ (cond
+ ;; Basic string: "..." with \" and \\ escapes. Reject multi-line ("""...) here.
+ (and (str/starts-with? v "\"")
+ (not (str/starts-with? v "\"\"\""))
+ (re-matches #"\"(?:[^\"\\]|\\.)*\"" v))
+ (-> v
+ (subs 1 (dec (count v)))
+ (str/replace #"\\(.)" "$1"))
+
+ ;; Literal string: '...' (no escapes). Reject multi-line ('''...).
+ (and (str/starts-with? v "'")
+ (not (str/starts-with? v "'''"))
+ (re-matches #"'[^']*'" v))
+ (subs v 1 (dec (count v)))
+
+ ;; Bare scalar (int, float, bool) — just hand back the token.
+ (re-matches #"[A-Za-z0-9_+\-.]+" v)
+ v
+
+ :else nil)))
+
+(defn- load-mise-local!
+ "Parse mise.local.toml and merge its [env] values into environ's map.
+ This must run before metabase.config.core loads, which it does since that namespace
+ is loaded lazily via dev/start!.
+
+ Mirrors mage.bot.env/read-mise-local-toml's tolerance: keys may contain word
+ chars, hyphens, or dots, and values may be basic strings (with escapes),
+ literal strings, or bare scalars. Lines we can't parse are silently skipped
+ rather than crashing the REPL boot."
+ []
+ (let [f (io/file "mise.local.toml")]
+ (when (.exists f)
+ (with-open [rdr (io/reader f)]
+ (let [env-vars (->> (line-seq rdr)
+ (drop-while #(not= (str/trim %) "[env]"))
+ (drop 1)
+ (take-while #(not (re-matches #"\s*\[.*\]\s*" %)))
+ (keep (fn [line]
+ (when-let [[_ k raw-v]
+ (re-matches #"\s*([\w.\-]+)\s*=\s*(.*?)\s*" line)]
+ (when-let [v (parse-toml-value raw-v)]
+ (let [kw (-> k
+ str/lower-case
+ (str/replace "_" "-")
+ keyword)]
+ [kw v])))))
+ (into {}))]
+ (alter-var-root #'environ.core/env merge env-vars))))))
+
+(load-mise-local!)
+
(comment
metabase.core.bootstrap/keep-me
hashp.preload/keep-me
diff --git a/mage/src/mage/bot/api_call.clj b/mage/src/mage/bot/api_call.clj
new file mode 100644
index 00000000000..02b9f5b2ba8
--- /dev/null
+++ b/mage/src/mage/bot/api_call.clj
@@ -0,0 +1,112 @@
+(ns mage.bot.api-call
+ "Make HTTP API calls to a Metabase instance — either the locally running
+ dev server or a remote PR preview environment, depending on whether
+ .bot/pr-env.env exists in the current worktree."
+ (:require
+ [babashka.http-client :as http]
+ [babashka.json :as json]
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.bot.pr-env :as pr-env]
+ [mage.color :as c]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn- discover-port
+ "Discover MB_JETTY_PORT using shared env resolution. Exits if unresolved."
+ []
+ (or (bot-env/resolve-env "MB_JETTY_PORT")
+ (do
+ (println (c/red "Could not resolve MB_JETTY_PORT for this worktree."))
+ (println (c/yellow "Run ./bin/mage -bot-dev-env to configure the dev environment,"))
+ (println (c/yellow "or export MB_JETTY_PORT in your shell."))
+ (u/exit 1))))
+
+(defn- local-url [path]
+ (str "http://localhost:" (discover-port) path))
+
+(defn- remote-url [path]
+ (let [env (pr-env/load-pr-env)]
+ (str (get env "BASE_URL") path)))
+
+(defn- do-request
+ "Perform one HTTP request. Returns the response map."
+ [{:keys [method url headers body]}]
+ (let [opts (cond-> {:headers headers :throw false}
+ body (assoc :body body))]
+ (try
+ (http/request (assoc opts :method method :uri url))
+ (catch java.io.IOException e
+ (println (c/red (str "Connection failed: " url)))
+ (let [msg (or (.getMessage e) (str (class e)))]
+ (println msg))
+ (u/exit 1)))))
+
+(defn api-call!
+ "Make an API call to the local or remote Metabase instance.
+ Options (from CLI):
+ positional arg: API path (e.g. /api/card, /api/collection/root)
+ --method HTTP method (default GET)
+ --api-key API key for x-api-key header (local mode; overrides remote session if given)
+ --body JSON request body (for POST/PUT)
+ --pretty Pretty-print JSON output (default true)
+ --raw Suppress the GET/Status diagnostic preamble so stdout is only the
+ response body (suitable for piping into jq/python/etc)"
+ [{:keys [arguments options]}]
+ (let [api-path (first arguments)]
+ (when (str/blank? api-path)
+ (println (c/red "Usage: ./bin/mage -bot-api-call /api/<path> [--method GET|POST|PUT|DELETE] [--api-key <key>] [--body '{...}'] [--raw]"))
+ (u/exit 1))
+
+ (let [method (keyword (str/lower-case (or (:method options) "GET")))
+ api-key (:api-key options)
+ body (:body options)
+ raw? (:raw options)
+ path (if (str/starts-with? api-path "/") api-path (str "/" api-path))
+ remote? (pr-env/pr-env-active?)
+ url (if remote? (remote-url path) (local-url path))
+ session (when (and remote? (not api-key))
+ (or (pr-env/session-token)
+ (pr-env/refresh-session!)))
+ base-hdr {"Content-Type" "application/json"
+ "Accept" "application/json"}
+ headers (cond-> base-hdr
+ api-key (assoc "x-api-key" api-key)
+ session (assoc "X-Metabase-Session" session))]
+
+ ;; Print request info to stderr unless --raw
+ (when-not raw?
+ (binding [*out* *err*]
+ (println (str (str/upper-case (name method)) " " path
+ (if remote? " (remote PR env)" (str " (port " (discover-port) ")"))))))
+
+ (let [first-response (do-request {:method method :url url :headers headers :body body})
+ ;; In remote mode with session auth, retry once on 401 with a fresh token
+ response (if (and remote? session (= 401 (:status first-response)))
+ (let [_ (when-not raw?
+ (binding [*out* *err*]
+ (println (c/yellow "Session token rejected (401) — refreshing and retrying"))))
+ new-token (pr-env/refresh-session!)]
+ (do-request {:method method
+ :url url
+ :headers (assoc base-hdr "X-Metabase-Session" new-token)
+ :body body}))
+ first-response)
+ status (:status response)
+ body-str (:body response)]
+
+ ;; Print status to stderr unless --raw
+ (when-not raw?
+ (binding [*out* *err*]
+ (println (str "Status: " status))))
+
+ ;; Print response body to stdout
+ (when (seq body-str)
+ (if (not= (:pretty options) "false")
+ (try
+ (let [parsed (json/read-str body-str)]
+ (println (json/write-str parsed {:indent true})))
+ (catch Exception _
+ (println body-str)))
+ (println body-str)))))))
diff --git a/mage/src/mage/bot/autobot.clj b/mage/src/mage/bot/autobot.clj
new file mode 100644
index 00000000000..f25010a16b8
--- /dev/null
+++ b/mage/src/mage/bot/autobot.clj
@@ -0,0 +1,524 @@
+(ns mage.bot.autobot
+ "Unified autobot session management — launch, stop, list, quit."
+ (:require
+ [babashka.fs :as fs]
+ [clojure.java.io :as io]
+ [clojure.string :as str]
+ [mage.bot.preflight :as preflight]
+ [mage.color :as c]
+ [mage.shell :as shell]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Session naming and lookup
+
+(defn branch-to-session-name
+ "Convert a branch name to a session name (just the branch slug, no bot prefix).
+ Replaces slashes and other non-alphanumeric chars with dashes.
+ e.g., (branch-to-session-name \"feature/my-branch\") -> \"feature-my-branch\"
+ (branch-to-session-name \"stream-fingerprinting\") -> \"stream-fingerprinting\""
+ [branch-name]
+ (-> branch-name
+ (str/lower-case)
+ (str/replace #"[^a-z0-9-]" "-")
+ (str/replace #"-+" "-")
+ ((fn [s] (subs s 0 (min (count s) 40))))
+ (str/replace #"^-|-$" "")))
+
+(defn- workmux-list-raw
+ "Run `workmux list` and return the raw output lines."
+ []
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true} "workmux" "list")]
+ (if (zero? exit)
+ (vec (remove str/blank? out))
+ [])))
+
+(defn- parse-worktree-name
+ "Extract the worktree name from a workmux list output line."
+ [line]
+ (let [trimmed (str/trim line)]
+ (when-let [path (last (re-find #"(\S+)\s*$" trimmed))]
+ (cond
+ (= path "(here)") nil
+ (str/includes? path "__worktrees/")
+ (second (str/split path #"__worktrees/" 2))
+ :else (last (str/split path #"/"))))))
+
+(defn find-session
+ "Find a session matching the given name or ID. Tries an exact match on the
+ parsed worktree name first; if none, falls back to a case-insensitive
+ substring match on the raw line. Returns the worktree name (suitable for
+ workmux commands) or nil."
+ [name-or-id]
+ (let [needle (str/lower-case (str/trim name-or-id))
+ data (rest (workmux-list-raw))
+ names (keep parse-worktree-name data)
+ exact (some (fn [n] (when (= (str/lower-case n) needle) n)) names)]
+ (or exact
+ (->> data
+ (keep (fn [line]
+ (when (str/includes? (str/lower-case line) needle)
+ (parse-worktree-name line))))
+ first))))
+
+(defn- print-available-sessions!
+ "Print the list of available sessions."
+ []
+ (let [sessions (workmux-list-raw)]
+ (if (seq sessions)
+ (do
+ (println (c/yellow "Available sessions:"))
+ (doseq [s sessions]
+ (println (str " " s))))
+ (println (c/yellow "No active sessions.")))))
+
+(defn worktree-path
+ "Get the filesystem path for a session."
+ [session]
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true} "workmux" "path" session)]
+ (when (zero? exit)
+ (str/trim (str/join "" out)))))
+
+(defn tmux-session-running?
+ "Check if a tmux session with the given name is currently running."
+ [session-name]
+ (let [{:keys [exit]} (shell/sh* {:quiet? true} "tmux" "has-session" "-t" session-name)]
+ (zero? exit)))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Self-detection (for running stop/quit from inside a session)
+
+(defn- current-worktree-path
+ "Return the absolute path of the git worktree the caller is currently in,
+ or nil if not inside a git repo."
+ []
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true :dir (System/getProperty "user.dir")}
+ "git" "rev-parse" "--show-toplevel")]
+ (when (zero? exit)
+ (str/trim (str/join "" out)))))
+
+(defn- main-repo-path
+ "Return the absolute path of the main (common) git repo, or nil if not in a git repo.
+ When run from a linked worktree, this returns the main repo, not the worktree."
+ []
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true :dir (System/getProperty "user.dir")}
+ "git" "rev-parse" "--git-common-dir")]
+ (when (zero? exit)
+ (let [git-dir (str/trim (str/join "" out))
+ abs (str (fs/absolutize git-dir))]
+ (str (fs/parent abs))))))
+
+(defn- detect-current-session
+ "Detect the current session name when the caller is inside a worktree.
+
+ Derives the name from the current worktree's path rather than asking
+ workmux (which has no `current` subcommand). If the caller is in the
+ main repo, returns nil (there's no active session there).
+
+ Strategy:
+ 1. `git rev-parse --show-toplevel` → current worktree path
+ 2. `git rev-parse --git-common-dir` → main repo path
+ 3. If they are the same, we're in the main repo → nil
+ 4. Otherwise take the basename of the worktree path as the session name
+ (autobot always names worktrees with the session slug)."
+ []
+ (let [wt (current-worktree-path)
+ main (main-repo-path)]
+ (when (and wt main (not= wt main))
+ (last (str/split wt #"/")))))
+
+(defn- resolve-session-name
+ "Resolve a session name from arguments, or detect current session if no args."
+ [name-or-id]
+ (if (str/blank? name-or-id)
+ (or (detect-current-session)
+ (do
+ (println (c/red "No session name provided and not inside a session."))
+ (println "Usage: ./bin/mage -autobot-stop <session-name>")
+ (println " (or run from inside a session with no arguments)")
+ (u/exit 1)))
+ (or (find-session name-or-id)
+ (do
+ (println (c/red "No session found matching: ") name-or-id)
+ (print-available-sessions!)
+ (u/exit 1)))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Workmux config generation
+
+(defn- generate-workmux-config
+ "Generate the .workmux.yaml content from a template for a given bot.
+ In PR-env mode (when pr-env-url is non-nil), uses the slim PR-env template
+ instead of the full local-dev template."
+ [{:keys [bot-name app-db pr-env-url pr-num]}]
+ (let [template-path (if pr-env-url
+ (str u/project-root-directory "/dev/bot/workmux-template-pr-env.yaml")
+ (str u/project-root-directory "/dev/bot/workmux-template.yaml"))]
+ (cond-> (slurp template-path)
+ true (str/replace "{{BOT_NAME}}" bot-name)
+ (not pr-env-url) (str/replace "{{APP_DB}}" app-db)
+ pr-env-url (str/replace "{{PR_ENV_URL}}" pr-env-url)
+ pr-num (str/replace "{{PR_NUM}}" pr-num))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Per-launch workmux config
+
+(defn- launch-config-path
+ "Per-launch workmux config path under <root>/.bot/launch/<session>.yaml.
+ The .bot/ directory is gitignored."
+ [root session-name]
+ (str root "/.bot/launch/" session-name ".yaml"))
+
+(defn- with-workmux-config!
+ "Spit `config-content` to `cfg-path`, run `f`, then delete the file even on
+ exception. Used by both launch and relaunch paths."
+ [cfg-path config-content f]
+ (io/make-parents cfg-path)
+ (spit cfg-path config-content)
+ (try (f)
+ (finally
+ (fs/delete-if-exists cfg-path))))
+
+(defn- in-tmux?
+ []
+ (not (str/blank? (u/env "TMUX" (constantly nil)))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Fresh launch (workmux add — creates new worktree)
+
+(defn- launch-workmux-session!
+ "Launch a new workmux session (creates worktree from branch).
+ branch-ref is what workmux add receives as its positional arg — either the
+ existing branch name, or origin/<name> to check out a remote branch.
+
+ When called from outside tmux, we pass `-s` so workmux creates the tmux
+ session itself (no `tmux new-session` shim, no bootstrap-window cleanup
+ loop). The window_prefix is set to \"\" in the template so the resulting
+ session name matches `session-name` exactly."
+ [{:keys [session-name branch-name branch-ref prompt-file workmux-config display-info]}]
+ (let [cfg-path (launch-config-path u/project-root-directory session-name)
+ ref (or branch-ref branch-name)
+ attached? (in-tmux?)]
+ (with-workmux-config! cfg-path workmux-config
+ (fn []
+ ;; Fetch latest refs
+ (println (c/yellow "Fetching latest from remote..."))
+ (shell/sh "git" "fetch")
+
+ (println)
+ (println (c/bold (c/green "Launching workmux session: ") (c/cyan session-name)))
+ (println (c/yellow "Branch: ") branch-name)
+ (doseq [[label value] display-info]
+ (println (c/yellow (str label ": ")) value))
+ (println (c/yellow "Prompt: ") prompt-file)
+ (println)
+
+ ;; Synchronous workmux invocation. With --config we don't touch
+ ;; ./.workmux.yaml. With -s (when not already in tmux) workmux owns
+ ;; session creation. workmux returns once the worktree + window are
+ ;; up, so the cfg file is safe to delete in the finally.
+ (apply shell/sh
+ (concat ["workmux" "add" ref
+ "--config" cfg-path
+ "--name" session-name
+ "-P" prompt-file]
+ (when-not attached? ["-s"])))
+
+ (when-not attached?
+ (println)
+ (println (c/bold (c/green "Tmux session created: ") (c/cyan session-name)))
+ (println)
+ (println "Attach to it with:")
+ (println (str " tmux attach -t " session-name)))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Relaunch (workmux open — reuses existing worktree)
+
+(defn- relaunch-existing-session!
+ "Relaunch a session in an existing worktree.
+ Launches workmux open with --config pointing at a per-launch yaml under
+ <wt-path>/.bot/launch/<session>.yaml. The worktree's own persistent
+ .workmux.yaml is left untouched. The mode (window vs session) is whatever
+ the original `workmux add` recorded.
+
+ `bot-name` is currently unused but kept in the call signature so
+ bot-specific relaunch behavior can be added later without changing callers."
+ [{:keys [_bot-name session-name wt-path prompt-file workmux-config]}]
+ ;; Copy prompt file into worktree as prompt.md. Callers always pass an absolute path.
+ (let [prompt-dest (str wt-path "/prompt.md")]
+ (spit prompt-dest (slurp prompt-file))
+ (println (c/yellow "Copied prompt to " prompt-dest)))
+
+ (let [cfg-path (launch-config-path wt-path session-name)
+ attached? (in-tmux?)]
+ (with-workmux-config! cfg-path workmux-config
+ (fn []
+ (println)
+ (println (c/bold (c/green "Relaunching session: ") (c/cyan session-name)))
+ (println)
+
+ ;; Only kill a leftover tmux session when we're not currently attached
+ ;; to it: killing the session you're attached to evicts the user mid-edit,
+ ;; and `workmux open` will reattach/add a window when one already exists.
+ (when (and (not attached?) (tmux-session-running? session-name))
+ (shell/sh* {:quiet? true} "tmux" "kill-session" "-t" session-name))
+
+ (shell/sh {:dir wt-path}
+ "workmux" "open" session-name
+ "--config" cfg-path
+ "--run-hooks"
+ "-P" "prompt.md")
+
+ (when-not attached?
+ (println)
+ (println (c/bold (c/green "Tmux session created: ") (c/cyan session-name)))
+ (println)
+ (println "Attach to it with:")
+ (println (str " tmux attach -t " session-name)))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Branch validation
+
+(defn- local-branch-exists?
+ "Check if a local git branch with the given name exists."
+ [branch-name]
+ (let [{:keys [exit]} (shell/sh* {:quiet? true}
+ "git" "show-ref" "--verify" "--quiet"
+ (str "refs/heads/" branch-name))]
+ (zero? exit)))
+
+(defn- remote-branch-exists?
+ "Check if a remote git branch origin/<branch-name> exists."
+ [branch-name]
+ (let [{:keys [exit]} (shell/sh* {:quiet? true}
+ "git" "show-ref" "--verify" "--quiet"
+ (str "refs/remotes/origin/" branch-name))]
+ (zero? exit)))
+
+(defn- create-branch!
+ "Create a new local branch <branch-name> pointing at <base-ref>. Exits on failure."
+ [branch-name base-ref]
+ (println (c/yellow "Creating new branch: ") (str branch-name " from " base-ref))
+ (let [{:keys [exit err]} (shell/sh* {:quiet? true} "git" "branch" branch-name base-ref)]
+ (when-not (zero? exit)
+ (println (c/red "Failed to create branch " branch-name " from " base-ref))
+ (doseq [line err] (println (c/red " " line)))
+ (u/exit 1))
+ (println (c/green " Created local branch: ") branch-name)
+ branch-name))
+
+(defn- resolve-branch-ref!
+ "Fetch from origin and verify the branch exists locally or on origin.
+ Returns the ref to pass to workmux add (the branch name if local, or origin/<branch> if remote only).
+
+ The presence of base-branch means the caller wants the branch CREATED:
+ - If the branch does not exist, creates it locally from base-branch.
+ - If the branch already exists, exits with error (the base would otherwise be silently ignored).
+ Without base-branch, the branch must already exist; otherwise exits with error."
+ [branch-name {:keys [base-branch]}]
+ (println (c/yellow "Checking that branch exists: ") branch-name)
+ (shell/sh* {:quiet? true} "git" "fetch" "origin" branch-name)
+ (let [local? (local-branch-exists? branch-name)
+ remote? (remote-branch-exists? branch-name)
+ exists? (or local? remote?)
+ base? (not (str/blank? base-branch))]
+ (cond
+ (and exists? base?)
+ (do
+ (println (c/red "Branch already exists: ") branch-name)
+ (println (c/red " Cannot use 'from " base-branch "' (--base " base-branch ") because " branch-name " already exists."))
+ (println (c/red " Remove 'from <base>' to use the existing branch, or pick a new branch name."))
+ (u/exit 1))
+
+ local?
+ (do
+ (println (c/green " Found local branch: ") branch-name)
+ branch-name)
+
+ remote?
+ (let [remote-ref (str "origin/" branch-name)]
+ (println (c/green " Found remote branch: ") remote-ref)
+ remote-ref)
+
+ base?
+ (create-branch! branch-name base-branch)
+
+ :else
+ (do
+ (println (c/red "Branch not found: ") branch-name)
+ (println (c/red " No local branch and no origin/" branch-name " exists."))
+ (println (c/red " autobot will NOT create new branches — create the branch first,"))
+ (println (c/red " or pass --base <ref> (from <ref> in /autobot) to create it from that ref."))
+ (u/exit 1)))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Launch entry point
+
+(defn go!
+ "Launch a session. Takes --bot, --command, --base, --pr-env-url, and branch name."
+ [{:keys [arguments options]}]
+ (let [branch-name (first arguments)]
+ (when (str/blank? branch-name)
+ (println (c/red "Usage: ./bin/mage -autobot-go <branch-name> --bot <name> --command <cmd> [--pr-env-url <url>]"))
+ (u/exit 1))
+ (let [branch-name (str/trim branch-name)
+ bot-name (:bot options)
+ command (:command options)
+ app-db (or (:app-db options) "postgres")
+ base-branch (:base options)
+ pr-env-url (:pr-env-url options)
+ pr-num (when pr-env-url
+ (second (re-matches #"https://pr(\d+)\.coredev\.metabase\.com/?" pr-env-url)))
+ session-name (branch-to-session-name branch-name)
+ config (generate-workmux-config
+ {:bot-name (or bot-name "autobot")
+ :app-db app-db
+ :pr-env-url pr-env-url
+ :pr-num pr-num})]
+ (when (and pr-env-url (str/blank? pr-num))
+ (println (c/red "Could not extract PR number from --pr-env-url: " pr-env-url))
+ (println (c/red "Expected format: https://pr<NUMBER>.coredev.metabase.com"))
+ (u/exit 1))
+ (preflight/check-workmux!)
+ (when pr-env-url
+ (preflight/check-pr-env-vars!))
+ (when (str/blank? bot-name)
+ (println (c/red "--bot is required"))
+ (u/exit 1))
+ (when (str/blank? command)
+ (println (c/red "--command is required"))
+ (u/exit 1))
+
+ ;; Check for running tmux session
+ (when (tmux-session-running? session-name)
+ (println (c/red "Session " session-name " is already running!"))
+ (println)
+ (println "Attach to it with:")
+ (println (str " tmux attach -t " session-name))
+ (println)
+ (println (str "Stop it first with: /autobot-stop " session-name))
+ (u/exit 1))
+
+ ;; Write the prompt to a temp file — passed to workmux -P for the agent's initial prompt.
+ ;; The file is consumed before this fn returns; deleteOnExit ensures cleanup even on crash.
+ (let [prompt-file (str (System/getProperty "java.io.tmpdir") "/.autobot-prompt-" session-name ".md")]
+ (spit prompt-file command)
+ (.deleteOnExit (java.io.File. ^String prompt-file))
+ (try
+ ;; Check for existing worktree -> relaunch, otherwise fresh launch
+ (let [existing (find-session session-name)
+ wt-path (when existing (worktree-path existing))]
+ (if (and existing wt-path)
+ (do
+ (println (c/yellow "Found existing worktree: " existing))
+ (relaunch-existing-session!
+ {:bot-name bot-name
+ :session-name session-name
+ :wt-path wt-path
+ :prompt-file prompt-file
+ :workmux-config config}))
+ ;; Fresh launch: verify the branch exists somewhere before creating a worktree.
+ ;; Returns the ref to pass to workmux (branch name if local, origin/<name> if remote-only).
+ (let [branch-ref (resolve-branch-ref! branch-name
+ {:base-branch base-branch})
+ info (cond-> {"Bot" bot-name "Command" command}
+ (not pr-env-url) (assoc "App DB" app-db)
+ pr-env-url (assoc "PR Env" pr-env-url
+ "PR #" pr-num))]
+ (launch-workmux-session!
+ {:session-name session-name
+ :branch-name branch-name
+ :branch-ref branch-ref
+ :base-branch base-branch
+ :prompt-file prompt-file
+ :workmux-config config
+ :display-info info}))))
+ (finally
+ (fs/delete-if-exists prompt-file)))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Result lookup
+
+(defn- most-recent-result-md
+ "Given a worktree path and a bot name, find the most recent result.md file
+ under <wt>/.bot/<bot>/*/result.md. Returns the java.io.File or nil."
+ [wt-path bot-name]
+ (let [bot-dir (java.io.File. (str wt-path "/.bot/" bot-name))]
+ (when (.isDirectory bot-dir)
+ (->> (.listFiles bot-dir)
+ (filter #(.isDirectory ^java.io.File %))
+ (map (fn [^java.io.File subdir]
+ (java.io.File. subdir "result.md")))
+ (filter #(.exists ^java.io.File %))
+ (sort-by #(.lastModified ^java.io.File %))
+ last))))
+
+(defn result!
+ "Print the most recent result.md for a given branch+bot combination.
+ Usage: ./bin/mage -autobot-result <branch> <bot>"
+ [{:keys [arguments]}]
+ (let [[branch bot-name] arguments]
+ (when (or (str/blank? branch) (str/blank? bot-name))
+ (println (c/red "Usage: ./bin/mage -autobot-result <branch> <bot>"))
+ (u/exit 1))
+ (let [session-name (branch-to-session-name branch)
+ session (find-session session-name)
+ wt-path (when session (worktree-path session))]
+ (cond
+ (not wt-path)
+ (do
+ (println (c/red "No worktree found for branch: " branch))
+ (print-available-sessions!)
+ (u/exit 1))
+
+ :else
+ (let [result-file (most-recent-result-md wt-path bot-name)]
+ (if result-file
+ (do
+ (println (c/bold (c/cyan "Result file: ")) (.getPath ^java.io.File result-file))
+ (println)
+ (println (slurp result-file)))
+ (do
+ (println (c/yellow (str "No result.md found for bot '" bot-name "' in " wt-path)))
+ (println (c/yellow "The bot may not have started writing one yet, or the bot name is wrong.")))))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Session management
+
+(defn stop!
+ "Stop a session (kill tmux + dev env, keep worktree).
+ Works with a session name argument, or detects current session if no args."
+ [{:keys [arguments]}]
+ (let [session (resolve-session-name (first arguments))
+ wt-path (worktree-path session)]
+ ;; Stop dev environment
+ (when (and wt-path (seq wt-path))
+ (println (c/yellow "Stopping dev environment in " wt-path "..."))
+ (shell/sh* {:quiet? true :dir wt-path} "./bin/mage" "-bot-dev-env" "--down"))
+ ;; Kill tmux session
+ (println (c/yellow "Stopping tmux session: " session "..."))
+ (shell/sh* {:quiet? true} "tmux" "kill-session" "-t" session)
+ (println)
+ (println (c/bold (c/green "Session stopped: ") (c/cyan session)))
+ (println (c/yellow "Worktree preserved. Use /autobot to restart."))))
+
+(defn quit!
+ "Tear down and remove a session.
+ Works with a session name argument, or detects current session if no args."
+ [{:keys [arguments]}]
+ (let [session (resolve-session-name (first arguments))]
+ (println (c/yellow "Removing worktree: " session "..."))
+ (shell/sh* {:quiet? true} "workmux" "remove" "-f" session)
+ (shell/sh* {:quiet? true} "tmux" "kill-session" "-t" session)
+ (println)
+ (println (c/bold (c/green "Session removed: ") (c/cyan session)))))
+
+(defn list-all!
+ "List all sessions with status."
+ [_parsed]
+ (println (c/bold (c/green "Autobot Sessions")))
+ (println)
+ (doseq [line (workmux-list-raw)]
+ (println line)))
diff --git a/mage/src/mage/bot/dev_env.clj b/mage/src/mage/bot/dev_env.clj
new file mode 100644
index 00000000000..a298f96b7e5
--- /dev/null
+++ b/mage/src/mage/bot/dev_env.clj
@@ -0,0 +1,753 @@
+(ns mage.bot.dev-env
+ (:require
+ [babashka.fs :as fs]
+ [babashka.process :as p]
+ [clojure.edn :as edn]
+ [clojure.java.io :as io]
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.bot.preflight :as preflight]
+ [mage.color :as c]
+ [mage.shell :as shell]
+ [mage.util :as u]
+ [table.core :as t]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private root-override (atom nil))
+
+(defn- root [] (or @root-override u/project-root-directory))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Port allocation & Docker infrastructure
+
+(def port-bases
+ {:jetty 3000
+ :frontend-dev 8080
+ :nrepl 50605
+ :socket-repl 50505
+ :postgres-app 15432
+ :postgres-wh 25432
+ :mysql 13309
+ :mariadb 13306
+ :mongo 37017
+ :clickhouse-http 18123
+ :clickhouse-nat 19000
+ :ldap 11389
+ :maildev-smtp 11025
+ :maildev-ui 11080})
+
+(def service-specs
+ "Map of service-key -> spec. :internal-ports is a vector of [host-key internal-port] pairs."
+ {:postgres {:image "postgres:17"
+ :internal-ports [[:postgres-app 5432]]
+ :wh-ports [[:postgres-wh 5432]]
+ :env {"POSTGRES_USER" "metabase"
+ "POSTGRES_DB" "metabase"
+ "POSTGRES_PASSWORD" "password"
+ "PGDATA" "/var/lib/postgresql/data"}
+ :can-be-app-db? true}
+ :mysql {:image "mysql:8.4"
+ :internal-ports [[:mysql 3306]]
+ :env {"MYSQL_DATABASE" "metabase_test"
+ "MYSQL_ALLOW_EMPTY_PASSWORD" "yes"}
+ :can-be-app-db? true}
+ :mariadb {:image "mariadb:11"
+ :internal-ports [[:mariadb 3306]]
+ :env {"MYSQL_DATABASE" "metabase_test"
+ "MYSQL_ALLOW_EMPTY_PASSWORD" "yes"}
+ :can-be-app-db? true}
+ :mongo {:image "mongo:8"
+ :internal-ports [[:mongo 27017]]
+ :env {"MONGO_INITDB_ROOT_USERNAME" "metabase"
+ "MONGO_INITDB_ROOT_PASSWORD" "metasample123"}}
+ :clickhouse {:image "clickhouse/clickhouse-server:latest"
+ :internal-ports [[:clickhouse-http 8123] [:clickhouse-nat 9000]]
+ :env {"CLICKHOUSE_USER" "metabase"
+ "CLICKHOUSE_PASSWORD" "metasample123"}}
+ :ldap {:image "bitnami/openldap:latest"
+ :internal-ports [[:ldap 1389]]
+ :env {"LDAP_ADMIN_USERNAME" "admin"
+ "LDAP_ADMIN_PASSWORD" "adminpassword"}}
+ :maildev {:image "maildev/maildev"
+ :internal-ports [[:maildev-smtp 1025] [:maildev-ui 1080]]
+ :env {}}})
+
+(def shared-db-services
+ "Services that use a shared local instance rather than a per-worktree Docker container."
+ #{:postgres :mysql :mariadb :mongo})
+
+(def bot-dirs
+ "Bot-specific directories to create under .bot/ in the worktree."
+ {"cibot" [".bot/cibot"]
+ "fixbot" [".bot/fixbot/playwright/sessions" ".bot/fixbot/playwright/sockets"]
+ "qabot" [".bot/qabot"]
+ "reprobot" [".bot/reprobot"]
+ "uxbot" [".bot/uxbot/screenshots"]})
+
+(defn worktree-name
+ "Last path component of the given root directory."
+ [root-dir]
+ (last (str/split root-dir #"/")))
+
+(defn db-name
+ "Database name for this worktree: worktree name with non-alphanumeric chars replaced by _."
+ [root-dir]
+ (str/replace (worktree-name root-dir) #"[^a-zA-Z0-9_]" "_"))
+
+(defn compute-slot
+ "Deterministic slot 0-99 from worktree name, or override."
+ [root-dir slot-override]
+ (if slot-override
+ slot-override
+ (Math/floorMod (.hashCode ^String (worktree-name root-dir)) 100)))
+
+(defn container-prefix
+ "Prefix for all docker containers for this worktree."
+ [root-dir]
+ (str "mb-" (worktree-name root-dir) "-"))
+
+(defn port-for
+ "Compute the port for a given service key and slot."
+ [port-key slot]
+ (+ (get port-bases port-key) slot))
+
+(defn check-docker!
+ "Verify docker is available and the daemon is running."
+ []
+ (when-not (u/can-run? "docker")
+ (println (c/red "Docker is not installed. Please install Docker to use dev-env."))
+ (u/exit 1))
+ (let [{:keys [exit]} (shell/sh* {:quiet? true} "docker" "info")]
+ (when-not (zero? exit)
+ (println (c/red "Docker daemon is not running. Please start Docker."))
+ (u/exit 1))))
+
+(defn- kill-container!
+ "Kill and remove a docker container (quiet, no error on missing)."
+ [container-name]
+ (shell/sh* {:quiet? true} "docker" "kill" container-name)
+ (shell/sh* {:quiet? true} "docker" "rm" container-name))
+
+(defn- build-docker-cmd
+ "Build a docker run command vector for a service."
+ [container-name image port-mappings env-map]
+ (into ["docker" "run" "-d"]
+ (concat
+ (mapcat (fn [[host-port internal-port]]
+ ["-p" (str host-port ":" internal-port)])
+ port-mappings)
+ (mapcat (fn [[k v]]
+ ["-e" (str k "=" v)])
+ env-map)
+ ["--name" container-name
+ image])))
+
+(defn start-service!
+ "Kill existing container and start a new one.
+ suffix is typically \"app\" or \"wh\" (warehouse)."
+ [root-dir service-key suffix slot]
+ (let [spec (get service-specs service-key)
+ container-name (str (container-prefix root-dir) (name service-key) (when suffix (str "-" suffix)))
+ port-key-src (if (= suffix "app")
+ (:internal-ports spec)
+ (or (:wh-ports spec) (:internal-ports spec)))
+ port-mappings (mapv (fn [[pk ip]] [(port-for pk slot) ip]) port-key-src)
+ cmd (build-docker-cmd container-name (:image spec) port-mappings (:env spec))]
+ (println (c/yellow "Starting " container-name "..."))
+ (kill-container! container-name)
+ (u/debug "Running: " (str/join " " cmd))
+ (apply shell/sh cmd)
+ (println (c/green " Started ") container-name)))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Incremental mise.local.toml updates
+
+(defn- update-mise-local!
+ "Incrementally update mise.local.toml [env] section. Merges `env-pairs` (a map of
+ {\"KEY\" \"value\"}) into the existing file, preserving keys not in `env-pairs`.
+ Creates the file if it doesn't exist. Optionally prepends `header-lines` (comment strings)."
+ ([root-dir env-pairs]
+ (update-mise-local! root-dir env-pairs nil))
+ ([root-dir env-pairs header-lines]
+ (let [path (str root-dir "/mise.local.toml")
+ existing (or (bot-env/read-mise-local-toml root-dir) {})
+ merged (merge existing env-pairs)
+ lines (cond-> []
+ (seq header-lines)
+ (into header-lines)
+ (seq header-lines)
+ (conj "")
+ true
+ (conj "[env]")
+ true
+ (into (map (fn [[k v]] (str k " = \"" v "\""))
+ (sort-by key merged))))]
+ (spit path (str (str/join "\n" lines) "\n")))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Token env var mapping
+
+(def ^:private token-env-vars
+ {:all-features "MBDEV_ALL_FEATURES_TOKEN"
+ :starter-cloud "MBDEV_STARTER_CLOUD_TOKEN"
+ :pro-cloud "MBDEV_PRO_CLOUD_TOKEN"
+ :pro-self-hosted "MBDEV_PRO_SELF_HOSTED_TOKEN"})
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; TUI prompts
+
+(def ^:private fzf-opts "--height=10 --layout=reverse")
+
+(defn- select-edition
+ "Prompt for edition, or return CLI-provided value."
+ [opts]
+ (or (some-> (:edition opts) keyword)
+ (keyword (u/fzf-select! ["ee" "oss"]
+ (str fzf-opts " --prompt='Edition: '")))))
+
+(defn- select-token
+ "Prompt for token type, or return CLI-provided value."
+ [opts]
+ (or (some-> (:token opts) keyword)
+ (keyword (u/fzf-select! ["all-features" "starter-cloud" "pro-cloud" "pro-self-hosted" "none"]
+ (str fzf-opts " --prompt='Token: '")))))
+
+(defn- select-app-db
+ "Prompt for app database, or return CLI-provided value."
+ [opts]
+ (or (some-> (:app-db opts) keyword)
+ (keyword (u/fzf-select! ["h2" "postgres" "mysql" "mariadb"]
+ (str fzf-opts " --prompt='App database: '")))))
+
+(defn- select-with
+ "Prompt for warehouse services (multi-select), or return CLI-provided values.
+ nil means not specified (prompt); [] means explicitly none (skip prompt)."
+ [opts]
+ (if (some? (:with opts))
+ (mapv keyword (:with opts))
+ (let [result (u/fzf-select! ["postgres" "mysql" "mariadb" "mongo" "clickhouse" "ldap" "maildev" "(none)"]
+ (str fzf-opts " --multi --prompt='Warehouse services (TAB to select): '"))]
+ (if (or (str/blank? result) (= result "(none)"))
+ []
+ (->> (str/split-lines result)
+ (remove #(= % "(none)"))
+ (mapv keyword))))))
+
+(defn- resolve-token-value
+ "Get the actual token string for the given token type."
+ [token]
+ (bot-env/resolve-env (get token-env-vars token) (root)))
+
+(defn- validate-token!
+ "Verify the token value is available (from env var or mise.local.toml)."
+ [token]
+ (when (and token (not= token :none))
+ (when (str/blank? (resolve-token-value token))
+ (let [env-var (get token-env-vars token)]
+ (println (c/red "WARNING: ") (c/yellow env-var) " is not set in your environment!")
+ (println "Set " env-var " with your " (name token) " token, or use --token none")
+ (u/exit 1)))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Core infra
+
+(defn- validate-services!
+ "Validate the app-db and --with values. Returns normalized config map."
+ [{:keys [app-db with]}]
+ (let [valid-app-dbs #{:h2 :postgres :mysql :mariadb}
+ valid-withs #{:postgres :mysql :mariadb :mongo :clickhouse :ldap :maildev}]
+ (when-not (valid-app-dbs app-db)
+ (println (c/red "Invalid --app-db: " (name app-db) ". Must be one of: " (str/join ", " (map name valid-app-dbs))))
+ (u/exit 1))
+ (doseq [w with]
+ (when-not (valid-withs w)
+ (println (c/red "Invalid --with: " (name w) ". Must be one of: " (str/join ", " (map name valid-withs))))
+ (u/exit 1)))
+ ;; Warn if --with overlaps with --app-db
+ (when (and (not= app-db :h2) (some #{app-db} with))
+ (println (c/yellow "Note: --with " (name app-db) " is redundant when --app-db is " (name app-db) ". Using app-db container only.")))
+ {:app-db app-db
+ :with (if (= app-db :h2)
+ with
+ (vec (remove #{app-db} with)))}))
+
+(defn- generate-mise-local!
+ "Incrementally update mise.local.toml with dev-env configuration.
+ Preserves existing keys not being set. When bot-name is provided,
+ uses Docker-based ports; otherwise uses shared local DB instances."
+ [slot {:keys [app-db edition token bot-name]}]
+ (let [wt-name (worktree-name (root))
+ bot-mode? (some? bot-name)
+ env-pairs (cond-> {"MB_JETTY_PORT" (str (port-for :jetty slot))
+ "MB_FRONTEND_DEV_PORT" (str (port-for :frontend-dev slot))
+ "NREPL_PORT" (str (port-for :nrepl slot))
+ "SOCKET_REPL_PORT" (str (port-for :socket-repl slot))
+ "MB_ENABLE_TEST_ENDPOINTS" "true"
+ "MB_DANGEROUS_UNSAFE_ENABLE_TESTING_H2_CONNECTIONS_DO_NOT_ENABLE" "true"}
+
+ ;; Edition
+ edition
+ (assoc "MB_EDITION" (name edition))
+
+ ;; EE token
+ (and (= edition :ee) token (not= token :none))
+ (assoc "MB_PREMIUM_EMBEDDING_TOKEN" (resolve-token-value token)
+ "METASTORE_DEV_SERVER_URL" "https://token-check.staging.metabase.com")
+
+ ;; App DB — bot mode uses Docker containers with slot-based ports
+ (and bot-mode? (= app-db :postgres))
+ (assoc "MB_DB_TYPE" "postgres"
+ "MB_DB_CONNECTION_URI"
+ (str "jdbc:postgresql://localhost:" (port-for :postgres-app slot)
+ "/metabase?user=metabase&password=password"))
+
+ (and bot-mode? (#{:mysql :mariadb} app-db))
+ (assoc "MB_DB_TYPE" "mysql"
+ "MB_DB_CONNECTION_URI"
+ (str "jdbc:mysql://localhost:"
+ (port-for (if (= app-db :mysql) :mysql :mariadb) slot)
+ "/metabase?user=root&password="))
+
+ ;; App DB — personal mode uses shared local instances
+ (and (not bot-mode?) (= app-db :postgres))
+ (assoc "MB_DB_TYPE" "postgres"
+ "MB_DB_CONNECTION_URI"
+ (str "jdbc:postgresql://localhost:5432/"
+ (db-name (root))
+ "?user=metabase&password=password"))
+
+ (and (not bot-mode?) (#{:mysql :mariadb} app-db))
+ (assoc "MB_DB_TYPE" "mysql"
+ "MB_DB_CONNECTION_URI"
+ (str "jdbc:mysql://localhost:3306/"
+ (db-name (root))
+ "?user=root&password="))
+
+ ;; Bot-specific env vars
+ bot-mode?
+ (assoc "DISABLE_BUILD_NOTIFICATIONS" "1"
+ "MB_PREMIUM_EMBEDDING_TOKEN"
+ (or (bot-env/resolve-env "MB_PREMIUM_EMBEDDING_TOKEN" (root))
+ (bot-env/resolve-env "MBDEV_ALL_FEATURES_TOKEN" (root))
+ "")
+ "LINEAR_API_KEY"
+ (or (bot-env/resolve-env "LINEAR_API_KEY" (root)) ""))
+
+ (and bot-mode? bot-name)
+ (assoc "PLAYWRIGHT_DAEMON_SESSION_DIR"
+ (str (root) "/.bot/" bot-name "/playwright/sessions")
+ "PLAYWRIGHT_DAEMON_SOCKETS_DIR"
+ (str (root) "/.bot/" bot-name "/playwright/sockets")))
+
+ headers [(str "# Auto-generated by ./bin/mage -bot-dev-env")
+ (str "# Worktree: " wt-name " (slot " slot ")")
+ "# Re-run `./bin/mage -bot-dev-env` to update."]
+ path (str (root) "/mise.local.toml")]
+ (update-mise-local! (root) env-pairs headers)
+ (println (c/green "Wrote " path))))
+
+(defn- update-idea-datasources!
+ "Update the 'Project Appdb' data source in .idea/dataSources.xml and .idea/dataSources.local.xml
+ to match the current dev-env postgres configuration."
+ [app-db]
+ (when (= app-db :postgres)
+ (let [sources-xml (io/file (root) ".idea/dataSources.xml")
+ local-xml (io/file (root) ".idea/dataSources.local.xml")]
+ (when (.exists sources-xml)
+ (let [content (slurp sources-xml)
+ updated (str/replace content
+ #"(<data-source[^>]*name=\"Project Appdb\"[^>]*>[\s\S]*?<jdbc-url>)([^<]*)(</jdbc-url>)"
+ (str "$1jdbc:postgresql://localhost:5432/" (db-name (root)) "$3"))]
+ (when (not= content updated)
+ (spit sources-xml updated)
+ (println (c/green "Updated .idea/dataSources.xml jdbc-url for Project Appdb")))))
+ (when (.exists local-xml)
+ (let [content (slurp local-xml)
+ updated (str/replace content
+ #"(<data-source[^>]*name=\"Project Appdb\"[\s\S]*?<user-name>)([^<]*)(</user-name>)"
+ "$1metabase$3")]
+ (when (not= content updated)
+ (spit local-xml updated)
+ (println (c/green "Updated .idea/dataSources.local.xml user-name for Project Appdb"))))))))
+
+(defn- collect-container-names
+ "Return the container names that would be created for the given config."
+ [{:keys [app-db with bot-name]}]
+ (let [bot-mode? (some? bot-name)]
+ (cond-> []
+ (and (not= app-db :h2)
+ (or bot-mode? (not (shared-db-services app-db))))
+ (conj (str (container-prefix (root)) (name app-db) "-app"))
+
+ true
+ (into (map #(str (container-prefix (root)) (name %) "-wh")
+ (if bot-mode? with (remove shared-db-services with)))))))
+
+(defn- print-summary!
+ "Print a summary table of ports, containers, and connection info."
+ [slot {:keys [app-db with]}]
+ (let [wt-name (worktree-name (root))
+ rows (cond-> [{:service "Jetty backend" :port (port-for :jetty slot) :env-var "MB_JETTY_PORT"}
+ {:service "Frontend dev" :port (port-for :frontend-dev slot) :env-var "MB_FRONTEND_DEV_PORT"}
+ {:service "nREPL" :port (port-for :nrepl slot) :env-var "NREPL_PORT"}
+ {:service "Socket REPL" :port (port-for :socket-repl slot) :env-var "SOCKET_REPL_PORT"}]
+
+ (= app-db :postgres)
+ (conj {:service (str "Postgres (app-db, db: " (db-name (root)) ")") :port 5432 :env-var "MB_DB_CONNECTION_URI"})
+
+ (= app-db :mysql)
+ (conj {:service (str "MySQL (app-db, db: " (db-name (root)) ")") :port 3306 :env-var "MB_DB_CONNECTION_URI"})
+
+ (= app-db :mariadb)
+ (conj {:service (str "MariaDB (app-db, db: " (db-name (root)) ")") :port 3306 :env-var "MB_DB_CONNECTION_URI"})
+
+ (some #{:postgres} with)
+ (conj {:service (str "Postgres (warehouse, db: " (db-name (root)) "_wh)") :port 5432 :env-var ""})
+
+ (some #{:mysql} with)
+ (conj {:service (str "MySQL (warehouse, db: " (db-name (root)) "_wh)") :port 3306 :env-var ""})
+
+ (some #{:mariadb} with)
+ (conj {:service (str "MariaDB (warehouse, db: " (db-name (root)) "_wh)") :port 3306 :env-var ""})
+
+ (some #{:mongo} with)
+ (conj {:service (str "MongoDB (db: " (db-name (root)) ")") :port 27017 :env-var ""})
+
+ (some #{:clickhouse} with)
+ (conj {:service "ClickHouse HTTP" :port (port-for :clickhouse-http slot) :env-var ""}
+ {:service "ClickHouse native" :port (port-for :clickhouse-nat slot) :env-var ""})
+
+ (some #{:ldap} with)
+ (conj {:service "OpenLDAP" :port (port-for :ldap slot) :env-var ""})
+
+ (some #{:maildev} with)
+ (conj {:service "Maildev SMTP" :port (port-for :maildev-smtp slot) :env-var ""}
+ {:service "Maildev UI" :port (port-for :maildev-ui slot) :env-var ""}))]
+ (println)
+ (println (c/bold (c/green "Dev environment for ") (c/cyan wt-name) (c/green " (slot " slot ")")))
+ (println)
+ (t/table rows :style :unicode)
+ (println)
+ (println (c/cyan "Open a new shell in this worktree for mise to pick up the env vars."))
+ (println (c/cyan "Tear down with: ") (c/yellow "./bin/mage -bot-dev-env --down"))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Session layer — background process management
+
+(defn- state-file-path []
+ (str (root) "/local/.dev-env-state.edn"))
+
+(defn- read-state-file
+ "Read state file, return nil if missing or unreadable."
+ []
+ (let [path (state-file-path)]
+ (when (.exists (java.io.File. path))
+ (try
+ (edn/read-string (slurp path))
+ (catch Exception _ nil)))))
+
+(defn- write-state-file!
+ "Write state to the state file."
+ [state]
+ (spit (state-file-path) (pr-str state)))
+
+(defn- delete-state-file! []
+ (let [f (java.io.File. (state-file-path))]
+ (when (.exists f)
+ (.delete f))))
+
+(defn- pid-alive?
+ "Check if a process with the given PID is still running."
+ [pid]
+ (let [{:keys [exit]} (shell/sh* {:quiet? true} "kill" "-0" (str pid))]
+ (zero? exit)))
+
+(defn- kill-pid!
+ "Kill a process by PID (SIGTERM, then SIGKILL after 5s)."
+ [pid label]
+ (when (pid-alive? pid)
+ (println (c/yellow "Stopping " label " (PID " pid ")..."))
+ (shell/sh* {:quiet? true} "kill" (str pid))
+ (Thread/sleep 2000)
+ (when (pid-alive? pid)
+ (shell/sh* {:quiet? true} "kill" "-9" (str pid)))
+ (println (c/green " Stopped " label "."))))
+
+(defn- build-env
+ "Assemble the env map for spawning backend/frontend processes."
+ [slot {:keys [app-db edition token]}]
+ (cond-> {"MB_JETTY_PORT" (str (port-for :jetty slot))
+ "MB_FRONTEND_DEV_PORT" (str (port-for :frontend-dev slot))
+ "NREPL_PORT" (str (port-for :nrepl slot))
+ "SOCKET_REPL_PORT" (str (port-for :socket-repl slot))
+ "MB_ENABLE_TEST_ENDPOINTS" "true"
+ "MB_DANGEROUS_UNSAFE_ENABLE_TESTING_H2_CONNECTIONS_DO_NOT_ENABLE" "true"}
+
+ edition
+ (assoc "MB_EDITION" (name edition))
+
+ (and (= edition :ee) token (not= token :none))
+ (assoc "MB_PREMIUM_EMBEDDING_TOKEN" (resolve-token-value token)
+ "METASTORE_DEV_SERVER_URL" "https://token-check.staging.metabase.com")
+
+ (= app-db :postgres)
+ (assoc "MB_DB_TYPE" "postgres"
+ "MB_DB_CONNECTION_URI" (str "jdbc:postgresql://localhost:5432/"
+ (db-name (root))
+ "?user=metabase&password=password"))
+
+ (#{:mysql :mariadb} app-db)
+ (assoc "MB_DB_TYPE" "mysql"
+ "MB_DB_CONNECTION_URI" (str "jdbc:mysql://localhost:3306/"
+ (db-name (root))
+ "?user=root&password="))))
+
+(defn- build-aliases
+ "Build Clojure alias string for the backend process."
+ [edition]
+ (str ":dev:dev-start:drivers:drivers-dev"
+ (when (= edition :ee) ":ee:ee-dev")))
+
+(defn- start-backend!
+ "Launch backend process in background. Returns PID."
+ [slot edition env-map]
+ (let [aliases (build-aliases edition)
+ nrepl-port (str (port-for :nrepl slot))
+ log-file (str "/tmp/mb-" (worktree-name (root)) "-backend.log")
+ cmd ["clojure" (str "-M" aliases) "-p" nrepl-port]
+ log (java.io.File. log-file)
+ proc (apply p/process {:dir (root)
+ :out log
+ :err log
+ :extra-env env-map}
+ cmd)]
+ (println (c/green "Started backend") (c/cyan "(PID " (.pid (:proc proc)) ")"))
+ (println (c/cyan " Aliases: ") aliases)
+ (println (c/cyan " nREPL: ") nrepl-port)
+ (println (c/cyan " Log: ") (c/yellow (str "tail -f " log-file)))
+ {:pid (.pid (:proc proc))
+ :log-file log-file}))
+
+(defn- start-frontend!
+ "Launch frontend dev server in background. Returns PID."
+ [env-map]
+ (let [log-file (str "/tmp/mb-" (worktree-name (root)) "-frontend.log")
+ log (java.io.File. log-file)
+ proc (p/process {:dir (root)
+ :out log
+ :err log
+ :extra-env env-map}
+ "yarn" "build-hot")]
+ (println (c/green "Started frontend") (c/cyan "(PID " (.pid (:proc proc)) ")"))
+ (println (c/cyan " Log: ") (c/yellow (str "tail -f " log-file)))
+ {:pid (.pid (:proc proc))
+ :log-file log-file}))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Config reuse
+
+(defn- prompt-reuse-config?
+ "If a saved config exists and no CLI flags override it, ask the user whether to reuse."
+ [opts]
+ (let [state (read-state-file)
+ has-cli-overrides? (or (:edition opts) (:token opts) (:app-db opts) (seq (:with opts)))]
+ (when (and (:config state) (not has-cli-overrides?))
+ (let [cfg (:config state)
+ summary (str (name (:edition cfg)) " / " (name (:app-db cfg))
+ (when (seq (:with cfg))
+ (str " + " (str/join ", " (map name (:with cfg))))))]
+ (= "yes"
+ (u/fzf-select! ["yes" "no"]
+ (str fzf-opts " --prompt='Reuse saved config (" summary ")? '")))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Entry points
+
+(defn- start-processes!
+ "Launch backend + frontend. Updates state file with PIDs."
+ [opts slot full-config]
+ ;; Kill any already-running processes first
+ (when-let [state (read-state-file)]
+ (when-let [pid (get-in state [:backend :pid])]
+ (when (pid-alive? pid)
+ (kill-pid! pid "backend")))
+ (when-let [pid (get-in state [:frontend :pid])]
+ (when (pid-alive? pid)
+ (kill-pid! pid "frontend"))))
+ (println)
+ (println (c/bold (c/green "Launching dev processes...")))
+ (println)
+ (let [env-map (build-env slot full-config)
+ backend (start-backend! slot (:edition full-config) env-map)
+ frontend (when-not (:no-frontend opts)
+ (start-frontend! env-map))
+ state (cond-> (merge (read-state-file)
+ {:backend backend})
+ frontend (assoc :frontend frontend))]
+ (write-state-file! state)
+ (println)
+ (println (c/bold (c/green "Dev environment is running in the background.")))
+ (println (c/cyan "Stop with: ") (c/yellow "./bin/mage -bot-dev-env --down"))))
+
+(defn- create-bot-dirs!
+ "Create all bot directories and .autobot/ with initial status file."
+ [_bot-name]
+ ;; Create all bot-specific dirs
+ (doseq [[_ dirs] bot-dirs]
+ (doseq [dir dirs]
+ (fs/create-dirs (str (root) "/" dir))))
+ ;; Create .bot/autobot/ and initial status file
+ (fs/create-dirs (str (root) "/.bot/autobot"))
+ (let [status-path (str (root) "/.bot/autobot/llm-status.txt")]
+ (when-not (fs/exists? status-path)
+ (spit status-path "Starting up")))
+ (println (c/green " Created bot directories")))
+
+(defn- stand-up!
+ "Orchestrate: prompt -> validate -> check docker -> start containers -> write toml -> optionally run.
+ When --bot is provided, skips interactive prompts and uses Docker containers."
+ [opts]
+ (let [bot-name (:bot opts)
+ bot-mode? (some? bot-name)
+ reuse? (and (not bot-mode?) (prompt-reuse-config? opts))
+ saved (when reuse? (:config (read-state-file)))
+ edition (or (:edition saved)
+ (if bot-mode? :ee (select-edition opts)))
+ token (if saved
+ (:token saved)
+ (if bot-mode?
+ :all-features
+ (when (= edition :ee)
+ (let [t (select-token opts)]
+ (validate-token! t)
+ t))))
+ app-db (or (:app-db saved)
+ (some-> (:app-db opts) keyword)
+ (if bot-mode? :postgres (select-app-db opts)))
+ with (or (:with saved)
+ (if bot-mode? [] (select-with opts)))
+ slot (compute-slot (root) (:slot opts))
+ config (validate-services! {:app-db app-db :with with})
+ full-config (assoc config :edition edition :token token :bot-name bot-name)]
+ ;; In bot mode, always use Docker containers (never shared local DB)
+ ;; In personal mode, only Docker for non-shared services
+ (let [docker-app-db (when (not= (:app-db config) :h2)
+ (if bot-mode?
+ (:app-db config)
+ (when-not (shared-db-services (:app-db config))
+ (:app-db config))))
+ docker-with (if bot-mode?
+ (:with config)
+ (remove shared-db-services (:with config)))]
+ (when (or docker-app-db (seq docker-with))
+ (check-docker!))
+ (when docker-app-db
+ (start-service! (root) docker-app-db "app" slot))
+ (doseq [svc docker-with]
+ (start-service! (root) svc "wh" slot)))
+ ;; Create bot dirs (cheap, always do it)
+ (when bot-mode?
+ (create-bot-dirs! bot-name))
+ ;; Write mise.local.toml (incremental update)
+ (generate-mise-local! slot full-config)
+ ;; Update IntelliJ data source config (personal mode only)
+ (when-not bot-mode?
+ (update-idea-datasources! (:app-db config)))
+ ;; Save config to state file
+ (write-state-file! {:slot slot
+ :config full-config
+ :containers (collect-container-names config)})
+ ;; Print summary
+ (print-summary! slot config)
+ ;; Optionally launch processes
+ (when (:run opts)
+ (start-processes! opts slot full-config))))
+
+(defn- tear-down!
+ "Find all containers for this worktree, kill/rm them, kill processes, clean up."
+ []
+ ;; Kill processes from state file
+ (when-let [state (read-state-file)]
+ (when-let [pid (get-in state [:backend :pid])]
+ (kill-pid! pid "backend"))
+ (when-let [pid (get-in state [:frontend :pid])]
+ (kill-pid! pid "frontend")))
+ ;; Kill containers
+ (check-docker!)
+ (let [prefix (container-prefix (root))
+ {:keys [out]} (shell/sh* {:quiet? true}
+ "docker" "ps" "-a"
+ "--filter" (str "name=^" prefix)
+ "--format" "{{.Names}}")
+ containers (when (seq out)
+ (->> out
+ (remove str/blank?)
+ vec))]
+ (if (seq containers)
+ (do
+ (println (c/yellow "Stopping containers:"))
+ (doseq [cname containers]
+ (println (c/red " Killing " cname))
+ (kill-container! cname))
+ (println (c/green "All containers stopped.")))
+ (println (c/yellow "No containers found for prefix: " prefix))))
+ ;; Leave mise.local.toml in place — the user may have added their own [env] keys
+ ;; and `update-mise-local!` only merges, never overwrites unrelated values.
+ ;; Remove state file
+ (delete-state-file!))
+
+(defn- print-status!
+ "Show running containers and processes for this worktree."
+ []
+ ;; Process status
+ (when-let [state (read-state-file)]
+ (println (c/bold (c/green "Processes:")))
+ (println)
+ (let [rows (cond-> []
+ (:backend state)
+ (conj {:process "Backend"
+ :pid (get-in state [:backend :pid])
+ :status (if (pid-alive? (get-in state [:backend :pid])) "running" "stopped")
+ :log (get-in state [:backend :log-file])})
+
+ (:frontend state)
+ (conj {:process "Frontend"
+ :pid (get-in state [:frontend :pid])
+ :status (if (pid-alive? (get-in state [:frontend :pid])) "running" "stopped")
+ :log (get-in state [:frontend :log-file])}))]
+ (when (seq rows)
+ (t/table rows :style :unicode)
+ (println))))
+ ;; Container status
+ (check-docker!)
+ (let [prefix (container-prefix (root))
+ {:keys [out]} (shell/sh* {:quiet? true}
+ "docker" "ps" "-a"
+ "--filter" (str "name=^" prefix)
+ "--format" "{{.Names}}\t{{.Status}}\t{{.Ports}}")
+ lines (when (seq out)
+ (->> out (remove str/blank?) vec))]
+ (if (seq lines)
+ (let [rows (mapv (fn [line]
+ (let [[cname status ports] (str/split line #"\t" 3)]
+ {:container cname
+ :status (or status "")
+ :ports (or ports "")}))
+ lines)]
+ (println (c/bold (c/green "Containers for " (worktree-name (root)) ":")))
+ (println)
+ (t/table rows :style :unicode))
+ (println (c/yellow "No containers found for " (worktree-name (root)))))))
+
+(defn dev-env!
+ "Top-level dispatcher for dev-env command."
+ [{:keys [options]}]
+ (when (:worktree options)
+ (reset! root-override (:worktree options)))
+ (let [{:keys [down status]} options]
+ (cond
+ down (tear-down!)
+ status (print-status!)
+ :else (do (preflight/check-mise!)
+ (stand-up! options)))))
diff --git a/mage/src/mage/bot/env.clj b/mage/src/mage/bot/env.clj
new file mode 100644
index 00000000000..665662511fe
--- /dev/null
+++ b/mage/src/mage/bot/env.clj
@@ -0,0 +1,125 @@
+(ns mage.bot.env
+ "Environment variable resolution across dev infrastructure.
+ Priority order: mise.local.toml > .env > .lein-env > system env."
+ (:require
+ [clojure.edn :as edn]
+ [clojure.java.io :as io]
+ [clojure.string :as str]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn- parse-toml-value
+ "Parse a TOML scalar value (RHS of `key = value`). Returns the unquoted string
+ for basic strings (with `\\\"` and `\\\\` escapes), the inner text for literal
+ strings, or the raw token for bare scalars (ints, bools). Returns nil for
+ values we don't handle (multi-line strings, arrays, inline tables)."
+ [v]
+ (let [v (str/trim v)]
+ (cond
+ (and (str/starts-with? v "\"")
+ (not (str/starts-with? v "\"\"\""))
+ (re-matches #"\"(?:[^\"\\]|\\.)*\"" v))
+ (-> v
+ (subs 1 (dec (count v)))
+ (str/replace #"\\(.)" "$1"))
+
+ (and (str/starts-with? v "'")
+ (not (str/starts-with? v "'''"))
+ (re-matches #"'[^']*'" v))
+ (subs v 1 (dec (count v)))
+
+ (re-matches #"[A-Za-z0-9_+\-.]+" v)
+ v
+
+ :else nil)))
+
+(defn read-mise-local-toml
+ "Parse mise.local.toml [env] section and return a map of env var name -> value.
+ Handles double-quoted strings (with escapes), single-quoted literal strings,
+ and bare scalars. Keys may contain word chars, hyphens, or dots."
+ ([] (read-mise-local-toml u/project-root-directory))
+ ([root-dir]
+ (let [path (str root-dir "/mise.local.toml")]
+ (when (.exists (java.io.File. ^String path))
+ (with-open [rdr (io/reader path)]
+ (->> (line-seq rdr)
+ (drop-while #(not= (str/trim %) "[env]"))
+ (drop 1)
+ (take-while #(not (re-matches #"\s*\[.*\]\s*" %)))
+ (keep (fn [line]
+ (when-let [[_ k raw-v] (re-matches #"\s*([\w.\-]+)\s*=\s*(.*?)\s*" line)]
+ (when-let [v (parse-toml-value raw-v)]
+ [k v]))))
+ (into {})))))))
+
+(defn read-dot-env
+ "Parse .env file and return a map of env var name -> value.
+ Supports KEY=value, export KEY=value, and quoted values."
+ ([] (read-dot-env u/project-root-directory))
+ ([root-dir]
+ (let [path (str root-dir "/.env")]
+ (when (.exists (java.io.File. ^String path))
+ (into {}
+ (keep (fn [line]
+ (let [trimmed (-> (str/trim line)
+ (str/replace #"^\s*export\s+" ""))]
+ (when (and (seq trimmed)
+ (not (str/starts-with? trimmed "#"))
+ (str/includes? trimmed "="))
+ (let [idx (str/index-of trimmed "=")
+ k (str/trim (subs trimmed 0 idx))
+ v (-> (subs trimmed (inc idx))
+ str/trim
+ (str/replace #"^\"(.*)\"$" "$1")
+ (str/replace #"^'(.*)'$" "$1"))]
+ [k v])))))
+ (str/split-lines (slurp path)))))))
+
+(defn read-lein-env
+ "Parse .lein-env (EDN map with keyword keys) and return a map of env var name -> value."
+ ([] (read-lein-env u/project-root-directory))
+ ([root-dir]
+ (let [path (str root-dir "/.lein-env")]
+ (when (.exists (java.io.File. ^String path))
+ (try
+ (into {}
+ (map (fn [[k v]]
+ [(-> (name k)
+ (str/replace "-" "_")
+ str/upper-case)
+ (str v)]))
+ (edn/read-string (slurp path)))
+ (catch Exception _e nil))))))
+
+(defn resolve-env
+ "Resolve an environment variable with priority: mise.local.toml > .env > .lein-env > system env.
+ Returns the value or nil if not found in any source."
+ ([var-name]
+ (resolve-env var-name u/project-root-directory))
+ ([var-name root-dir]
+ (or (get (read-mise-local-toml root-dir) var-name)
+ (get (read-dot-env root-dir) var-name)
+ (get (read-lein-env root-dir) var-name)
+ (let [v (System/getenv var-name)] (when-not (str/blank? v) v)))))
+
+(defn resolve-all
+ "Resolve all environment variables from all sources, with mise.local.toml > .env > .lein-env > system env.
+ Returns a sorted map of all resolved vars."
+ ([] (resolve-all u/project-root-directory))
+ ([root-dir]
+ (let [mise-map (or (read-mise-local-toml root-dir) {})
+ dot-env-map (or (read-dot-env root-dir) {})
+ lein-map (or (read-lein-env root-dir) {})
+ all-keys (into (sorted-set)
+ (concat (keys mise-map)
+ (keys dot-env-map)
+ (keys lein-map)))]
+ (into (sorted-map)
+ (keep (fn [k]
+ (when-let [v (or (get mise-map k)
+ (get dot-env-map k)
+ (get lein-map k)
+ (let [v (System/getenv k)] (when-not (str/blank? v) v)))]
+ [k v])))
+ all-keys))))
diff --git a/mage/src/mage/bot/linear.clj b/mage/src/mage/bot/linear.clj
new file mode 100644
index 00000000000..a20b56b278e
--- /dev/null
+++ b/mage/src/mage/bot/linear.clj
@@ -0,0 +1,112 @@
+(ns mage.bot.linear
+ (:require
+ [babashka.http-client :as http]
+ [babashka.json :as json]
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.color :as c]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private linear-api-url "https://api.linear.app/graphql")
+
+(defn- get-api-key!
+ "Get LINEAR_API_KEY using shared env resolution. Exit with instructions if not found."
+ []
+ (or (bot-env/resolve-env "LINEAR_API_KEY")
+ (do
+ (println (c/red "LINEAR_API_KEY not found in mise.local.toml, .env, .lein-env, or environment."))
+ (println)
+ (println "To get a Linear API key:")
+ (println " 1. Go to https://linear.app/metabase/settings/account/security/api-keys/new")
+ (println " 2. Create a personal API key")
+ (println " 3. Add it to .env: LINEAR_API_KEY=lin_api_...")
+ (u/exit 1))))
+
+(def ^:private issue-query
+ "query IssueByIdentifier($id: String!) {
+ issue(id: $id) {
+ identifier
+ title
+ description
+ url
+ branchName
+ state { name }
+ comments {
+ nodes {
+ body
+ user { name }
+ createdAt
+ }
+ }
+ }
+ }")
+
+(defn fetch-issue
+ "Fetch a Linear issue by identifier (e.g. MB-12345).
+ Returns a map with :identifier, :title, :description, :url, :state, :comments
+ or nil if not found."
+ [issue-id]
+ (let [api-key (get-api-key!)
+ payload (json/write-str {:query issue-query
+ :variables {:id issue-id}})
+ resp (try
+ (http/post linear-api-url
+ {:headers {"Content-Type" "application/json"
+ "Authorization" api-key}
+ :body payload
+ :throw false})
+ (catch Exception e
+ (println (c/red "Linear API request failed: ") (.getMessage e))
+ (u/exit 1)))
+ response (json/read-str (:body resp) {:key-fn keyword})]
+ (when-let [errors (:errors response)]
+ (println (c/red "Linear API error:") (pr-str errors))
+ (u/exit 1))
+ (when-let [issue (get-in response [:data :issue])]
+ {:identifier (:identifier issue)
+ :title (:title issue)
+ :description (or (:description issue) "")
+ :url (:url issue)
+ :branch-name (:branchName issue)
+ :state (get-in issue [:state :name])
+ :comments (mapv (fn [c]
+ {:body (:body c)
+ :author (get-in c [:user :name])
+ :created-at (:createdAt c)})
+ (get-in issue [:comments :nodes]))})))
+
+(defn print-issue!
+ "Fetch and print a Linear issue. Entry point for the CLI task."
+ [{:keys [arguments]}]
+ (let [issue-id (first arguments)]
+ (when (str/blank? issue-id)
+ (println (c/red "Usage: ./bin/mage -fixbot-fetch-issue MB-12345"))
+ (u/exit 1))
+ (let [issue-id (str/upper-case (str/trim issue-id))]
+ (when-not (re-matches #"[A-Z]+-\d+" issue-id)
+ (println (c/red "Invalid issue identifier: " issue-id))
+ (println "Expected format: MB-12345")
+ (u/exit 1))
+ (println (c/yellow "Fetching " issue-id "..."))
+ (if-let [issue (fetch-issue issue-id)]
+ (do
+ (println)
+ (println (c/bold (c/green (:identifier issue))) " — " (c/bold (:title issue)))
+ (println (c/cyan (:url issue)))
+ (println (c/yellow "State: ") (:state issue))
+ (println (c/yellow "Branch: ") (:branch-name issue))
+ (println)
+ (println (c/bold "Description:"))
+ (println (:description issue))
+ (when (seq (:comments issue))
+ (println)
+ (println (c/bold "Comments:"))
+ (doseq [comment (:comments issue)]
+ (println)
+ (println (c/cyan (:author comment)) " — " (:created-at comment))
+ (println (:body comment)))))
+ (do
+ (println (c/red "Issue not found: " issue-id))
+ (u/exit 1))))))
diff --git a/mage/src/mage/bot/pr_env.clj b/mage/src/mage/bot/pr_env.clj
new file mode 100644
index 00000000000..a96041499c9
--- /dev/null
+++ b/mage/src/mage/bot/pr_env.clj
@@ -0,0 +1,148 @@
+(ns mage.bot.pr-env
+ "PR preview environment support for autobot.
+ Writes .bot/pr-env.env and .bot/pr-env-session.txt in the current worktree
+ so -bot-api-call and -bot-server-info can detect remote mode and talk to
+ the deployed PR env at https://pr<PR#>.coredev.metabase.com."
+ (:require
+ [babashka.http-client :as http]
+ [babashka.json :as json]
+ [clojure.string :as str]
+ [mage.bot.preflight :as preflight]
+ [mage.color :as c]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn- pr-env-dir
+ "Return the .bot directory inside the current user cwd (the worktree).
+ Creates it if it doesn't exist."
+ []
+ (let [dir (java.io.File. ^String (System/getProperty "user.dir") ".bot")]
+ (.mkdirs dir)
+ dir))
+
+(defn- env-file [] (java.io.File. ^java.io.File (pr-env-dir) "pr-env.env"))
+(defn- session-file [] (java.io.File. ^java.io.File (pr-env-dir) "pr-env-session.txt"))
+
+(defn- login!
+ "POST to {base-url}/api/session with creds. Returns the session token string,
+ or throws an ex-info with :status and :body on failure."
+ [base-url username password]
+ (let [url (str base-url "/api/session")
+ body (json/write-str {:username username :password password})
+ resp (try
+ (http/post url {:headers {"Content-Type" "application/json"
+ "Accept" "application/json"}
+ :body body
+ :throw false})
+ (catch Exception e
+ (throw (ex-info (str "Connection failed to " url)
+ {:url url :cause (.getMessage e)}))))
+ status (:status resp)
+ body-str (:body resp)]
+ (if (= status 200)
+ (let [parsed (json/read-str body-str)]
+ (or (get parsed :id) (get parsed "id")
+ (throw (ex-info "Login response missing session id"
+ {:status status :body body-str}))))
+ (throw (ex-info (str "Login failed: HTTP " status)
+ {:status status :body body-str :url url})))))
+
+(defn- write-env-file!
+ "Write .bot/pr-env.env with the PR env config."
+ [{:keys [base-url pr-num repl-host username password]}]
+ (spit (env-file)
+ (str "BASE_URL=" base-url "\n"
+ "PR_NUM=" pr-num "\n"
+ "REPL_HOST=" repl-host "\n"
+ "REPL_PORT=" pr-num "\n"
+ "USERNAME=" username "\n"
+ "PASSWORD=" password "\n")))
+
+(defn- read-env-file
+ "Read .bot/pr-env.env into a map of string keys. Returns nil if missing."
+ []
+ (let [f (env-file)]
+ (when (.exists f)
+ (into {}
+ (keep (fn [line]
+ (let [line (str/trim line)]
+ (when (and (seq line)
+ (not (str/starts-with? line "#"))
+ (str/includes? line "="))
+ (let [[k v] (str/split line #"=" 2)]
+ [(str/trim k) (str/trim v)])))))
+ (str/split-lines (slurp f))))))
+
+(defn pr-env-active?
+ "True when the current worktree is configured for remote PR-env mode
+ (detected by the presence of .bot/pr-env.env)."
+ []
+ (.exists (env-file)))
+
+(defn load-pr-env
+ "Read .bot/pr-env.env and return a map, or nil if not in PR-env mode."
+ []
+ (read-env-file))
+
+(defn session-token
+ "Read the cached session token from .bot/pr-env-session.txt, or nil."
+ []
+ (let [f (session-file)]
+ (when (.exists f)
+ (str/trim (slurp f)))))
+
+(defn refresh-session!
+ "Re-login using the cached creds and overwrite the session token file.
+ Returns the new token. Throws on failure."
+ []
+ (let [env (read-env-file)]
+ (when-not env
+ (throw (ex-info ".bot/pr-env.env not found — not in PR-env mode" {})))
+ (let [token (login! (get env "BASE_URL")
+ (get env "USERNAME")
+ (get env "PASSWORD"))]
+ (spit (session-file) (str token "\n"))
+ token)))
+
+(defn setup!
+ "CLI entry point: write .bot/pr-env.env, log in, cache session token.
+ Required options: --url, --pr"
+ [{:keys [options]}]
+ (let [{:keys [url pr]} options]
+ (when (or (str/blank? url) (str/blank? pr))
+ (println (c/red "Usage: ./bin/mage -bot-pr-env --url <URL> --pr <PR_NUMBER>"))
+ (u/exit 1))
+ (preflight/check-mise!)
+ (let [resolved (preflight/check-pr-env-vars!)
+ username (get resolved "PR_ENV_USERNAME")
+ password (get resolved "PR_ENV_PASSWORD")
+ repl-host (get resolved "PR_ENV_REPL_HOST")
+ cfg {:base-url url
+ :pr-num pr
+ :repl-host repl-host
+ :username username
+ :password password}]
+ (println (c/bold (c/green "Configuring PR preview environment")))
+ (println (c/yellow " URL: ") url)
+ (println (c/yellow " PR: ") pr)
+ (println (c/yellow " Username: ") username)
+ (println)
+
+ (write-env-file! cfg)
+ (println (c/green " Wrote .bot/pr-env.env"))
+
+ (try
+ (let [token (login! url username password)]
+ (spit (session-file) (str token "\n"))
+ (println (c/green " Logged in, cached session token to .bot/pr-env-session.txt"))
+ (println)
+ (println (c/bold (c/green "PR preview environment ready."))))
+ (catch clojure.lang.ExceptionInfo e
+ (println)
+ (println (c/red "Login failed: ") (ex-message e))
+ (println)
+ (println (c/yellow "Likely cause: you are not on the Metabase Tailscale network."))
+ (println (c/yellow "PR preview environments are only reachable via Tailscale."))
+ (println (c/yellow "Verify connectivity: curl -v " url "/api/health"))
+ (u/exit 1))))))
diff --git a/mage/src/mage/bot/preflight.clj b/mage/src/mage/bot/preflight.clj
new file mode 100644
index 00000000000..633b627f3d4
--- /dev/null
+++ b/mage/src/mage/bot/preflight.clj
@@ -0,0 +1,237 @@
+(ns mage.bot.preflight
+ "Composable preflight checks shared across bot types."
+ (:require
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.color :as c]
+ [mage.shell :as shell]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn check-mise!
+ "Check that mise is installed and activated in the current shell (so that
+ managed tools like clj, bun, bb resolve on PATH without a `mise x --` prefix).
+ Exits on failure."
+ []
+ (when-not (u/can-run? "mise")
+ (println (c/red "mise is not installed."))
+ (println "Install it: https://mise.jdx.dev/getting-started.html")
+ (u/exit 1))
+ (let [needed ["clj" "bun" "bb"]
+ missing (binding [u/*skip-warning* true]
+ (doall (remove u/can-run? needed)))]
+ (when (seq missing)
+ (println (c/red "mise does not appear to be activated in this shell."))
+ (println (c/red (str "Not on PATH: " (str/join ", " missing))))
+ (println)
+ (println "Activate mise in your shell profile, for example:")
+ (println " eval \"$(mise activate zsh)\" # zsh")
+ (println " eval \"$(mise activate bash)\" # bash")
+ (println "Then re-run in a shell where mise is active.")
+ (u/exit 1))))
+
+(def ^:private workmux-min-version
+ "Minimum workmux version required. 0.1.187 added the --config flag, which
+ we rely on to avoid writing .workmux.yaml at the repo root."
+ [0 1 187])
+
+(defn- parse-workmux-version
+ "Parse `workmux 0.1.189` (or just `0.1.189`) into [0 1 189], or nil if unparseable."
+ [s]
+ (when-let [[_ a b c] (re-find #"(\d+)\.(\d+)\.(\d+)" (or s ""))]
+ [(Integer/parseInt a) (Integer/parseInt b) (Integer/parseInt c)]))
+
+(defn- version<?
+ "True when version a (vector of ints) is strictly less than b."
+ [a b]
+ (neg? (compare a b)))
+
+(defn check-workmux!
+ "Check that workmux is installed and at least the minimum version. Exits on failure."
+ []
+ (when-not (u/can-run? "workmux")
+ (println (c/red "workmux is not installed."))
+ (println)
+ (println "Install workmux:")
+ (println " cargo install workmux")
+ (println " or see: https://github.com/raine/workmux")
+ (u/exit 1))
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true} "workmux" "--version")
+ version-str (when (zero? exit) (str/trim (str/join "" out)))
+ version (parse-workmux-version version-str)
+ min-str (str/join "." workmux-min-version)]
+ (cond
+ (nil? version)
+ (do
+ (println (c/red (str "Could not determine workmux version (got: " (pr-str version-str) ").")))
+ (println (c/red (str "Need workmux >= " min-str ". Run `workmux update` and retry.")))
+ (u/exit 1))
+
+ (version<? version workmux-min-version)
+ (do
+ (println (c/red (str "workmux " (str/join "." version) " is too old. Need >= " min-str ".")))
+ (println "Run `workmux update`, then retry.")
+ (u/exit 1)))))
+
+(defn check-nrepl!
+ "Check that clj-nrepl-eval is installed. Exits on failure."
+ []
+ (when-not (u/can-run? "clj-nrepl-eval")
+ (println (c/red "clj-nrepl-eval is not installed."))
+ (println " cargo install clj-nrepl-eval")
+ (u/exit 1)))
+
+(defn check-docker!
+ "Check that Docker is installed and running. Exits on failure."
+ []
+ (when-not (u/can-run? "docker")
+ (println (c/red "Docker is not installed."))
+ (u/exit 1))
+ (let [{:keys [exit]} (shell/sh* {:quiet? true} "docker" "info")]
+ (when-not (zero? exit)
+ (println (c/red "Docker daemon is not running. Please start Docker."))
+ (u/exit 1))))
+
+(defn check-tmux-status!
+ "Warn if not inside a tmux session."
+ []
+ (when (str/blank? (u/env "TMUX" (constantly nil)))
+ (println (c/yellow "Not inside a tmux session — one will be created automatically."))))
+
+(defn check-linear-api-key!
+ "Check LINEAR_API_KEY env var.
+ mode :required — exits on failure.
+ mode :optional — warns and returns false if missing, true if present."
+ [mode]
+ (let [key (u/env "LINEAR_API_KEY" (constantly nil))]
+ (if (str/blank? key)
+ (if (= mode :required)
+ (do
+ (println (c/red "LINEAR_API_KEY environment variable is not set."))
+ (println)
+ (println "To get a Linear API key:")
+ (println " 1. Go to https://linear.app/metabase/settings/account/security/api-keys/new")
+ (println " 2. Create a personal API key")
+ (println " 3. Export it: export LINEAR_API_KEY=lin_api_...")
+ (u/exit 1))
+ (do
+ (println (c/yellow "LINEAR_API_KEY not set — Linear context will be skipped."))
+ false))
+ true)))
+
+(def pr-env-vars
+ "Env vars required to talk to a PR preview environment."
+ ["PR_ENV_USERNAME" "PR_ENV_PASSWORD" "PR_ENV_REPL_HOST"])
+
+(defn check-pr-env-vars!
+ "Ensure PR_ENV_USERNAME, PR_ENV_PASSWORD, and PR_ENV_REPL_HOST are set
+ (in mise.local.toml, .env, .lein-env, or the system env). Exits on failure.
+ Returns a map of {var-name value} on success."
+ []
+ (let [resolved (into {} (map (fn [v] [v (bot-env/resolve-env v)]) pr-env-vars))
+ missing (->> resolved
+ (filter (fn [[_ v]] (str/blank? v)))
+ (mapv key))]
+ (when (seq missing)
+ (println (c/red "Missing required environment variables for PR preview environment:"))
+ (doseq [v missing]
+ (println (c/red (str " - " v))))
+ (println)
+ (println "Set these in your shell profile or in .mise.local.toml / .env at the repo root.")
+ (println "For example, in .mise.local.toml:")
+ (println " [env]")
+ (println " PR_ENV_USERNAME = \"[email protected]\"")
+ (println " PR_ENV_PASSWORD = \"...\"")
+ (println " PR_ENV_REPL_HOST = \"repl.coredev.metabase.com\"")
+ (u/exit 1))
+ resolved))
+
+(defn check-ee-token!
+ "Check MB_PREMIUM_EMBEDDING_TOKEN env var. Exits on failure."
+ []
+ (when (str/blank? (u/env "MB_PREMIUM_EMBEDDING_TOKEN" (constantly nil)))
+ (println (c/red "MB_PREMIUM_EMBEDDING_TOKEN environment variable is not set."))
+ (println)
+ (println "This token is required to run the Enterprise Edition.")
+ (println "Set it in your shell profile or export it before running.")
+ (u/exit 1)))
+
+(defn check-playwright!
+ "Check that Playwright MCP is available via npx. Exits on failure."
+ []
+ (when-not (u/can-run? "npx")
+ (println (c/red "npx is not available. Install Node.js."))
+ (u/exit 1))
+ (let [{:keys [exit]} (shell/sh* {:quiet? true} "npx" "-y" "@playwright/mcp" "--version")]
+ (when-not (zero? exit)
+ (println (c/red "@playwright/mcp is not available."))
+ (println)
+ (println "It should auto-install via npx. Check your npm/node setup.")
+ (u/exit 1))))
+
+(defn check-node-modules!
+ "Ensure node_modules exists. Auto-installs via bun if missing."
+ []
+ (when-not (.isDirectory (java.io.File. ^String (str u/project-root-directory "/node_modules")))
+ (println (c/yellow "node_modules not found — running bun install..."))
+ (shell/sh {:dir u/project-root-directory} "bun" "install")))
+
+(defn check-backend-health!
+ "Check that the Metabase backend is responding on the given port.
+ Retries every 10 seconds for up to 5 minutes to allow startup time.
+ Exits on failure after timeout."
+ [port]
+ (let [url (str "http://localhost:" port "/api/health")
+ timeout-ms (* 5 60 1000)
+ interval 10000
+ start (System/currentTimeMillis)]
+ (loop []
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true}
+ "curl" "-s" "-o" "/dev/null" "-w" "%{http_code}" url)
+ healthy? (and (zero? exit) (= (str/trim (str/join out)) "200"))
+ elapsed (- (System/currentTimeMillis) start)]
+ (cond
+ healthy?
+ (println (c/green (str "Backend healthy on port " port)))
+
+ (>= elapsed timeout-ms)
+ (do
+ (println (c/red (str "Backend did not become healthy on port " port " after 5 minutes.")))
+ (println "Check the backend logs for errors.")
+ (u/exit 1))
+
+ :else
+ (do
+ (println (c/yellow (str "Waiting for backend on port " port "... ("
+ (int (/ elapsed 1000)) "s elapsed)")))
+ (Thread/sleep interval)
+ (recur)))))))
+
+(defn preflight-health!
+ "CLI entry point: wait for backend health, auto-discovering the port."
+ [_parsed]
+ (let [port (or (bot-env/resolve-env "MB_JETTY_PORT") "3000")]
+ (check-backend-health! port)))
+
+(defn preflight!
+ "Run all prerequisite checks for the given bot. Exits on failure.
+ --bot <name> controls bot-specific policy (currently: whether
+ LINEAR_API_KEY is required). Unknown or missing bot name treats
+ Linear as optional."
+ [parsed]
+ (let [bot (:bot (:options parsed))
+ linear-mode (case bot
+ ("fixbot" "reprobot") :required
+ :optional)]
+ (check-mise!)
+ (check-workmux!)
+ (check-nrepl!)
+ (check-docker!)
+ (check-tmux-status!)
+ (check-linear-api-key! linear-mode)
+ (check-ee-token!)
+ (check-playwright!)
+ (check-node-modules!)
+ (println (c/green "All preflight checks passed."))))
+
diff --git a/mage/src/mage/bot/prompt.clj b/mage/src/mage/bot/prompt.clj
new file mode 100644
index 00000000000..00153ae850d
--- /dev/null
+++ b/mage/src/mage/bot/prompt.clj
@@ -0,0 +1,91 @@
+(ns mage.bot.prompt
+ "Fill template placeholders and write agent prompts.
+ Supports {{KEY}} for value replacement and {{FILE:path}} for file inclusion."
+ (:require
+ [clojure.string :as str]
+ [mage.color :as c]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn- parse-set-args
+ "Parse --set KEY=VALUE arguments into a map of {\"KEY\" \"VALUE\"}.
+ Warns on entries without a `=` so typos surface."
+ [set-args]
+ (into {}
+ (keep (fn [s]
+ (let [idx (str/index-of s "=")]
+ (if (and idx (pos? idx))
+ [(subs s 0 idx) (subs s (inc idx))]
+ (do (println (c/yellow "Warning: --set value missing '=' (ignored): " s))
+ nil)))))
+ set-args))
+
+(defn- parse-set-from-file-args
+ "Parse --set-from-file KEY=path arguments by reading the referenced file
+ and producing a map of {\"KEY\" \"<file contents>\"}. Missing files become
+ empty strings with a warning."
+ [args]
+ (into {}
+ (keep (fn [s]
+ (when-let [idx (str/index-of s "=")]
+ (when (pos? idx)
+ (let [k (subs s 0 idx)
+ path (subs s (inc idx))
+ f (java.io.File. ^String path)]
+ (if (.exists f)
+ [k (slurp f)]
+ (do
+ (println (c/yellow "Warning: --set-from-file path does not exist: " path))
+ [k ""])))))))
+ args))
+
+(defn- resolve-file-includes
+ "Replace all {{FILE:path}} placeholders with the contents of the referenced files.
+ Paths are relative to the project root. One pass only — included content is
+ not re-scanned for further {{FILE:...}} markers."
+ [content]
+ (str/replace content
+ #"\{\{FILE:([^}]+)\}\}"
+ (fn [[_ path]]
+ (let [full-path (str u/project-root-directory "/" (str/trim path))]
+ (if (.exists (java.io.File. ^String full-path))
+ (slurp full-path)
+ (do
+ (println (c/yellow "Warning: {{FILE:" path "}} not found at " full-path))
+ (str "<!-- FILE NOT FOUND: " path " -->")))))))
+
+(defn generate-prompt!
+ "Fill a template with placeholders and write to output.
+ Expects --template, --output, and one or more --set KEY=VALUE options.
+ Also supports --set-from-file KEY=path to read a value from a file
+ (useful for multi-line values you'd otherwise have to shell-escape).
+ Also resolves {{FILE:path}} includes."
+ [{:keys [options]}]
+ (let [template-path (:template options)
+ output-path (:output options)
+ set-args (:set options)
+ set-file-args (:set-from-file options)]
+ (when (str/blank? template-path)
+ (println (c/red "--template is required"))
+ (u/exit 1))
+ (when (str/blank? output-path)
+ (println (c/red "--output is required"))
+ (u/exit 1))
+ (when-not (.exists (java.io.File. ^String template-path))
+ (println (c/red "Template not found: " template-path))
+ (u/exit 1))
+ (let [replacements (merge (parse-set-from-file-args (or set-file-args []))
+ (parse-set-args (or set-args [])))
+ template (slurp template-path)
+ ;; First resolve {{FILE:...}} includes
+ with-files (resolve-file-includes template)
+ ;; Then replace {{KEY}} placeholders
+ content (reduce-kv (fn [s k v]
+ (str/replace s (str "{{" k "}}") v))
+ with-files
+ replacements)]
+ (.mkdirs (.getParentFile (java.io.File. ^String output-path)))
+ (spit output-path content)
+ (println (c/green "Wrote prompt: ") output-path)
+ output-path)))
diff --git a/mage/src/mage/bot/repl_eval.clj b/mage/src/mage/bot/repl_eval.clj
new file mode 100644
index 00000000000..144802e29b5
--- /dev/null
+++ b/mage/src/mage/bot/repl_eval.clj
@@ -0,0 +1,279 @@
+(ns mage.bot.repl-eval
+ "Unified REPL eval wrapper for bots.
+
+ Tries nREPL first (via clj-nrepl-eval) and falls back to a plain Clojure
+ socket REPL if nREPL isn't available. This means bots can use `-bot-repl-eval`
+ uniformly in both local-dev mode (where nREPL and socket REPL are both
+ available) and PR-env mode (where only a socket REPL is available on a
+ remote host)."
+ (:require
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.bot.pr-env :as pr-env]
+ [mage.color :as c]
+ [mage.shell :as shell]
+ [mage.util :as u])
+ (:import
+ (java.io BufferedReader InputStreamReader PrintWriter)
+ (java.net InetSocketAddress Socket SocketTimeoutException)))
+
+(set! *warn-on-reflection* true)
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Cache file — .bot/repl.env in the current worktree
+;;
+;; The first call to `-bot-repl-eval` discovers the best available backend
+;; and writes it here. Subsequent calls read from this file, skipping the
+;; discovery shell-out entirely. If an eval fails with a connection error
+;; (backend restarted, PR env went away, etc) we nuke the cache and retry
+;; with fresh discovery once.
+
+(defn- cache-file ^java.io.File []
+ (let [dir (java.io.File. ^String (System/getProperty "user.dir") ".bot")]
+ (.mkdirs dir)
+ (java.io.File. dir "repl.env")))
+
+(defn- read-cache
+ "Read .bot/repl.env if it exists. Returns {:type ... :host ... :port ...} or nil."
+ []
+ (let [f (cache-file)]
+ (when (.exists f)
+ (let [lines (str/split-lines (slurp f))
+ m (into {}
+ (keep (fn [line]
+ (let [line (str/trim line)]
+ (when (and (seq line)
+ (not (str/starts-with? line "#"))
+ (str/includes? line "="))
+ (let [[k v] (str/split line #"=" 2)]
+ [(str/trim k) (str/trim v)])))))
+ lines)]
+ (when (and (get m "TYPE") (get m "PORT"))
+ {:type (get m "TYPE")
+ :host (get m "HOST")
+ :port (get m "PORT")})))))
+
+(defn- write-cache!
+ "Cache a resolved {:type :host :port} to .bot/repl.env for subsequent calls."
+ [{:keys [type host port]}]
+ (spit (cache-file)
+ (str "TYPE=" type "\n"
+ "HOST=" host "\n"
+ "PORT=" port "\n")))
+
+(defn- clear-cache! []
+ (let [f (cache-file)]
+ (when (.exists f)
+ (.delete f))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Discovery
+
+(defn- discover-nrepl-port
+ "Return an nREPL port number string if one is discoverable, else nil."
+ []
+ (let [user-cwd (System/getProperty "user.dir")
+ {:keys [exit out]} (shell/sh* {:quiet? true :dir user-cwd}
+ "clj-nrepl-eval" "--discover-ports")
+ from-cmd (when (zero? exit)
+ (some (fn [line]
+ (when-let [m (re-find #"localhost:(\d+)" line)]
+ (second m)))
+ out))]
+ (or from-cmd
+ (let [f (java.io.File. ^String user-cwd ".nrepl-port")]
+ (when (.exists f)
+ (str/trim (slurp f)))))))
+
+(defn- discover-socket-repl
+ "Return {:host ... :port ...} for a socket REPL if one is discoverable,
+ else nil. Prefers PR-env mode (remote) over local mode."
+ []
+ (if (pr-env/pr-env-active?)
+ (let [env (pr-env/load-pr-env)]
+ {:host (get env "REPL_HOST")
+ :port (Integer/parseInt (get env "REPL_PORT"))})
+ (when-let [port (bot-env/resolve-env "MB_SOCKET_REPL_PORT")]
+ (try
+ {:host "localhost" :port (Integer/parseInt port)}
+ (catch NumberFormatException _ nil)))))
+
+(defn- resolve-backend
+ "Pick the best available REPL backend and return {:type :host :port} or nil.
+ Auto-detect: nREPL first, socket REPL fallback."
+ []
+ (or (when-let [port (discover-nrepl-port)]
+ {:type "nrepl" :host "localhost" :port port})
+ (when-let [cfg (discover-socket-repl)]
+ {:type "socket" :host (:host cfg) :port (str (:port cfg))})))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; nREPL backend (shells out to clj-nrepl-eval)
+
+(defn- eval-via-nrepl!
+ "Eval code against an nREPL server using the clj-nrepl-eval CLI.
+ Returns exit code; prints output directly."
+ [port code]
+ (let [user-cwd (System/getProperty "user.dir")
+ {:keys [exit out err]} (shell/sh* {:quiet? true :dir user-cwd}
+ "clj-nrepl-eval" "-p" (str port) code)]
+ (doseq [line out] (println line))
+ (when (seq err)
+ (binding [*out* *err*]
+ (doseq [line err] (println line))))
+ exit))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Socket REPL backend (direct TCP)
+
+(def ^:private socket-read-timeout-ms 10000)
+(def ^:private socket-connect-timeout-ms 5000)
+
+(defn- eval-via-socket-repl!
+ "Open a TCP socket to host:port, send one Clojure form, read everything
+ the REPL prints until the read timeout, and print it to stdout.
+ Returns 0 on success, non-zero on failure."
+ [host port code]
+ (try
+ (with-open [sock (Socket.)]
+ (.connect sock (InetSocketAddress. ^String host ^int (int port))
+ (int socket-connect-timeout-ms))
+ (.setSoTimeout sock (int socket-read-timeout-ms))
+ (let [writer (PrintWriter. (.getOutputStream sock) true)
+ reader (BufferedReader. (InputStreamReader. (.getInputStream sock)))]
+ ;; Send the form followed by a newline. Socket REPL evaluates each
+ ;; top-level form as soon as it parses.
+ (.println writer code)
+ (.flush writer)
+ ;; Read everything the server sends until the read timeout fires.
+ ;; Socket REPLs stay open indefinitely, so the timeout is how we know
+ ;; the server is done talking.
+ (let [sb (StringBuilder.)]
+ (try
+ (loop []
+ (let [line (.readLine reader)]
+ (when line
+ (.append sb line)
+ (.append sb "\n")
+ (recur))))
+ (catch SocketTimeoutException _))
+ (print (str sb))
+ (flush)
+ 0)))
+ (catch java.net.ConnectException e
+ (println (c/red (str "Could not connect to socket REPL at " host ":" port)))
+ (println (.getMessage e))
+ 1)
+ (catch Exception e
+ (println (c/red (str "Socket REPL error: " (.getMessage e))))
+ 1)))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; CLI entry point
+
+(defn- dispatch-eval!
+ "Run an eval against a resolved backend config. Returns {:exit int :connect-error? bool}."
+ [{:keys [type host port]} code]
+ (try
+ (let [exit (case type
+ "nrepl" (eval-via-nrepl! port code)
+ "socket" (eval-via-socket-repl! host (Integer/parseInt port) code))]
+ {:exit exit :connect-error? false})
+ (catch Exception e
+ {:exit 1 :connect-error? true :error (.getMessage e)})))
+
+(defn- looks-like-connect-error?
+ "nREPL's clj-nrepl-eval prints a Java exception trace on connection failure.
+ Socket eval returns a non-zero exit with a Connection/Unknown host error.
+ This is a best-effort check — when in doubt, retry once."
+ [exit output]
+ (or (not (zero? exit))
+ (and output
+ (or (str/includes? output "ConnectException")
+ (str/includes? output "UnknownHost")
+ (str/includes? output "Connection refused")))))
+
+(defn repl-eval!
+ "Evaluate a Clojure form against the best-available REPL backend.
+
+ Caches the resolved backend to .bot/repl.env so subsequent calls skip
+ discovery. If a cached backend produces a connection error, the cache
+ is cleared and discovery runs fresh one more time.
+
+ Options (from CLI):
+ positional arg: Clojure code to eval (alternatively via --code)
+ --code CODE Clojure code to eval
+ --port PORT Override discovery and use this port
+ --host HOST Override discovery and use this host (socket REPL only)
+ --type TYPE Force backend: 'nrepl' or 'socket'. Default: auto-detect.
+ --refresh Ignore the cache and re-run discovery.
+
+ Auto-detect order:
+ 1. nREPL (via clj-nrepl-eval) if discoverable
+ 2. Socket REPL (MB_SOCKET_REPL_PORT locally, REPL_HOST/REPL_PORT in PR-env mode)
+ 3. Error if neither is available"
+ [{:keys [arguments options]}]
+ (let [code (or (:code options) (first arguments))]
+ (when (str/blank? code)
+ (println (c/red "Usage: ./bin/mage -bot-repl-eval '<clojure-form>' [--port PORT] [--host HOST] [--type nrepl|socket] [--refresh]"))
+ (u/exit 1))
+ (let [forced-type (:type options)
+ forced-port (:port options)
+ forced-host (:host options)
+ refresh? (:refresh options)
+ ;; Option overrides bypass the cache entirely
+ override (when (or forced-type forced-port forced-host)
+ {:type (or forced-type "nrepl")
+ :host (or forced-host "localhost")
+ :port (or forced-port "")})]
+ (cond
+ ;; Explicit override — no cache involvement
+ override
+ (let [cfg (if (= (:type override) "socket")
+ (merge {:host "localhost"} override)
+ override)]
+ (when (str/blank? (:port cfg))
+ (println (c/red "When using --type or --host, --port is required (or rely on cache/auto-detect)."))
+ (u/exit 1))
+ (u/exit (:exit (dispatch-eval! cfg code))))
+
+ :else
+ (do
+ (when refresh? (clear-cache!))
+ (let [cached (read-cache)
+ cfg (or cached (resolve-backend))]
+ (cond
+ (nil? cfg)
+ (do
+ (println (c/red "No REPL available: neither nREPL nor socket REPL could be discovered."))
+ (println (c/yellow "Hints:"))
+ (println (c/yellow " - For local dev: start the backend with `clj -M:dev:dev-start`."))
+ (println (c/yellow " - For PR-env: check that .bot/pr-env.env exists and REPL_HOST/REPL_PORT are set."))
+ (u/exit 1))
+
+ :else
+ (let [{:keys [exit]} (dispatch-eval! cfg code)]
+ (cond
+ (zero? exit)
+ (do
+ ;; Only persist the cache when the eval actually worked
+ (when-not cached (write-cache! cfg))
+ (u/exit 0))
+
+ ;; Connection error on a cached backend — invalidate and retry once with fresh discovery
+ cached
+ (do
+ (binding [*out* *err*]
+ (println (c/yellow (str "Cached REPL backend failed (exit " exit "). Clearing cache and retrying discovery."))))
+ (clear-cache!)
+ (if-let [fresh (resolve-backend)]
+ (let [{:keys [exit]} (dispatch-eval! fresh code)]
+ (when (zero? exit) (write-cache! fresh))
+ (u/exit exit))
+ (do
+ (println (c/red "No REPL available after cache invalidation."))
+ (u/exit 1))))
+
+ ;; Non-cached first attempt failed — don't persist a bad cache
+ :else
+ (u/exit exit))))))))))
diff --git a/mage/src/mage/bot/server_info.clj b/mage/src/mage/bot/server_info.clj
new file mode 100644
index 00000000000..b9b8339ed09
--- /dev/null
+++ b/mage/src/mage/bot/server_info.clj
@@ -0,0 +1,162 @@
+(ns mage.bot.server-info
+ "Discover and print server configuration for bot agents.
+ Finds MB_CONFIG_FILE_PATH from env, mise.local.toml, or .lein-env,
+ then prints the config YAML along with port/connection info.
+ In PR-env mode (when .bot/pr-env.env exists), prints remote info instead."
+ (:require
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.bot.pr-env :as pr-env]
+ [mage.shell :as shell]
+ [mage.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn- print-git-branch []
+ (println "## Git Branch")
+ (println)
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true} "git" "branch" "--show-current")]
+ (if (zero? exit)
+ (println (str/trim (str/join "" out)))
+ (println "unknown")))
+ (println))
+
+(defn- print-pr-env-info! []
+ (let [env (pr-env/load-pr-env)
+ token (pr-env/session-token)]
+ (print-git-branch)
+
+ (println "## Remote PR Environment")
+ (println)
+ (println "MODE=pr-env")
+ (println (str "BASE_URL=" (get env "BASE_URL")))
+ (println (str "PR_NUM=" (get env "PR_NUM")))
+ (println (str "USERNAME=" (get env "USERNAME")))
+ (println "SESSION_FILE=.bot/pr-env-session.txt")
+ (println (str "SESSION_TOKEN_PRESENT=" (if token "yes" "no")))
+ (println)
+ (println "API calls via `./bin/mage -bot-api-call` transparently target BASE_URL")
+ (println "using the cached session token — no code changes needed.")
+ (println)
+
+ (println "## REPL Access")
+ (println)
+ (println "NREPL_PORT=NONE")
+ (println (str "SOCKET_REPL_HOST=" (get env "REPL_HOST")))
+ (println (str "SOCKET_REPL_PORT=" (get env "REPL_PORT")))
+ (println (str "SOCKET_REPL_USAGE=echo '(+ 1 2)' | nc -q 1 "
+ (get env "REPL_HOST") " " (get env "REPL_PORT")))
+ (println)
+ (println "Remote PR envs expose a socket REPL, not nREPL. `clj-nrepl-eval`")
+ (println "will NOT work here. Send ONE form per connection via `nc`. Wrap")
+ (println "multi-form work in `(do ...)`.")
+ (println)
+
+ (println "## Network")
+ (println)
+ (println "PR preview environments are only reachable via the Metabase Tailscale")
+ (println "network. If API calls, Playwright navigation, or `nc` hang or time out,")
+ (println "the most likely cause is a missing Tailscale connection.")
+ (println)))
+
+(defn- server-info-local!
+ "Local-dev server info output. Unchanged from the pre-PR-env behavior."
+ []
+ (let [resolved (bot-env/resolve-all)
+ config-path (get resolved "MB_CONFIG_FILE_PATH")]
+ (print-git-branch)
+
+ ;; MB_* environment variables section
+ (println "## Environment Variables")
+ (println)
+ (let [mb-vars (filter (fn [[k _]] (str/starts-with? k "MB_")) resolved)]
+ (if (seq mb-vars)
+ (doseq [[k v] (sort-by first mb-vars)]
+ (println (str k "=" v)))
+ (println "No MB_* variables found.")))
+ (println)
+
+ ;; Other useful variables
+ (println "## Other Variables")
+ (println)
+ (doseq [var-name ["LINEAR_API_KEY" "METASTORE_DEV_SERVER_URL"]]
+ (when-let [v (get resolved var-name)]
+ (let [display-v (if (= var-name "LINEAR_API_KEY")
+ (str (subs v 0 (min 12 (count v))) "...")
+ v)]
+ (println (str var-name "=" display-v)))))
+ (println)
+
+ ;; nREPL discovery — try clj-nrepl-eval first, fall back to reading
+ ;; .nrepl-port directly (which Metabase's dev REPL writes on startup).
+ (println "## nREPL Servers")
+ (println)
+ (let [{:keys [exit out]} (shell/sh* {:quiet? true} "clj-nrepl-eval" "--discover-ports")
+ port-from-cmd (when (zero? exit)
+ (some (fn [line]
+ (when-let [m (re-find #"localhost:(\d+)" line)]
+ (second m)))
+ out))
+ port-from-file (when-not port-from-cmd
+ (let [f (java.io.File. ^String (System/getProperty "user.dir") ".nrepl-port")]
+ (when (.exists f)
+ (str/trim (slurp f)))))]
+ (cond
+ port-from-cmd (println (str "NREPL_PORT=" port-from-cmd))
+ port-from-file (println (str "NREPL_PORT=" port-from-file))
+ :else (println "NREPL_PORT=NONE")))
+ (println)
+
+ ;; Source info
+ (println "## Sources")
+ (println)
+ (let [has-mise? (seq (bot-env/read-mise-local-toml))
+ has-lein? (seq (bot-env/read-lein-env))]
+ (cond
+ has-mise? (println "Primary: mise.local.toml")
+ has-lein? (println "Primary: .lein-env")
+ :else (println "Primary: system environment only"))
+ (when (.exists (java.io.File. ^String (str u/project-root-directory "/.env")))
+ (println "Also loaded: .env"))
+ (when has-lein?
+ (println "Also loaded: .lein-env")))
+ (println)
+
+ ;; Config file section
+ (println "## Instance Configuration")
+ (println)
+ (if config-path
+ (let [config-file (java.io.File. ^String config-path)]
+ (if (.exists config-file)
+ (do
+ (println (str "Config file: " config-path))
+ (println)
+ (println (slurp config-file)))
+ (do
+ (println (str "Config file path set but file does not exist: " config-path))
+ (println "The instance may not have pre-configured users. Check /api/setup to see if initial setup is needed."))))
+ ;; MB_CONFIG_FILE_PATH not set — look for config files in well-known locations
+ (let [candidates [(str u/project-root-directory "/metabase.config.yml")
+ (str u/project-root-directory "/local/config.yml")]
+ found (first (filter #(.exists (java.io.File. ^String %)) candidates))]
+ (if found
+ (do
+ (println (str "Config file (auto-discovered): " found))
+ (println)
+ (println (slurp found)))
+ (do
+ (println "No config file found.")
+ (println "MB_CONFIG_FILE_PATH is not set, and no config file exists at:")
+ (doseq [c candidates]
+ (println (str " " c)))
+ (println)
+ (println "You may need to check /api/setup or /api/session to determine the instance state.")))))))
+
+(defn server-info!
+ "Print server configuration for bot agents.
+ Selects between local-dev and remote PR-env output based on whether
+ .bot/pr-env.env exists in the current worktree."
+ [& _]
+ (if (pr-env/pr-env-active?)
+ (print-pr-env-info!)
+ (server-info-local!)))
diff --git a/mage/src/mage/bot/setup_worktree.clj b/mage/src/mage/bot/setup_worktree.clj
new file mode 100644
index 00000000000..24b5e55fab5
--- /dev/null
+++ b/mage/src/mage/bot/setup_worktree.clj
@@ -0,0 +1,185 @@
+(ns mage.bot.setup-worktree
+ (:require
+ [babashka.fs :as fs]
+ [babashka.pods :as pods]
+ [clojure.java.io :as io]
+ [clojure.string :as str]
+ [mage.color :as c]
+ [mage.shell :as shell]))
+
+(pods/load-pod 'org.babashka/postgresql "0.1.0")
+(require '[pod.babashka.postgresql :as pg])
+
+(set! *warn-on-reflection* true)
+
+(defn- worktree-name [worktree-root]
+ (last (str/split worktree-root #"/")))
+
+(defn- main-worktree-path
+ "Return the path of the main (original) git worktree."
+ []
+ (let [{:keys [out]} (shell/sh* {:quiet? true} "git" "worktree" "list" "--porcelain")]
+ (->> out
+ (take-while #(not (str/blank? %)))
+ (filter #(str/starts-with? % "worktree "))
+ first
+ (#(subs % (count "worktree "))))))
+
+(defn- copy-file!
+ "Copy a single file from main worktree to new worktree. Skips if source doesn't exist."
+ [main-path worktree-root relative-path]
+ (let [src (str main-path "/" relative-path)
+ dest (str worktree-root "/" relative-path)]
+ (if-not (fs/exists? src)
+ (println (c/yellow "Skipping " relative-path " (not found in main repo)"))
+ (do
+ (fs/create-dirs (str (fs/parent dest)))
+ (fs/copy src dest {:replace-existing true})
+ (println (c/green "Copied " relative-path))))))
+
+(defn- create-symlink!
+ "Create a symlink from main worktree to new worktree for a single path."
+ [main-path worktree-root relative-path]
+ (let [src (str main-path "/" relative-path)
+ dest (str worktree-root "/" relative-path)]
+ ;; Create source dir if it doesn't exist (e.g., jars/)
+ (when (and (not (fs/exists? src)) (not (str/includes? relative-path ".")))
+ (fs/create-dirs src))
+ (cond
+ (not (fs/exists? src))
+ (println (c/yellow "Skipping " relative-path " symlink: not found"))
+
+ (and (fs/exists? dest {:nofollow-links true}) (not (fs/sym-link? dest)))
+ (println (c/yellow "Skipping " relative-path " symlink: already exists and is not a symlink"))
+
+ :else
+ (do
+ (when (fs/sym-link? dest) (fs/delete dest))
+ (fs/create-sym-link dest src)
+ (println (c/green "Symlinked " relative-path))))))
+
+(defn- copy-tree-if-exists!
+ "Copy a directory tree from main to worktree. Tries APFS copy-on-write
+ (`cp -rc`) first; on non-APFS filesystems (including Linux) falls back
+ to a regular recursive copy. Replaces existing destination. Skips if
+ source doesn't exist."
+ [main-path worktree-root relative-path]
+ (let [src (str main-path "/" relative-path)
+ dest (str worktree-root "/" relative-path)]
+ (if-not (fs/exists? src)
+ (println (c/yellow "Skipping " relative-path " copy: not found"))
+ (do
+ (when (fs/exists? dest {:nofollow-links true})
+ (fs/delete-tree dest))
+ (let [{:keys [exit]} (shell/sh* {:quiet? true} "cp" "-rc" src dest)]
+ (if (zero? exit)
+ (println (c/green "Copied " relative-path " (copy-on-write)"))
+ (let [{:keys [exit err]} (shell/sh* {:quiet? true} "cp" "-r" src dest)]
+ (if (zero? exit)
+ (println (c/green "Copied " relative-path))
+ (do (println (c/red "Failed to copy " relative-path ":"))
+ (doseq [line err] (println (c/red " " line))))))))))))
+
+(defn- copy-files!
+ "Copy individual files from main worktree to new worktree."
+ [main-path worktree-root]
+ (doseq [path [".env" ".lein-env" ".mcp.json" ".claude/settings.local.json"]]
+ (copy-file! main-path worktree-root path)))
+
+(defn- copy-dirs!
+ "Copy directory trees (APFS copy-on-write) from main worktree to new worktree."
+ [main-path worktree-root]
+ (doseq [path [".cpcache" ".clj-kondo/.cache" ".shadow-cljs" "plugins" "local"]]
+ (copy-tree-if-exists! main-path worktree-root path)))
+
+(defn- create-symlinks!
+ "Create symlinks from main worktree to new worktree."
+ [main-path worktree-root]
+ (doseq [path ["bin/bb" "jars"]]
+ (create-symlink! main-path worktree-root path)))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; IntelliJ / IDE setup
+
+(defn- copy-idea-files!
+ "Copy .idea/ and *.iml files, renaming .iml to match the worktree name."
+ [main-path worktree-root]
+ (let [main-name (worktree-name main-path)
+ wt-name (worktree-name worktree-root)]
+ ;; Copy .idea directory
+ (copy-tree-if-exists! main-path worktree-root ".idea")
+ ;; Copy and rename .iml files
+ (doseq [iml (fs/glob main-path "*.iml")]
+ (let [old-name (str (fs/file-name iml))
+ new-name (str/replace old-name main-name wt-name)
+ dest (str worktree-root "/" new-name)]
+ (fs/copy iml dest {:replace-existing true})
+ (println (c/green "Copied " old-name " -> " new-name))))
+ ;; Update modules.xml to reference the renamed .iml file
+ (let [modules-xml (io/file worktree-root ".idea/modules.xml")]
+ (when (.exists modules-xml)
+ (let [content (slurp modules-xml)
+ updated (str/replace content (str main-name ".iml") (str wt-name ".iml"))]
+ (when (not= content updated)
+ (spit modules-xml updated)
+ (println (c/green "Updated modules.xml: " main-name ".iml -> " wt-name ".iml"))))))))
+
+(defn- update-workspace-paths!
+ "Replace absolute main-worktree paths with new worktree paths in workspace.xml."
+ [main-path worktree-root]
+ (let [workspace (io/file worktree-root ".idea/workspace.xml")]
+ (when (.exists workspace)
+ (let [content (slurp workspace)
+ updated (str/replace content main-path worktree-root)]
+ (when (not= content updated)
+ (spit workspace updated)
+ (println (c/green "Updated workspace.xml paths")))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Database and dev environment
+
+(defn- create-postgres-db!
+ "Create the worktree's database in the local PostgreSQL instance if it doesn't already exist."
+ [worktree-root]
+ (let [wt-name (worktree-name worktree-root)
+ db-name (str/replace wt-name #"[^a-zA-Z0-9_]" "_")
+ db-spec {:dbtype "postgresql" :host "localhost" :port 5432
+ :dbname "metabase" :user "metabase" :password "password"}]
+ (try
+ (pg/execute! db-spec [(str "CREATE DATABASE \"" db-name "\"")])
+ (println (c/green "Created postgres database: ") db-name)
+ (catch Exception e
+ (cond
+ (str/includes? (ex-message e) "already exists")
+ (println (c/green "Postgres database already exists: ") db-name)
+
+ :else
+ (do
+ (println (c/red "Failed to create postgres database '" db-name "': ") (ex-message e))
+ (println (c/yellow "Expected a local Postgres on localhost:5432 with user=metabase password=password."))
+ (println (c/yellow "Adjust your local Postgres or set up the metabase user/password to match."))
+ (throw e)))))))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Main entry point
+
+(defn setup-worktree!
+ "Run final configuration steps after a new worktree is created."
+ [{:keys [options]}]
+ (let [worktree-root (or (:worktree options)
+ (do (println (c/red "Usage: ./bin/mage -bot-setup-worktree --worktree <path-to-worktree>"))
+ (System/exit 1)))
+ main-path (main-worktree-path)]
+ (println (c/bold (c/green "Setting up worktree: ") (c/cyan (worktree-name worktree-root))))
+ (println)
+ (println (c/cyan "Main repo: ") main-path)
+ (println)
+ (create-symlinks! main-path worktree-root)
+ (copy-dirs! main-path worktree-root)
+ (copy-files! main-path worktree-root)
+ (copy-idea-files! main-path worktree-root)
+ (update-workspace-paths! main-path worktree-root)
+ (create-postgres-db! worktree-root)
+ (println)
+ (println (c/green "Done."))
+ (println (c/cyan "Run ./bin/mage -bot-dev-env to configure the dev environment."))))
diff --git a/mage/src/mage/bot/status.clj b/mage/src/mage/bot/status.clj
new file mode 100644
index 00000000000..e6bfbbb2e9f
--- /dev/null
+++ b/mage/src/mage/bot/status.clj
@@ -0,0 +1,178 @@
+(ns mage.bot.status
+ "Autobot status monitor — watches .bot/autobot/llm-status.txt and checks service health.
+
+ Supports two modes:
+ - **Local dev mode:** reads mise.local.toml for backend/frontend/DB ports and polls their health locally.
+ - **PR-env mode:** reads .bot/pr-env.env for the remote BASE_URL and polls that instead.
+ No local ports, no DB check."
+ (:require
+ [babashka.http-client :as http]
+ [babashka.json :as json]
+ [clojure.string :as str]
+ [mage.bot.env :as bot-env]
+ [mage.bot.pr-env :as pr-env]
+ [mage.color :as c]
+ [mage.shell :as shell])
+ (:import
+ (java.io File)
+ (java.net Socket)))
+
+(set! *warn-on-reflection* true)
+
+(defn- extract-port
+ "Extract port number from a string, trying env value directly or parsing from JDBC URL."
+ [^String s]
+ (when s
+ (or (try (Integer/parseInt s) (catch Exception _ nil))
+ (when-let [[_ port-str] (re-find #"(?:localhost|host\.docker\.internal):(\d+)" s)]
+ (Integer/parseInt port-str)))))
+
+(defn- extract-db-host
+ "Extract the DB host from a JDBC URL."
+ [^String s]
+ (when s
+ (when-let [[_ host] (re-find #"//([^:/]+)" s)]
+ host)))
+
+(defn- check-http
+ "Try an HTTP GET. Returns :ready, :unhealthy, or :waiting."
+ [^String url timeout-ms]
+ (try
+ (let [resp (http/get url {:timeout (int timeout-ms)
+ :throw false})
+ code (:status resp)]
+ (if (<= 200 code 399) :ready :unhealthy))
+ (catch java.net.ConnectException _ :waiting)
+ (catch Exception _ :unhealthy)))
+
+(defn- check-tcp
+ "Try a TCP connection. Returns :ready or :waiting."
+ [^String host port timeout-ms]
+ (try
+ (let [sock (Socket.)]
+ (.connect sock (java.net.InetSocketAddress. host ^int (int port)) (int timeout-ms))
+ (.close sock)
+ :ready)
+ (catch Exception _ :waiting)))
+
+(defn- load-ports
+ "Read mise.local.toml and extract ports. Returns a map or nil if file not ready."
+ []
+ (when-let [env (bot-env/read-mise-local-toml)]
+ (let [jetty-port (extract-port (get env "MB_JETTY_PORT"))
+ frontend-port (extract-port (get env "MB_FRONTEND_DEV_PORT"))
+ db-uri (get env "MB_DB_CONNECTION_URI")
+ db-type-str (get env "MB_DB_TYPE")
+ db-type (when db-type-str (keyword db-type-str))
+ db-port (extract-port db-uri)
+ db-host (extract-db-host db-uri)]
+ (when jetty-port
+ {:jetty-port jetty-port
+ :frontend-port frontend-port
+ :db-type db-type
+ :db-port db-port
+ :db-host (or db-host "localhost")}))))
+
+(defn- check-pr
+ "Check if there's an open PR for the current branch. Returns {:url ... :number ...} or nil."
+ []
+ (try
+ (let [result (shell/sh* {:quiet? true} "gh" "pr" "view" "--json" "url,number,state")]
+ (when (zero? (:exit result))
+ (let [data (json/read-str (str/join "\n" (:out result)) {:key-fn keyword})]
+ (when (= "OPEN" (:state data))
+ {:url (:url data) :number (:number data)}))))
+ (catch Exception _ nil)))
+
+(defn- render-display
+ "Render the full status pane display.
+
+ mode is either :local (port-based) or :pr-env (remote URL).
+ In :pr-env mode, `ports` is nil and the first line is derived from pr-env-cfg."
+ [mode ports pr-env-cfg be-status db-status llm-status pr-info]
+ (let [sb (StringBuilder.)]
+ (case mode
+ :local
+ (when ports
+ (let [be-up? (= be-status :ready)
+ mb-color (if be-up? c/green c/red)
+ mb-text (str (if be-up? "http" "error") "://localhost:" (:jetty-port ports))
+ db-name (when (:db-type ports)
+ (str/upper-case (name (:db-type ports))))
+ db-color (if (= db-status :ready) c/green c/red)
+ db-text (when (and db-name (:db-port ports))
+ (str db-name ": " (:db-port ports)))]
+ (.append sb (mb-color mb-text))
+ (when db-text
+ (.append sb " | ")
+ (.append sb (db-color db-text)))
+ (when pr-info
+ (.append sb (str " | " (c/green (str "PR #" (:number pr-info))))))
+ (.append sb "\n")))
+
+ :pr-env
+ (let [be-up? (= be-status :ready)
+ mb-color (if be-up? c/green c/red)
+ base-url (get pr-env-cfg "BASE_URL")
+ pr-num (get pr-env-cfg "PR_NUM")
+ mb-text (if be-up? base-url (str "error: " base-url))]
+ (.append sb (mb-color mb-text))
+ (when pr-num
+ (.append sb (str " | " (c/green (str "PR #" pr-num)))))
+ (.append sb (str " | " (c/yellow "pr-env mode")))
+ (.append sb "\n")))
+
+ ;; Blank line + LLM status
+ (when (seq llm-status)
+ (.append sb "\n")
+ (.append sb llm-status)
+ (.append sb "\n"))
+ (.toString sb)))
+
+(defn run!
+ "Watch llm-status.txt and periodically check service health.
+ Auto-detects PR-env mode via .bot/pr-env.env."
+ [{:keys [arguments]}]
+ (let [file-path (or (first arguments) ".bot/autobot/llm-status.txt")
+ f (File. ^String file-path)
+ pr-env-cfg (when (pr-env/pr-env-active?) (pr-env/load-pr-env))
+ mode (if pr-env-cfg :pr-env :local)
+ ;; Seed last-output with a sentinel so the first tick always prints
+ ;; (even if render-display returns an empty string, the sentinel is
+ ;; different, so we print the initial state immediately).
+ startup-line (case mode
+ :pr-env (str "Starting status monitor for PR env " (get pr-env-cfg "BASE_URL") "...\n")
+ :local "Starting status monitor (local dev mode, waiting for mise.local.toml)...\n")]
+ (println startup-line)
+ (flush)
+ (loop [last-output startup-line
+ ports nil
+ pr-info nil
+ last-be-status :unhealthy
+ last-db-status :unhealthy
+ tick 0]
+ (let [check? (zero? (mod tick 5))
+ pr-check? (and (not pr-info) (zero? (mod tick 30)))
+ ports (or ports (when (and check? (= mode :local)) (load-ports)))
+ pr-info (or pr-info (when pr-check? (check-pr)))
+ be-status (cond
+ (and check? (= mode :local) ports)
+ (check-http (str "http://localhost:" (:jetty-port ports) "/api/health") 2000)
+
+ (and check? (= mode :pr-env) pr-env-cfg)
+ (check-http (str (get pr-env-cfg "BASE_URL") "/api/health") 5000)
+
+ :else
+ last-be-status)
+ db-status (if (and check? (= mode :local) ports (:db-port ports))
+ (check-tcp (:db-host ports) (:db-port ports) 2000)
+ last-db-status)
+ llm-status (when (.exists f)
+ (str/trim (slurp f)))
+ output (render-display mode ports pr-env-cfg be-status db-status llm-status pr-info)]
+ (when (not= output last-output)
+ (println "=========================================\n")
+ (print output)
+ (flush))
+ (Thread/sleep 1000)
+ (recur output ports pr-info be-status db-status (inc tick))))))
diff --git a/mage/src/mage/shell.clj b/mage/src/mage/shell.clj
index 217096e9dfa..ab6926f608e 100644
--- a/mage/src/mage/shell.clj
+++ b/mage/src/mage/shell.clj
@@ -64,6 +64,9 @@
^"[Ljava.lang.String;" cmd-array
^"[Ljava.lang.String;" env-array
^File (when dir (File. ^String dir)))]
+ ;; Close child stdin so subprocesses that read from it see EOF immediately
+ ;; instead of blocking forever on the JVM-owned pipe.
+ (.close (.getOutputStream proc))
(with-open [out-reader (BufferedReader. (InputStreamReader. (.getInputStream proc)))
err-reader (BufferedReader. (InputStreamReader. (.getErrorStream proc)))]
(let [exit-code (future (.waitFor proc))
diff --git a/mage/test/mage/bot/autobot_test.clj b/mage/test/mage/bot/autobot_test.clj
new file mode 100644
index 00000000000..dc1f951cb19
--- /dev/null
+++ b/mage/test/mage/bot/autobot_test.clj
@@ -0,0 +1,68 @@
+(ns mage.bot.autobot-test
+ (:require
+ [babashka.fs :as fs]
+ [clojure.test :refer [deftest is testing]]
+ [mage.bot.autobot :as autobot]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private parse-wt-name #'autobot/parse-worktree-name)
+(def ^:private launch-config-path #'autobot/launch-config-path)
+(def ^:private with-workmux-config! #'autobot/with-workmux-config!)
+
+(deftest branch-to-session-name-test
+ (testing "simple branch name"
+ (is (= "stream-fingerprinting" (autobot/branch-to-session-name "stream-fingerprinting"))))
+ (testing "replaces slashes with dashes"
+ (is (= "feature-my-branch" (autobot/branch-to-session-name "feature/my-branch"))))
+ (testing "lowercases"
+ (is (= "mb-12345-fix" (autobot/branch-to-session-name "MB-12345-Fix"))))
+ (testing "replaces special chars with hyphens"
+ (is (= "foo-bar-baz" (autobot/branch-to-session-name "foo_bar.baz"))))
+ (testing "deduplicates hyphens"
+ (is (= "a-b" (autobot/branch-to-session-name "a--b"))))
+ (testing "strips leading/trailing hyphens"
+ (is (= "abc" (autobot/branch-to-session-name "-abc-"))))
+ (testing "truncates to 40 chars"
+ (let [long-branch (apply str (repeat 50 "a"))
+ result (autobot/branch-to-session-name long-branch)]
+ (is (<= (count result) 40)))))
+
+(deftest parse-worktree-name-test
+ (testing "extracts name from __worktrees/ path"
+ (is (= "fixbot-mb-123" (parse-wt-name "fixbot-mb-123 /path/__worktrees/fixbot-mb-123"))))
+ (testing "returns nil for (here) marker"
+ (is (nil? (parse-wt-name "main /path/to/repo (here)"))))
+ (testing "extracts last component for non-worktree paths"
+ (is (= "some-dir" (parse-wt-name "some-dir /path/to/some-dir")))))
+
+(deftest launch-config-path-test
+ (testing "config goes under <root>/.bot/launch/<session>.yaml"
+ (is (= "/some/root/.bot/launch/my-session.yaml"
+ (launch-config-path "/some/root" "my-session")))))
+
+(deftest with-workmux-config!-writes-and-cleans-up
+ (let [dir (str (fs/create-temp-dir))
+ cfg-path (str dir "/.bot/launch/test.yaml")
+ cfg-content "agent: 'claude'\n"
+ observed (atom nil)]
+ (try
+ (testing "config file exists during invocation, gone afterward"
+ (with-workmux-config! cfg-path cfg-content
+ (fn []
+ (reset! observed (slurp cfg-path))))
+ (is (= cfg-content @observed))
+ (is (not (.exists (java.io.File. cfg-path)))))
+
+ (testing "config file is cleaned up even when f throws"
+ (is (thrown? RuntimeException
+ (with-workmux-config! cfg-path cfg-content
+ (fn [] (throw (RuntimeException. "boom"))))))
+ (is (not (.exists (java.io.File. cfg-path)))))
+
+ (testing "parent directories are created on demand"
+ (let [nested (str dir "/.bot/launch/deeper/dir/x.yaml")]
+ (with-workmux-config! nested cfg-content (fn []))
+ (is (not (.exists (java.io.File. nested))))))
+ (finally
+ (fs/delete-tree dir)))))
diff --git a/mage/test/mage/bot/dev_env_core_test.clj b/mage/test/mage/bot/dev_env_core_test.clj
new file mode 100644
index 00000000000..6a217a45877
--- /dev/null
+++ b/mage/test/mage/bot/dev_env_core_test.clj
@@ -0,0 +1,33 @@
+(ns mage.bot.dev-env-core-test
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [mage.bot.dev-env :as dev-env]))
+
+(set! *warn-on-reflection* true)
+
+(deftest worktree-name-test
+ (is (= "my-worktree" (dev-env/worktree-name "/home/user/src/my-worktree")))
+ (is (= "metabase" (dev-env/worktree-name "/Users/nvoxland/src/metabase"))))
+
+(deftest db-name-test
+ (is (= "my_worktree" (dev-env/db-name "/path/to/my-worktree")))
+ (is (= "my_wt_2" (dev-env/db-name "/path/to/my-wt.2")))
+ (is (= "simple" (dev-env/db-name "/path/to/simple"))))
+
+(deftest compute-slot-test
+ (testing "deterministic — same input always gives same output"
+ (is (= (dev-env/compute-slot "/path/to/wt" nil)
+ (dev-env/compute-slot "/path/to/wt" nil))))
+ (testing "range 0-99"
+ (let [slot (dev-env/compute-slot "/path/to/wt" nil)]
+ (is (<= 0 slot 99))))
+ (testing "override bypasses hash"
+ (is (= 42 (dev-env/compute-slot "/path/to/wt" 42)))))
+
+(deftest port-for-test
+ (is (= 3005 (dev-env/port-for :jetty 5)))
+ (is (= 8080 (dev-env/port-for :frontend-dev 0)))
+ (is (= 50615 (dev-env/port-for :nrepl 10))))
+
+(deftest container-prefix-test
+ (is (= "mb-my-wt-" (dev-env/container-prefix "/path/to/my-wt"))))
diff --git a/mage/test/mage/bot/env_test.clj b/mage/test/mage/bot/env_test.clj
new file mode 100644
index 00000000000..82c4be82b10
--- /dev/null
+++ b/mage/test/mage/bot/env_test.clj
@@ -0,0 +1,77 @@
+(ns mage.bot.env-test
+ (:require
+ [babashka.fs :as fs]
+ [clojure.test :refer [deftest is testing]]
+ [mage.bot.env :as bot-env]))
+
+(set! *warn-on-reflection* true)
+
+(defn- with-temp-dir
+ "Create a temp directory, call f with its path, then clean up."
+ [f]
+ (let [dir (str (fs/create-temp-dir))]
+ (try (f dir)
+ (finally (fs/delete-tree dir)))))
+
+(deftest read-mise-local-toml-test
+ (with-temp-dir
+ (fn [dir]
+ (spit (str dir "/mise.local.toml")
+ (str "# Auto-generated\n"
+ "[env]\n"
+ "MB_JETTY_PORT = \"3042\"\n"
+ "NREPL_PORT = \"50647\"\n"
+ "# A comment\n"
+ "\n"))
+ (let [result (bot-env/read-mise-local-toml dir)]
+ (is (= "3042" (get result "MB_JETTY_PORT")))
+ (is (= "50647" (get result "NREPL_PORT")))))))
+
+(deftest read-mise-local-toml-missing-file
+ (with-temp-dir
+ (fn [dir]
+ (is (nil? (bot-env/read-mise-local-toml dir))))))
+
+(deftest read-dot-env-test
+ (with-temp-dir
+ (fn [dir]
+ (spit (str dir "/.env")
+ (str "# Comment\n"
+ "SIMPLE=value\n"
+ "export EXPORTED=val2\n"
+ "QUOTED=\"with spaces\"\n"
+ "SINGLE='single quoted'\n"
+ "\n"))
+ (let [result (bot-env/read-dot-env dir)]
+ (is (= "value" (get result "SIMPLE")))
+ (is (= "val2" (get result "EXPORTED")))
+ (is (= "with spaces" (get result "QUOTED")))
+ (is (= "single quoted" (get result "SINGLE")))))))
+
+(deftest read-lein-env-test
+ (with-temp-dir
+ (fn [dir]
+ (spit (str dir "/.lein-env")
+ (pr-str {:some-key "val1"
+ :another-thing "val2"}))
+ (let [result (bot-env/read-lein-env dir)]
+ (is (= "val1" (get result "SOME_KEY")))
+ (is (= "val2" (get result "ANOTHER_THING")))))))
+
+(deftest resolve-env-priority-test
+ (testing "mise.local.toml wins over .env"
+ (with-temp-dir
+ (fn [dir]
+ (spit (str dir "/mise.local.toml") "[env]\nMB_JETTY_PORT = \"3042\"\n")
+ (spit (str dir "/.env") "MB_JETTY_PORT=9999\n")
+ (is (= "3042" (bot-env/resolve-env "MB_JETTY_PORT" dir))))))
+ (testing ".env wins over .lein-env"
+ (with-temp-dir
+ (fn [dir]
+ (spit (str dir "/.env") "MY_VAR=from-env\n")
+ (spit (str dir "/.lein-env") (pr-str {:my-var "from-lein"}))
+ (is (= "from-env" (bot-env/resolve-env "MY_VAR" dir))))))
+ (testing "returns nil when not found anywhere"
+ (with-temp-dir
+ (fn [dir]
+ (is (nil? (bot-env/resolve-env "NONEXISTENT_VAR_12345" dir)))))))
diff --git a/mage/test/mage/bot/pr_env_test.clj b/mage/test/mage/bot/pr_env_test.clj
new file mode 100644
index 00000000000..87ad659b947
--- /dev/null
+++ b/mage/test/mage/bot/pr_env_test.clj
@@ -0,0 +1,72 @@
+(ns mage.bot.pr-env-test
+ (:require
+ [babashka.fs :as fs]
+ [clojure.test :refer [deftest is testing]]
+ [mage.bot.pr-env :as pr-env]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private write-env-file! #'pr-env/write-env-file!)
+(def ^:private read-env-file #'pr-env/read-env-file)
+
+(defn- with-temp-cwd
+ "Re-bind user.dir so .bot/ files land in a temp dir, then clean up."
+ [f]
+ (let [orig (System/getProperty "user.dir")
+ dir (str (fs/create-temp-dir))]
+ (try
+ (System/setProperty "user.dir" dir)
+ (f dir)
+ (finally
+ (System/setProperty "user.dir" orig)
+ (fs/delete-tree dir)))))
+
+(deftest write-and-read-env-file-roundtrip
+ (with-temp-cwd
+ (fn [_]
+ (write-env-file! {:base-url "https://pr1234.coredev.metabase.com"
+ :pr-num "1234"
+ :repl-host "10.0.0.1"
+ :username "[email protected]"
+ :password "p@ss w/ space"})
+ (let [m (read-env-file)]
+ (is (= "https://pr1234.coredev.metabase.com" (get m "BASE_URL")))
+ (is (= "1234" (get m "PR_NUM")))
+ (is (= "10.0.0.1" (get m "REPL_HOST")))
+ (is (= "1234" (get m "REPL_PORT")))
+ (is (= "[email protected]" (get m "USERNAME")))
+ (is (= "p@ss w/ space" (get m "PASSWORD")))))))
+
+(deftest pr-env-active?-test
+ (testing "false when .bot/pr-env.env is absent"
+ (with-temp-cwd
+ (fn [_] (is (false? (pr-env/pr-env-active?))))))
+ (testing "true after write"
+ (with-temp-cwd
+ (fn [_]
+ (write-env-file! {:base-url "https://x" :pr-num "1"
+ :repl-host "h" :username "u" :password "p"})
+ (is (true? (pr-env/pr-env-active?)))))))
+
+(deftest setup!-rejects-missing-args
+ (testing "missing --url → exits non-zero"
+ (let [ex (try
+ (pr-env/setup! {:options {:url nil :pr "123"}})
+ nil
+ (catch clojure.lang.ExceptionInfo e e))]
+ (is (some? ex))
+ (is (= 1 (get (ex-data ex) :babashka/exit)))))
+ (testing "missing --pr → exits non-zero"
+ (let [ex (try
+ (pr-env/setup! {:options {:url "https://x" :pr ""}})
+ nil
+ (catch clojure.lang.ExceptionInfo e e))]
+ (is (some? ex))
+ (is (= 1 (get (ex-data ex) :babashka/exit)))))
+ (testing "blank --url and --pr → exits non-zero"
+ (let [ex (try
+ (pr-env/setup! {:options {:url "" :pr ""}})
+ nil
+ (catch clojure.lang.ExceptionInfo e e))]
+ (is (some? ex))
+ (is (= 1 (get (ex-data ex) :babashka/exit))))))
diff --git a/mage/test/mage/bot/prompt_test.clj b/mage/test/mage/bot/prompt_test.clj
new file mode 100644
index 00000000000..4529469c553
--- /dev/null
+++ b/mage/test/mage/bot/prompt_test.clj
@@ -0,0 +1,20 @@
+(ns mage.bot.prompt-test
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [mage.bot.prompt]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private parse-set-args #'mage.bot.prompt/parse-set-args)
+
+(deftest parse-set-args-test
+ (testing "basic key=value"
+ (is (= {"KEY" "value"} (parse-set-args ["KEY=value"]))))
+ (testing "multiple args"
+ (is (= {"A" "1" "B" "2"} (parse-set-args ["A=1" "B=2"]))))
+ (testing "value containing ="
+ (is (= {"FOO" "bar=baz"} (parse-set-args ["FOO=bar=baz"]))))
+ (testing "empty list"
+ (is (= {} (parse-set-args []))))
+ (testing "nil list"
+ (is (= {} (parse-set-args nil)))))
diff --git a/mage/test/mage/bot/repl_eval_test.clj b/mage/test/mage/bot/repl_eval_test.clj
new file mode 100644
index 00000000000..0e2cc69e1e5
--- /dev/null
+++ b/mage/test/mage/bot/repl_eval_test.clj
@@ -0,0 +1,65 @@
+(ns mage.bot.repl-eval-test
+ (:require
+ [babashka.fs :as fs]
+ [clojure.test :refer [deftest is testing]]
+ [mage.bot.repl-eval :as repl-eval]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private cache-file #'repl-eval/cache-file)
+(def ^:private read-cache #'repl-eval/read-cache)
+(def ^:private write-cache! #'repl-eval/write-cache!)
+(def ^:private clear-cache! #'repl-eval/clear-cache!)
+
+(defn- with-temp-cwd [f]
+ (let [orig (System/getProperty "user.dir")
+ dir (str (fs/create-temp-dir))]
+ (try
+ (System/setProperty "user.dir" dir)
+ (f dir)
+ (finally
+ (System/setProperty "user.dir" orig)
+ (fs/delete-tree dir)))))
+
+(deftest write-then-read-cache-test
+ (with-temp-cwd
+ (fn [_]
+ (write-cache! {:type "nrepl" :host "localhost" :port "50605"})
+ (is (= {:type "nrepl" :host "localhost" :port "50605"}
+ (read-cache))))))
+
+(deftest read-cache-missing-file-returns-nil
+ (with-temp-cwd
+ (fn [_] (is (nil? (read-cache))))))
+
+(deftest read-cache-missing-required-keys-returns-nil
+ (testing "incomplete cache (no PORT) is treated as no cache"
+ (with-temp-cwd
+ (fn [_]
+ (spit (cache-file) "TYPE=nrepl\nHOST=localhost\n")
+ (is (nil? (read-cache)))))))
+
+(deftest read-cache-skips-comments-and-blanks
+ (with-temp-cwd
+ (fn [_]
+ (spit (cache-file)
+ (str "# header comment\n"
+ "\n"
+ "TYPE=socket\n"
+ "HOST=10.0.0.1\n"
+ "PORT=4242\n"))
+ (is (= {:type "socket" :host "10.0.0.1" :port "4242"}
+ (read-cache))))))
+
+(deftest clear-cache!-removes-file
+ (with-temp-cwd
+ (fn [_]
+ (write-cache! {:type "nrepl" :host "localhost" :port "50605"})
+ (is (.exists (cache-file)))
+ (clear-cache!)
+ (is (not (.exists (cache-file))))
+ (is (nil? (read-cache)))))
+ (testing "clear-cache! is a no-op when no file exists"
+ (with-temp-cwd
+ (fn [_]
+ (is (nil? (clear-cache!)))))))
diff --git a/mage/test/mage/core_test.clj b/mage/test/mage/core_test.clj
index 5e9b4b4cf91..912d6a04223 100644
--- a/mage/test/mage/core_test.clj
+++ b/mage/test/mage/core_test.clj
@@ -6,6 +6,10 @@
[clojure.string :as str]
[clojure.test :refer [deftest is testing]]
[mage.alias-test]
+ [mage.bot.autobot-test]
+ [mage.bot.dev-env-core-test]
+ [mage.bot.env-test]
+ [mage.bot.prompt-test]
[mage.doctor-test]
[mage.fix-unused-requires-test]
[mage.merge-yaml-migrations-test :as merge-yaml-migrations-test]
diff --git a/rspack.main.config.js b/rspack.main.config.js
index c2635fba2af..cbb91b1e852 100644
--- a/rspack.main.config.js
+++ b/rspack.main.config.js
@@ -387,11 +387,16 @@ if (isDevMode) {
// helps with source maps
config.output.devtoolModuleFilenameTemplate = "[absolute-resource-path]";
+ if (!process.env.DISABLE_BUILD_NOTIFICATIONS) {
+ config.plugins.push(
+ new WebpackNotifierPlugin({
+ excludeWarnings: true,
+ skipFirstNotification: true,
+ }),
+ );
+ }
+
config.plugins.push(
- new WebpackNotifierPlugin({
- excludeWarnings: true,
- skipFirstNotification: true,
- }),
new CssVarsDeclarationPlugin({
frontendSrcPath: __dirname + "/frontend/src",
rootPath: __dirname,