ci: add global-install smoke test for CLI preview

[miguel-heygen]

Summary

Adds a CI smoke test that reproduces the exact failure from #452 — hyperframes preview printing ✘ [ERROR] Could not resolve "…/runtime/entry.ts" when installed globally via npm.

The job simulates what a real user does:

1. npm pack the CLI → install globally with --prefix
2. hyperframes init test-project --example blank
3. hyperframes preview --port 3099 in background
4. curl http://localhost:3099/api/runtime.js — assert non-empty JS
5. Assert stderr has no ✘ [ERROR] or Failed to load runtime

Also adds .github/workflows/** to the change detection filter so CI jobs run when workflow files change.

Validation: the test catches the broken state

Verified locally that the grep pattern fires on the pre-#452 code and passes on the fixed code:

Broken (0.4.15-alpha.1, globally installed via npm i -g hyperframes@alpha):

$ hyperframes preview --port 3098 2>/tmp/hf-stderr.log
$ grep -E '✘ \[ERROR\]|Failed to load runtime' /tmp/hf-stderr.log
✘ [ERROR] Could not resolve "/opt/homebrew/lib/node_modules/hyperframes/runtime/entry.ts"
[studio] Failed to load runtime source fallback: Error: Build failed with 1 error: …
→ CAUGHT: assertion fires, test fails ✓

Fixed (built from #452 fix branch):

$ node packages/cli/dist/cli.js preview --port 3098 2>/tmp/hf-stderr.log
$ grep -E '✘ \[ERROR\]|Failed to load runtime' /tmp/hf-stderr.log
(empty)
→ PASS: no errors ✓

If this smoke test had existed before #452, it would have caught the bug before it shipped.

Test plan

• Grep pattern catches broken state — verified locally against pre-fix(cli): prevent esbuild runtime error in global/npx installs #452 global install
• Fixed state passes — verified locally against fix(cli): prevent esbuild runtime error in global/npx installs #452-fixed build
• CI job runs green — https://github.com/heygen-com/hyperframes/actions/runs/24854025990/job/72762086753

[jrusso1020]

Verdict: approve

Exactly what we discussed — reproduces Teodora's user-flow in CI. npm pack → npm i -g --prefix /tmp/hf-smoke → init blank → hyperframes preview → probe /api/runtime.js for non-empty body, then grep stderr for ✘ \[ERROR\]|Failed to load runtime. The grep pattern was validated against the pre-#452 broken state (both substrings present in stderr) and passes on fixed code, so the alarm is load-bearing, not decorative. --prefix /tmp/hf-smoke + PATH=/tmp/hf-smoke/bin:$PATH sidesteps sudo cleanly.

The .github/workflows/** addition to changes.code is a quiet quality-of-life fix — without it, CI wouldn't rerun when the workflow itself changed. Good catch.

Plumbing is sound: needs: [changes, build] for gating, 10-minute timeout, 15-second server-readiness poll, background server kill + wait for clean teardown, grep -qE with raw unicode ✘ (which works because run shell is UTF-8 by default on ubuntu-latest). Smoke job itself clocks ~50s on this run — cheap. Smoke: global install is already green on the head commit.

Two non-blockers:

1. Port 3099 is also used by regression tests. On dedicated ubuntu-latest it doesn't collide, but if someone ever runs this job on a self-hosted runner alongside regression, you'd want an env-var override or a random-port probe. Not worth complicating now.

2. npx hyperframes path isn't covered. The reported bug hit both global and npx — same resolution, different path layout under ~/.npm/_npx/<hash>/node_modules/. A follow-up variant job (or a matrix) that does npm_config_cache=$(mktemp -d) npx hyperframes@file:./packages/cli/... init ... would close the other half of the repro. Non-blocking since #452 fixes both paths with the same guard, and the grep pattern would trigger equivalently for either.

Two housekeeping asks when you merge: (a) tick the last checkbox in the test plan once this lands (CI green on this branch is the evidence), and (b) flip Smoke: global install to a required status check in branch protection so future regressions actually block merge — the test only protects if it gates.

Ship it.

---

Review by hyperframes