Agent Skills › LanternOps/breeze › worktree-stack

worktree-stack

GitHub

用于在当前 git worktree 中快速启动隔离的 Playwright 端到端测试环境,包含数据库、API 和前端服务,并提供连接信息以驱动自动化测试。

.claude/skills/worktree-stack/SKILL.md LanternOps/breeze

触发场景

需要为当前代码分支启动本地测试环境 运行 Playwright E2E 测试 搭建与工作树隔离的开发栈

安装

npx skills add LanternOps/breeze --skill worktree-stack -g -y
更多选项

非标准路径

npx skills add https://github.com/LanternOps/breeze/tree/main/.claude/skills/worktree-stack -g -y

不安装直接使用

npx skills use LanternOps/breeze@worktree-stack

指定 Agent (Claude Code)

npx skills add LanternOps/breeze --skill worktree-stack -a claude-code -g -y

安装 repo 全部 skill

npx skills add LanternOps/breeze --all -g -y

预览 repo 内 skill

npx skills add LanternOps/breeze --list

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:

  1. Bring up the stack (per-worktree isolated): pnpm wt-stack up
    • Add --shared for the singleton stack (ports are always ephemeral, read from .breeze-stack.json).
    • Add --rebuild after Dockerfile or dependency changes.
  2. Read .breeze-stack.json at the worktree root for baseUrl, apiUrl, portalUrl, and admin creds (admin@breeze.local / BreezeAdmin123!).
  3. Drive Playwright: pnpm wt-stack test -- tests/<spec>.spec.ts, or point the Playwright MCP browser at baseUrl.
  4. Tear down: pnpm wt-stack down (removes volumes by default). Run it from the same worktree that ran up; the branch does not matter (#9864). up records the compose project in .breeze-stack.json and down, up and test reuse it; without a descriptor the name is derived from the worktree path (breeze-wt-<dir>-<hash>). down exits non-zero when it finds no matching project instead of silently doing nothing; pass BREEZE_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.stack pins RESEND_API_KEY, MAILGUN_API_KEY and SMTP_HOST to empty so a QA stack never sends real email even though the root .env carries live keys; set BREEZE_WT_STACK_LIVE_MAIL=1 to keep the root values.
  • Caddy serves plain HTTP in dev; baseUrl is http://localhost:<port>.
  • Caddy's host port is random by default and changes if caddy is restarted (docker restart re-allocates it), stranding anything that read baseUrl. Export BREEZE_WT_CADDY_PORT=<free port> before pnpm wt-stack up to pin it; the descriptor then has caddyPortPinned: true. Required for any storm scenario that restarts caddy (socket-drop, storm-suite) — storm.sh refuses to run it otherwise (#8718). up refuses 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 compose interface.
  • pnpm wt-stack ls lists running stacks; pnpm wt-stack info prints 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

同 Skill 集合

.claude/skills/agent-info/SKILL.md
.claude/skills/agent-log-debugging/SKILL.md
.claude/skills/breeze-helper/SKILL.md
.claude/skills/breeze-testing/SKILL.md
.claude/skills/e2e-coverage/SKILL.md
.claude/skills/feature-delivery/SKILL.md
.claude/skills/feature-testing/SKILL.md
.claude/skills/issue-to-pr/SKILL.md
.claude/skills/security-review/SKILL.md
.claude/skills/gh-queue/SKILL.md
.claude/skills/pre-release-sweep/SKILL.md
.claude/skills/ui-qa-sweep/SKILL.md

元信息

文件数
0
版本
0b71144
Hash
e836b179
收录时间
2026-08-20 08:50

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 17:45
浙ICP备14020137号-1