From 0d0a948b37c7c207076522533396c57d5308f8d4 Mon Sep 17 00:00:00 2001 From: ylm Date: Thu, 10 Sep 2026 16:56:38 -0400 Subject: [PATCH] Document host-test bootstrap for fresh worktrees and branch switches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Running host tests from a fresh worktree, or from the shared checkout after switching to a branch based on newer main, fails in a way that looks like an endless build: the dev server / vite build reports a cryptic unresolved-import error and the QUnit page never boots. The cause is an un-bootstrapped tree — workspace packages added since the last install (e.g. @cardstack/bxl) aren't linked, and @cardstack/boxel-icons has no built dist. Add a packages/host subsection documenting the bootstrap order (mise trust, pnpm install, pnpm build-common-deps), the fastest way to diagnose a stuck test page (read the Vite error overlay's message rather than polling for QUnit), the two common unresolved-import → fix mappings, and why to prefer the headless build over a second env-locked live dev server. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_014GsYGsuCqHJz9GAti4jheG --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index cf49d303b3d..092ffcf0869 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,6 +87,24 @@ ``` This is a red herring. Just ignore this error. +#### Running tests from a fresh worktree or after switching branches + +The instructions above assume a fully bootstrapped checkout. A fresh `git worktree`, or the shared checkout after switching to a branch based on newer `main`, is NOT bootstrapped, and the failure looks nothing like "missing dependency" — the dev server / `vite build` reports a cryptic unresolved-import error and the QUnit page hangs forever without ever booting (`window.QUnit` stays undefined). Bootstrap in this order before building or serving: + +``` +mise trust # a fresh worktree's .mise.toml is untrusted; mise silently no-ops until you do this +mise exec -- pnpm install # links workspace packages added since the last install (e.g. @cardstack/bxl) into packages/*/node_modules +mise exec -- pnpm build-common-deps # builds @cardstack/boxel-icons `dist` (consumed via its exports map, so needed even though boxel-ui is read from source) +``` + +Diagnosing a stuck test page fast (do this FIRST, before assuming it's a slow build): +- The blocker is almost always a single unresolved import breaking the whole test module graph. Read the Vite error overlay directly instead of polling for QUnit — it names the exact import in seconds: + `document.querySelector('vite-error-overlay')?.shadowRoot?.querySelector('.message')?.textContent` +- `Failed to resolve import "@cardstack/bxl"` (or any `@cardstack/*` workspace package) ⇒ run `pnpm install`. +- `Failed to resolve import "@cardstack/boxel-icons/"` ⇒ run `pnpm build-common-deps` (its `dist` isn't built by install). + +Prefer the headless `vite build --mode development && pnpm exec ember test --path dist --filter "…"` path over a second live dev server: the shared `pnpm start` server is env-mode/Traefik-locked (one slug at a time) and switching the shared tree under it triggers a long Vite dep re-optimize + full reloads. The realm-server stack the tests talk to (`../realm-server && pnpm start:all`) is backend-only and can be shared across checkouts on the usual localhost ports. + #### CSS Guidance - Use scalable units such as rem