scenarios

# Scenarios Use this skill for committed fixture checks and runtime proof of prepared scenarios. ## Contract - Pick the proof path from the registered scenario key. - Use committed `fixtures/*` only as sources. The runnable app lives under `tmp/scenarios/*`. - Stop once the assigned proof path succeeds. Do not keep poking the app for sport. ## Hard Rules - Never run committed `fixtures/*` in place. - Always prepare into `tmp/scenarios/<name>/project`. - `fixtures:*` owns committed snapshot sync/check. - `scenario:*` owns runnable temp apps. - Stop spawned dev processes once proof succeeds or fails. - If a temp app is stale after package or scaffold changes, rerun `bun run scenario:prepare -- <name>` once. If it still fails, debug the cause. Do not loop forever. - If a scenario has no real browser auth surface, do not invent one. - For bootstrap-heavy Convex lanes, `bun run scenario:check -- <name>` is the proof. Do not replace it with ad-hoc `scenario:dev`. ## Canonical Commands ```bash bun run fixtures:sync bun run fixtures:check bun run scenario:prepare -- <name> bun run scenario:dev -- <name> bun run scenario:check -- <name> bun run scenario:test -- <name> bun run test:runtime bun run test:auth -- <name|url> bun run test:e2e -- <name|url> ``` `test:auth` and `test:e2e` assume the scenario is already running. `scenario:test` wraps the proof matrix below. `test:runtime` runs `scenario:test -- all` and is the default non-browser runtime gate. `test:e2e` is a separate auth browser lane and should be run only when auth surfaces changed. ## Proof Matrix ### Plain runtime proof Use this path for: - `next` - `vite` - `create-convex-bare` - `create-convex-nextjs-shadcn` - `create-convex-react-vite-shadcn` Run: 1. `bun run scenario:prepare -- <name>` 2. `bun run scenario:dev -- <name>` 3. Wait for ready logs. 4. Stop. Or: 1. `bun run scenario:test -- <name>` ### Auth demo proof Use this path for: - `next-auth` - `start-auth` Run: 1. `bun run scenario:prepare -- <next-auth|start-auth>` 2. `bun run scenario:dev -- <next-auth|start-auth>` 3. `bun run test:auth -- <next-auth|start-auth>` 4. Stop. Or: 1. `bun run scenario:test -- <next-auth|start-auth>` Why: - `scenario:test -- <next-auth|start-auth>` proves runtime + auth smoke only. - Browser auth proof belongs to the explicit `test:e2e` lane: 1. `bun run scenario:prepare -- <next-auth|start-auth>` 2. `bun run scenario:dev -- <next-auth|start-auth>` 3. `bun run test:e2e -- <next-auth|start-auth>` ### Auth backend proof without browser auth Use this path for: - `vite-auth` Run: 1. `bun run scenario:prepare -- vite-auth` 2. `bun run scenario:dev -- vite-auth` 3. Stop. Or: 1. `bun run scenario:test -- vite-auth` Why: - There is no `/auth` page or equivalent browser auth surface today. - Do not fake `test:e2e`. - Do not add `test:auth` here unless the registry grows a dedicated auth proof lane. ### Bootstrap-heavy Convex proof Use this path for: - `convex-next-auth-bootstrap` - `convex-vite-auth-bootstrap` - `convex-next-all` - `create-convex-nextjs-shadcn-auth` Run: 1. `bun run scenario:check -- <name>` 2. Stop. Or: 1. `bun run scenario:test -- <name>` Why: - Fresh kitcn lanes already bootstrap during `scenario:prepare` through `kitcn init -t <next|vite> --yes`, then finish the bootstrap-heavy proof with in-place `kitcn init --yes` after plugin setup. - The raw Convex auth adoption lane still owns `convex init` plus `kitcn add auth --preset convex --yes`. - Raw Convex auth adoption is not a `next-auth` browser demo. Do not invent `/auth`. ## Re-prepare Rule Re-run `scenario:prepare` once when: - package or scaffold source changed - the temp app predates that change - the temp app is missing expected local env or generated files Otherwise, reuse the prepared app. ## Examples ### `next-auth` or `start-auth` ```bash bun run scenario:prepare -- next-auth bun run scenario:dev -- next-auth bun run test:auth -- next-auth ``` Short path: ```bash bun run scenario:test -- next-auth ``` Browser lane: ```bash bun run scenario:prepare -- next-auth bun run scenario:dev -- next-auth bun run test:e2e -- next-auth ``` ### `vite-auth` ```bash bun run scenario:prepare -- vite-auth bun run scenario:dev -- vite-auth ``` Short path: ```bash bun run scenario:test -- vite-auth ``` ### `convex-next-all` ```bash bun run scenario:check -- convex-next-all ``` Short path: ```bash bun run scenario:test -- convex-next-all ```