build(web): replace Playwright MCP with project-scoped Playwright CLI

- feat: add `.agents/skills/playwright-cli/` with complete Skill
  markdown, agent interface, and 9 reference files covering session
  management, spec-driven testing, video recording, tracing, storage,
  request mocking, element attributes, test debugging, and running
  custom code
- feat: add `.playwright/cli.config.json` to configure the Playwright
  CLI
- feat: add `web/package.json` `playwright:cli` script that resolves
  `playwright cli` from the repo root
- build: remove `@playwright/mcp` dependency from `web/package.json`
- build: set `XDG_CACHE_HOME` in `mise.toml`
- build: delete `.codex/config.toml` (MCP server config)
- docs: update `README.md`, `docs/web/roadmap.md`,
  `docs/web/decisions.md`, and `web/README.md` to reflect the new
  Playwright CLI approach
This commit is contained in:
2026-07-15 23:10:43 +08:00
parent 29b176d2db
commit 52dd56ff06
21 changed files with 1793 additions and 113 deletions
+31
View File
@@ -46,6 +46,10 @@ account, admin, or large-transfer designs.
## 2026-07-14: Project-local Headless Browser Tooling
**Status**: Agent-debugging and browser-version decisions were superseded by
the 2026-07-15 Playwright CLI decision below. The Playwright Test and
project-local resource decisions remain active.
**Context**: Browser behavior needs deterministic E2E coverage and interactive
agent debugging inside a long-lived headless Debian Incus container. Tooling
should remain reproducible without placing browser binaries or generated
@@ -69,3 +73,30 @@ artifacts in a developer's home directory.
browser install scripts before browser tests or MCP debugging.
- Browser failures can retain traces, screenshots, and video under
`.artifacts/playwright/` without adding generated files to source control.
## 2026-07-15: Stable Playwright CLI Agent Debugging
**Context**: The official Playwright MCP package pulled an alpha Playwright
core alongside the stable test runner. That required a second Chromium
revision and expanded the agent tool surface. Playwright 1.61.1 already
provides the same browser-debugging command set through its embedded CLI.
**Decisions**:
| Area | Choice | Guidance |
|------|--------|----------|
| Agent entry point | Stable `playwright cli` behind the `playwright:cli` npm script | Run it from `web/` with `mise exec -- npm run playwright:cli --`; do not use a global install, standalone `@playwright/cli`, `playwright-cli`, or floating `npx`. |
| Version ownership | `@playwright/test` is the only Playwright dependency | E2E tests and interactive debugging use Playwright 1.61.1 and Chromium revision 1228. |
| Agent workflow | Repository Skill in `.agents/skills/playwright-cli` | Start from Playwright's generated Skill, then preserve the MyGO npm wrapper, headless workflow, artifact policy, and debugging principles when updating it. |
| Browser policy | Bundled Chromium, headless, isolated, and sandboxed | `.playwright/cli.config.json` is the shared CLI configuration; do not silently disable the Chromium sandbox. |
| Local resources | Repository `.cache/` and `.artifacts/` directories | `mise.toml` redirects XDG, npm, and browser caches; CLI output is limited to 100 MB under `.artifacts/playwright-cli/`. |
**Consequences**:
- A fresh environment needs one locked npm install, the Debian browser
libraries, and the stable Chromium install before E2E or CLI use.
- Changing Playwright's CLI entry point only requires changing the npm script;
the repository Skill and operator commands remain stable.
- The official generated references remain available through progressive
disclosure, while the main Skill carries only the MyGO-specific workflow.
- The MCP server configuration, alpha Playwright core, and Chromium revision
1232 are no longer required.