workout-app / rules

---
description: Known sandbox restriction affecting `npm run build`. Read this before running build commands.
globs: 
alwaysApply: true
---

# Build Sandbox Caveat

`npm run build` (which runs `tsc -b && vite build`) **will fail inside the Cursor sandbox** with this error:

```
Error: Unable to write the service worker file. 'Unexpected early exit.
Unfinished hook action(s) on exit: (terser) renderChunk'
```

This is **not a project bug**. workbox-build uses `worker_threads` via terser, and the sandbox blocks that syscall.

## What to do

- Always run `npm run build` with `required_permissions: ["all"]`.
- **Do NOT** check out `main` to verify — the error is identical on every branch.
- For type-checking without the bundler, run `npx tsc -b` (what CI's `type-check`
  job runs) or `npx tsc -p tsconfig.app.json --noEmit`. Both work in the sandbox.

## Never use `npx tsc --noEmit`

It **always passes and verifies nothing.** The root `tsconfig.json` is a
solution file — `"files": []` plus project references — so the command loads zero
files and exits 0 on a codebase that cannot compile. It is worse than no check,
because it reads like a green one.

```bash
# ❌ silently vacuous — reports success with a type error in src/
npx tsc --noEmit

# ✅ actually loads src/ and the test files
npx tsc -p tsconfig.app.json --noEmit
```

## `tsconfig.app.json` does not cover `scripts/`

Same trap, narrower. `tsconfig.app.json` is `include: ["src"]` and
`tsconfig.node.json` is `include: ["vite.config.ts"]`, so **nothing under
`scripts/` is type-checked by any project in the solution.** A broken script
gets a green `tsc -b`.

Type-check a script standalone, with the `tsconfig.node.json` flags spelled out:

```bash
npx tsc --noEmit --ignoreConfig --strict --target es2023 --lib es2023 \
  --module esnext --moduleResolution bundler --resolveJsonModule \
  --verbatimModuleSyntax --moduleDetection force --erasableSyntaxOnly \
  --noUnusedLocals --noUnusedParameters --types node --skipLibCheck \
  scripts/<file>.ts
```

## Run vitest with the Supabase env stripped

CI has no `.env`, so `src/lib/supabase.ts` throws `supabaseUrl is required.`
**at import time** there. Locally `.env.local` supplies one, which hides the
failure: a component test that forgets `vi.mock("@/lib/supabase")` passes on your
machine and dies in CI before a single test runs.

Reproduce CI by emptying the two variables:

```bash
VITE_SUPABASE_URL= VITE_SUPABASE_ANON_KEY= npx vitest run
```

Any test whose component tree reaches the client — directly or transitively —
needs the stub the other ~50 test files use:

```ts
vi.mock("@/lib/supabase", () => ({ supabase: { from: vi.fn() } }))
```

More agent context in PierreTsia/workout-app

23 other files this repository gives its agents.