worktree-stack
GitHub用于在当前 git worktree 中快速启动隔离的 Playwright 端到端测试环境,包含数据库、API 和前端服务,并提供连接信息以驱动自动化测试。
触发场景
安装
npx skills add LanternOps/breeze --skill worktree-stack -g -y
SKILL.md
Frontmatter
{
"name": "worktree-stack",
"description": "Use when an agent needs a running, seeded, Playwright-ready Breeze stack for the current git worktree. Brings up pg+redis+api+web+portal+caddy running the worktree's own code and emits a JSON descriptor."
}
Worktree Test Stack
Loop for testing the current worktree end to end:
- Bring up the stack (per-worktree isolated):
pnpm wt-stack up- Add
--sharedfor the singleton stack (ports are always ephemeral, read from.breeze-stack.json). - Add
--rebuildafter Dockerfile or dependency changes.
- Add
- Read
.breeze-stack.jsonat the worktree root forbaseUrl,apiUrl,portalUrl, and admin creds (admin@breeze.local/BreezeAdmin123!). - Drive Playwright:
pnpm wt-stack test -- tests/<spec>.spec.ts, or point the Playwright MCP browser atbaseUrl. - Tear down:
pnpm wt-stack down(removes volumes by default). Run it from the same worktree that ranup; the branch does not matter (#9864).uprecords the compose project in.breeze-stack.jsonanddown,upandtestreuse it; without a descriptor the name is derived from the worktree path (breeze-wt-<dir>-<hash>).downexits non-zero when it finds no matching project instead of silently doing nothing; passBREEZE_WT_PROJECT=<name>to target a specific project. A deleted worktree still orphans its stack (see "Tear down when done" below).
Notes:
- Requires Node v22.20.0 on PATH and a populated root
.env(image refs). .env.stackpinsRESEND_API_KEY,MAILGUN_API_KEYandSMTP_HOSTto empty so a QA stack never sends real email even though the root.envcarries live keys; setBREEZE_WT_STACK_LIVE_MAIL=1to keep the root values.- Caddy serves plain HTTP in dev;
baseUrlishttp://localhost:<port>. - Caddy's host port is random by default and changes if caddy is restarted (
docker restartre-allocates it), stranding anything that readbaseUrl. ExportBREEZE_WT_CADDY_PORT=<free port>beforepnpm wt-stack upto pin it; the descriptor then hascaddyPortPinned: true. Required for any storm scenario that restarts caddy (socket-drop,storm-suite) —storm.shrefuses to run it otherwise (#8718).uprefuses to start when another compose project already publishes the pinned port (#9864). - OrbStack is recommended for speed but not required — the CLI uses only the
standard
docker composeinterface. pnpm wt-stack lslists running stacks;pnpm wt-stack infoprints the descriptor.
Tear down when done (mandatory — nothing reaps a local stack for you)
Every stack you bring up stays up until something tears it down: OrbStack / Docker never expire them, and each agent session tends to leave its own behind. On 2026-09-01 the dev machine had five Breeze compose projects and two bare containers running from earlier sessions. Tear down what you brought up before you end, and say in your final summary what you left running and why.
pnpm wt-stack ls is not the whole picture. It lists only breeze and
breeze-wt-* projects. pnpm test-stack ls lists only breeze-test-*. Neither
shows a docker-compose.test.yml brought up without -p (project = directory
name, e.g. worktree-quiet-field-f8d5) or an ad-hoc docker run Postgres from a
plan task. Use the engine-wide listing below.
# 1. What is still up, across ALL worktrees and sessions?
docker compose ls -a --format json \
| jq -r '.[] | select(.ConfigFiles|test("breeze")) | "\(.Name)\t\(.Status)"'
docker ps -a --format '{{.Names}}\t{{.Status}}\t{{.Label "com.docker.compose.project"}}' \
| grep -i breeze # blank 3rd column = bare `docker run` container, no compose project
# 2. Tear down what YOU brought up, from the worktree that created it
pnpm wt-stack down # this worktree's dev stack (drops volumes)
pnpm test-stack down # this worktree's integration pg+redis
pnpm --filter @breeze/api test:docker:down # the shared :5433 test stack (docker-compose.test.yml, no -p)
docker compose -f docker-compose.yml -f docker-compose.override.yml.dev down -v --remove-orphans
# a compose-mode stack — pass the same -f files you used for `up`
# 3. Anything left over (worktree deleted, branch renamed, another session's stack)
docker compose -p <name> down -v --remove-orphans # <name> = first column of step 1; no -f needed
docker rm -f <container> # bare containers, e.g. breeze-<issue>-drift
# 4. Verify — both must print nothing
docker compose ls -a --format json | jq -r '.[] | select(.ConfigFiles|test("breeze")) | .Name'
docker ps -a --format '{{.Names}}' | grep -i breeze
Everything-Breeze reset. Only when you own every stack on the machine — this kills other sessions' stacks too, so never run it from a parallel agent:
docker compose ls -a --format json | jq -r '.[] | select(.ConfigFiles|test("breeze")) | .Name' \
| xargs -r -I{} docker compose -p {} down -v --remove-orphans
docker ps -aq --filter name=breeze | xargs -r docker rm -f
docker network ls --format '{{.Name}}' | grep -i breeze | xargs -r docker network rm # stray *-net networks
--keep-volumes on wt-stack down keeps the Postgres data for a re-up; the
default drops it, which is what you want at the end of a task.
版本历史
-
0b71144
当前 2026-11-03 11:01
修复了 compose 项目命名逻辑,从基于分支改为基于 worktree 路径,解决分支切换导致的环境孤立问题;down 命令现在会在项目不存在时报错而非静默成功。
-
8f240dd
2026-10-19 17:56
新增 Caddy 端口固定功能以解决重启后端口变更导致的服务中断问题,增强 storm.sh 对未固定端口场景的检查与诊断能力。
-
1c3a08e
2026-09-22 22:18
新增强制性的环境清理指南与排查命令;集成备份恢复审计、安全扫描门禁及灾难恢复文档更新。
- 10bb1af 2026-08-20 08:50


