setup: Playwright Chromium download failure aborts setup before skills/hooks/migrations land
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Summary
`./setup` is structured so that the riskiest step (Playwright Chromium
download) runs **before** several lower-risk steps (skill linking, hook
installation, version migrations). When the riskiest step fails, the
script exits 1 mid-run and the lower-risk steps never get a chance to
complete.
This means a user on a flaky network, a corporate machine with a
locked-down `bunx`, or hitting the Bun-on-Windows pipe bug
(oven-sh/bun#4253) ends up with a half-installed gstack: bun may be
copied, the browse binary may be built, but the actual user-facing
artifacts (skills, hooks, plan-tune machinery, gbrain regen) are
missing. A re-run of `./setup` does the same thing — dies at the same
step — and the user has no easy path to a working install minus
browser features.
## Failure modes observed
The current `setup` order interleaves trivial filesystem ops, expensive
compute, settings.json mutations, and external network/sudo steps:
1. Build browse binary (network: `bun install`)
2. Install Playwright Chromium (network, sudo, package manager) — **may exit 1**
3. Ensure `~/.gstack/projects/` exists (trivial filesystem)
4. Install for Claude (filesystem)
5-6. Install for Codex / Kiro / Factory / OpenCode (filesystem)
7. .agents/ sidecar symlinks (filesystem)
8. Run version migrations (filesystem)
9. First-time welcome + legacy cleanup (filesystem)
10. Team mode hook install in `settings.json` (mutation)
11. Plan-tune hook install in `settings.json` (mutation)
Concrete user-facing breakage when step 2 fails:
| Step | What's missing on re-run failure | User impact |
|------|----------------------------------|-------------|
| 4-6 | Skills not symlinked into `~/.claude/skills/` | `/qa`, `/ship`, `/review` etc. don't exist |
| 7 | `.agents/` sidecar symlinks not created | Codex skills broken |
| 8 | Version migrations not run | Stale config from prior gstack version |
| 9 | Welcome message + `/tmp/gstack-latest-version` cleanup never happens | Cosmetic, but the legacy `/tmp` file accumulates |
| 10 | Team-mode `SessionStart` hook not registered in `settings.json` | Team auto-sync silently disabled |
| 11 | Plan-tune `PostToolUse` + `PreToolUse` hooks not registered | `/plan-tune` AUQ capture silently disabled |
Even the trivial `mkdir -p "$HOME/.gstack/projects"` happens AFTER the
Playwright step, so a brand-new user without `~/.gstack/` ends up
without it.
## Proposal
Reorder `setup` so steps run in increasing order of failure probability:
- **Phase A** — pure filesystem (`~/.gstack/`, welcome, GBrain detection
file scan). Cannot fail in practice.
- **Phase B** — local compute: bun build, skill linking, version
migrations, GBrain SKILL.md regen. Fails only on bun bugs, fully
reproducible locally.
- **Phase C** — `settings.json` mutation: team-mode and plan-tune hooks.
Fails only if `settings.json` is malformed, fully reversible.
- **Phase D** — external network / sudo / package managers: coreutils
on macOS, emoji font on Linux, Playwright Chromium. Highest fail risk.
With this order, a Phase D failure leaves the user with a working gstack
install minus browser-driven features (`/qa`, `/design-review`,
`make-pdf`, sidebar, `/pair-agent`). Re-running `./setup` retries only
the failed phase since A-C are idempotent.
A separate (smaller) follow-up — already in flight as #1900, coordinated
with #1838 — converts the Playwright `exit 1` paths to best-effort warns
so even a re-run failure is non-fatal.
## Related
- #1883 — original bundled PR that combined the phase reorder with two
unrelated bug fixes and a Playwright behavior change. Per review
request, that PR is being split into three:
- #1898 — surgical bug fixes (`bun_cmd` routing + `tail -3` pipe)
- #1900 — Playwright `exit 1` → best-effort warn (coordinates with #1838)
- PR for this issue — the phase reorder itself
- #1838 — Pin Playwright install to the bundled version (touches the
same Playwright block).
- oven-sh/bun#4253 — Bun-on-Windows pipe bug that Phase D needs to
tolerate, not abort over.
Contributor guide
Research direction
Start with ./setup and map the existing setup steps into the proposed filesystem, local-compute, settings-mutation, and external-operation phases. Verify that a failure in the Playwright or other Phase D work still leaves the earlier artifacts installed, while repeated runs remain safe; review the related Playwright block and settings.json mutations without duplicating the changes in #1900 or #1838.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bun
- Domain
- tooling
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100