Testing overhaul#80
Merged
Merged
Conversation
Adds the Phase-1 requireRole gate to every admin route that was missing
auth (audit's CRITICAL bucket). Removes the commented-out RBAC in
create-admin. Restructures handlers into the four-stage shape so auth
sits above any try/catch. Tightens catch-all 500s to a fixed error
string per docs/api-contract.md.
Flips ~50 RED matrix tests to GREEN. Zero admin failures remaining in
tests/integration/api/_auth-matrix.test.ts.
Out of scope (Phase 4.4): SQL-injection-shape filter in courses/assign;
service-role client in pending-bookings/*; Zod schemas and response-
shape wrapping.
Behaviour-preserving fallbacks added by the contract-fix agent:
- courses POST: body.course.name ?? body.course.title (UI client sends
one, matrix sends the other — pin in 4.4)
- employees/[id]/availability PUT: defaults missing payload to {} so the
matrix not-401 probe doesn't 500 (full Zod in 4.4)
Routes fixed (all RED → GREEN against per-route 5Q test files):
- GET /api/coach/lessonspace/[coachId]/[studentId] (no-auth credential mint)
- PATCH /api/coach/lesson-progress (no ownership + token/badge side effects)
- PATCH /api/coach/lesson-feedback (no ownership)
- GET /api/coach/lessons (no ownership on ?studentId)
- GET /api/coach/conversation (auth-via-data-lookup)
- GET /api/coach/conversation/message (auth-via-data-lookup)
- GET /api/coach/sessions (auth-via-data-lookup)
- PATCH /api/coach/sessions/[id] (no ownership)
Each route now follows the four-stage shape: requireRole([2]) →
Zod .strict() → ownership helper → execute. Responses use
{ error: string } body or the documented success patterns
({ success: true } / { resource } / { sessions: [...] }).
Helper additions:
- assertCoachOwnsSession (ownership.ts) — 404 for both "missing"
and "not yours" per the enumeration rule for sequential bigint
IDs (api-ownership.md:170-178).
Helper bugfix:
- expectNoRow used .select("id") which fails on composite-PK
tables like student_tokens; switched to .select("*").
Deferred to Phase 4.2 spillover:
- PATCH /api/coach/lesson-tasks (FormData; needs multipart support
in tests/helpers/request.ts).
LessonSpace launch errors downgrade to 404 when the student has
no lesson_space_id ("room not provisioned"), instead of 500.
The N+1 in coach/conversation/message is preserved; contract pins
output shape only.
Routes fixed (per-route 5Q test files green):
- POST /api/checkout — removed password from Stripe metadata,
dropped 6 PII console.log lines, requireRole([1])
for the authed branch, 401 (not 404) for anon
- GET /api/attendance — assertOwnsStudent (role 1) or
assertCoachAssignedToStudent (role 2);
admin bypasses
- POST /api/attendance — requireRole([2,3]) + assignment check
- DELETE /api/attendance — requireRole([2,3]) + assignment check
- GET /api/parent/students/[studentId] — assertOwnsStudent + Zod;
404 with real HTTP status
(not status-in-body)
- GET/PUT /api/parent/students/[studentId]/availability — assertOwnsStudent
+ Zod; GET wraps
response in
{ availability }
- PATCH /api/parent/setup — requireRole([1]) + Zod + { error: string }
shape (was { success, message })
- GET /api/lesson-progress — fixed mixed error+success body
(404 { error } when no student profile)
Test fixture changes:
- attendance.test.ts: `regular` now seeded as owner of studentId so
GET-for-owner test is meaningful; coach linked to student so
POST/DELETE ownership tests pass. Removed the calcified
"no ownership check on GET" assertion.
Side-effect helpers (tests/helpers/sideEffects.ts) now used across
all 6 routes for row presence/absence assertions.
… (phase 4.4)
Routes brought into compliance:
- POST + GET /api/admin/courses/assign — Zod schemas, removed `"use server"`
directive, replaced SQL-injection-shape filter
`.not("id", "in", \`(${ids.join(",")})\`)` with in-memory diff,
wrapped GET response as { students }, added per-route 5Q test
- GET /api/admin/pending-bookings — dropped service-role client,
wrapped response as { pending }
- PATCH /api/admin/pending-bookings/[id] — dropped service-role,
replaced manual validation
with strict Zod schema
- POST /api/admin/pending-bookings/[id]/approve — Zod param validation
- POST /api/admin/pending-bookings/[id]/preview — dropped service-role,
Zod schemas;
matchmaking logic
preserved verbatim
- GET /api/admin/payment-plans/stripe-preview — Zod query schema
- POST /api/admin/create-coach — moved requireRole to line 1 (was
inline getUser shape), Zod with
strict, no auth-error message leak
Cleanup of three routes flagged by the audit that weren't in earlier
phases (all matrix REDs now flip to GREEN):
- GET /api/coach/students — requireRole([2]), wrapped as { students }
- GET /api/parent/sessions — requireRole([1]), wrapped as { sessions }
- GET /api/parent/students — requireRole([1]), wrapped as { students }
Matrix fix:
- FAKE_ID was "00000000-0000-0000-0000-000000000099" which fails
Zod's .uuid() (the version digit must be 1-5 per RFC 4122). Changed
to a v4-shape "00000000-0000-4000-8000-000000000099". This is the
reason all role-2/3 rejection tests against checkout were failing
with 400 instead of 403 (checkout validates before auth per the
documented exception).
Matrix is now 219/219 GREEN — every gated route in src/app/api
satisfies the role-gate contract spec.
…pi/user/role - Delete /api/profiles/select (redirect-based GET route that didn't fit the JSON contract). Sole caller (parent-without-PIN branch of /profiles page) now uses the existing selectProfile server action — same code path every other no-PIN branch already uses. The action's behavior is regression-tested by tests/integration/actions/selectProfile.test.ts. - /api/user/role: swap inline supabase.auth.getUser() + manual account lookup for requireRole([]). Behavior is identical; this just brings the route into the canonical four-stage shape. Matrix + selectProfile action: 232/232 GREEN. Phase 4.5 cleanup — addresses two of the three remaining stylistic drift items the post-Phase-4 audit flagged. Third item (admin Zod sweep) is a follow-up. coach/lesson-tasks (Phase 4.2 spillover) and Phase 5 webhooks remain outstanding.
PATCH /api/coach/lesson-tasks was the last Phase-4 deferred route. Per the
audit, it was the highest-severity remaining CRITICAL:
- No requireRole — any authed user could call.
- No ownership check on student_id from FormData.
- Service-role storage client outside webhook scope.
- No Zod validation; manual field-by-field.
Fixes:
- requireRole([2]) for the role gate.
- assertCoachAssignedToStudent(student_id) for ownership.
- Zod schema (.strict()-like; FormData scalar fields validated).
- Drop the service-role createAdminClient — use auth.supabase.storage
for both uploads and deletes (route is admin-only after the gate).
- Wrap success response as { task: row } / { deleted: true } (was raw row).
- Tighten 500 path to a fixed "Internal server error" (was err.message leak).
- Preserve every branch of the existing delete-when-empty / upsert /
file-replace logic.
Test infra: added optional `formData` field to tests/helpers/request.ts
`call()` helper. When provided, the body is sent as multipart/form-data
with the boundary set by FormData itself; JSON body is ignored.
Test file: tests/integration/api/coach/lesson-tasks.test.ts. 11 tests
covering ownership, validation, upsert and delete-when-empty paths.
File-upload branches are exercised by manual testing — out of scope
for the contract gates.
Phase 4 is now complete: every gated non-webhook route in src/app/api/**
satisfies the role-gate + Zod + ownership contract.
LessonSpace webhook (CRITICAL recipient fix):
- Was emailing every AI session summary to hardcoded wdstalkmaze@gmail.com
instead of the student's family account. Now resolves recipient from
account.email via the resolved student → account chain.
- Switched error responses from 200-with-{status,message}-in-body to proper
HTTP status codes with { error: string } body. 404 for unknown rooms,
422 for incomplete student records, 500 for server errors.
- Dropped 4 console.log debug lines.
- Uses createServiceRoleClient (the legitimate use per contract).
- Note: signature verification still not implemented (audit deferral); the
route accepts any POST. Tracked as Phase 5 follow-up.
Stripe webhook (minor fix to enable testing):
- Replaced `headers()` from next/headers with `request.headers.get()` for
the stripe-signature lookup. No behavior change in prod; routes already
have the request object, no reason to go through the runtime indirection.
- Side benefit: contract tests can now set the signature header via
NextRequest directly (the next/headers mock only carries cookies).
Three contract test files (19 tests total, all green):
- tests/contract/webhooks/lessonspace.session-summary.test.ts (6 tests):
recipient is account.email, no email on unknown room, no email on empty
summary, error body shape, error status codes.
- tests/contract/webhooks/stripe.invoice-paid.test.ts (7 tests):
first-payment insert, renewal update, sessions_remaining reset on
renewal, pending_plan_id cleared on matching renewal, signature
verification (missing + tampered).
- tests/contract/webhooks/stripe.subscription-deleted.test.ts (6 tests):
active sub marked cancelled, orphan event acknowledged, cross-student
isolation, state-based idempotency on replay. Last test documents the
audit's known gap (no event-id dedupe → stale replays can cascade onto
re-subscribed students); flagged as future cleanup.
Stripe SDK is mocked per file with vi.mock; webhooks.constructEvent kept
real so signature verification actually runs in tests. Uses the existing
tests/helpers/stripe.ts signWebhookPayload helper.
…(interim)
Product decision: AI summaries go to the shared wdstalkmaze@gmail.com inbox
during the early product phase so the founding team can review every
session. Reverts the recipient change from the previous Phase 5 commit.
The account.email lookup chain remains in place — the route still resolves
the family's email from students.account_id even though it doesn't use it
yet. That keeps the flip-to-per-family-delivery a one-line change in the
route (replace RECIPIENT_OVERRIDE with account.email).
Test flipped to match: the contract test now asserts the interim
wdstalkmaze@gmail.com recipient. The describe block names this as the
"(interim: shared inbox)" contract, and the inline comment in the route
points at the test as the load-bearing reminder.
When this flips back to per-family delivery:
- src/app/api/webhooks/lessonspace/route.tsx: `to: RECIPIENT_OVERRIDE`
→ `to: account.email`, delete the override constant.
- tests/contract/webhooks/lessonspace.session-summary.test.ts: flip
the assertion to `expect(recipients).toContain(family.email)` and
add `expect(recipients).not.toContain("wdstalkmaze@gmail.com")`.
…rningSpace
End-of-overhaul audit flagged /api/webhooks/stripe/learningSpace as the
last remaining must-fix-before-done item: it was an HTTP route in the
webhooks/ namespace with no signature verification, no auth check, no
Zod validation. It accepted an arbitrary student_id from any caller and
provisioned a LessonSpace room as a side effect.
It was reachable from outside the Stripe webhook handler — anyone could
POST /api/webhooks/stripe/learningSpace { student_id } and trigger a
LessonSpace room creation against any student.
It was only ever called once, by line ~502 of the Stripe webhook itself,
as a fetch self-hop. Removed by:
- Extracting the provisioning logic into a new lib function
src/lib/lessonspace/server/provisionStudentRoom.ts. Takes the
webhook's service-role supabase client as a parameter (no cookies in
webhook context). Returns a typed discriminated union for the three
outcomes (provisioned / already_exists / student_not_found).
- Replacing the fetch hop in the Stripe webhook with a direct call.
- Deleting src/app/api/webhooks/stripe/learningSpace/route.ts entirely
(including the GET handler that exposed raw LessonSpace org data
publicly).
The provisioning step still throws in tests because LESSONSPACE_WEBHOOK_URL
isn't set in .env.test — the webhook catches and logs, returns 200. All
20 webhook contract tests pass.
Addresses the HIGH and MEDIUM cluster the post-Phase-4 audit flagged:
admin routes that have requireRole([3]) but were left with ad-hoc
validation and bare-array responses. Admin-only blast radius, so not
security-critical — pure contract drift cleanup.
16 admin routes touched:
assignments/route.ts — GET wrap { assignments }, POST Zod
assignments/[id]/route.ts — composite-id Zod (uuid_uuid)
courses/route.ts — GET wrap, POST Zod, enumerate columns
courses/[id]/route.ts — PUT/DELETE Zod
courses/[id]/lessons/route.ts — GET wrap, POST Zod, removed 4
console.log + 5 status-in-body bodies
courses/[id]/lessons/[lessonId]/ — PUT Zod + { lesson } wrap; DELETE
route.ts status-in-body bug fixed
employees/route.ts — GET wrap, enumerate columns
employees/[id]/route.ts — PUT Zod
employees/[id]/availability/ — GET/PUT Zod, dropped resolveCoachUUID
route.ts no-op stub, comment on the
delete-then-insert integrity TODO
payment-plans/route.ts — GET wrap { plans }, POST Zod
payment-plans/[id]/route.ts — PATCH Zod
payment-plans/[id]/archive/route.ts — PATCH Zod
students/route.ts — GET wrap { students }, enumerate cols
students/[id]/route.ts — PUT Zod
students/lessons/[studentId]/ — GET param Zod, removed 2 console.log,
route.ts fixed bare-string error response,
wrap response { courses }
create-admin/route.ts — POST Zod
Common transformations across the batch:
- Add strict Zod schemas for body + path params (with .strict()).
- Replace bare-array responses with named-collection wrappers.
- Replace { status, message }-in-body with proper HTTP status +
{ error: string }.
- Replace `select("*")` with explicit column lists where possible.
- Tighten catch-all 500s to fixed "Internal server error" strings.
- Drop console.log debug noise; keep console.error in catch blocks only.
Matrix: 227/227 GREEN (matrix 219 + courses-assign 8). No behaviour
changes from the matrix's perspective — all routes still pass their
role gates. The contract changes are response-shape + validation
strictness; they don't move the role-gate needle.
Untouched (per user direction): /api/webhooks/stripe (event-id dedupe
remains the known follow-up).
…alisation)
Closes the audit's "domain-logic-placement" finding — routes with 150+
lines of inline business logic that should live in src/lib/<domain>/
per docs/api-contract.md §domain-logic-placement.
Four extractions, four routes shrunk from monoliths to ~50-line
auth/validate/authorize/delegate handlers:
1. src/lib/lessons/server/awardProgress.ts
← coach/lesson-progress (token + badge cascade)
The cautionary tale named explicitly in the contract docs. Route
went from 142 lines to 53. Result is a typed discriminated union
so the route doesn't introspect cascade state.
2. src/lib/lessons/server/insertLessonIntoCourse.ts
← admin/courses/[id]/lessons POST (linked-list head/tail mutation
+ default lesson_tasks + token row)
Route's POST shrunk from ~170 lines to ~30. Inline TODO in the lib
notes the compound-mutation atomicity gap (would need an RPC).
3. src/lib/scheduling/server/previewPendingBooking.ts
← admin/pending-bookings/[id]/preview POST (availability shading +
conflict detection + occurrence generation)
Route went from 343 lines to 67. dayjs timezone math, conflict
detection, and FullCalendar event shaping all live in the lib now.
4. src/lib/lessons/server/getStudentLessonsByCourse.ts
← admin/students/lessons/[studentId] GET (lesson assembly with
linked-list traversal + storage URL resolution)
Route went from 186 lines to 36. N+1 storage URL lookup is
preserved (acceptable for the small admin-UI lesson counts; noted
in the lib comment).
Matrix + lesson-progress + courses-assign: 244/244 GREEN.
Three changes to get the GitHub Actions integration job green:
1. .github/workflows/test.yml
- Add RESEND_API_KEY=re_test_dummy and LESSONSPACE_API_KEY=ls_test_dummy
to the CI .env.test write. HTTP calls to Resend and LessonSpace are
intercepted by MSW in tests, but the route/lib env-guards check for
presence and 500-early when missing. Locally these leak in via
.env.local; CI never had them.
- Add testing-overhaul to the push/pull_request branch list so this
branch actually runs CI.
2. src/lib/auth/server/middleware/updateSession.ts
- Whitelist /forgot-password and /reset-password for unauthenticated
users. The reset-password page is reachable from a Supabase email
link with no session yet (the token IS the credential there).
Previously /reset-password bounced unauthed users to /login,
breaking the password-recovery flow.
3. src/middleware.ts (restructured)
- Add authed-user redirects from public-auth pages (/signup,
/forgot-password, /) to the appropriate dashboard
(regular → /profiles, coach → /coach, admin → /admin). Previously
these pages just stayed accessible to logged-in users — confusing
UX with no test coverage.
- Add /payments, /reset-password, /profiles, /onboarding to the
profile-locked carve-out list. Regular users without an active
profile cookie can now reach /payments (which IS where they go to
resolve a missing subscription) and /reset-password.
- Reorganized into a documented step list at the top of the file.
- Behavior preserved for: RBAC on /profiles, /coach, /admin;
subscription gate on /student/**; webhook bypass.
Test run under CI-shaped env (no .env.local, only the CI-written
.env.test): 527 passed, 1 todo, 0 failed across 29 test files.
Down from 18 failures pre-fix.
Anchor file for a cold-start agent picking up after the contract rewrite. Includes: - Response-shape change table for every route I wrapped - Error-shape change summary - Routes deleted entirely (with replacement pointers) - Hard rules (no test edits, no Stripe webhook touches, no force pushes) - Decision-vs-mechanical-fix triage - Final smoke-test checklist for the user when they return
Phase 6 cleanup after the API contract rewrite (Phases 0-5):
- Type fixes: typed Record<string, unknown> updates as TablesUpdate<T>
for admin payment-plans PATCH and admin students PUT, so .update()
accepts the dynamic-key payload.
- tsconfig: add @tests/* path alias and exclude tests/ from the
next-build typecheck (vitest configs already type-check tests at
runtime, and tests/helpers carry shapes Next's tsc can't reconcile).
- vitest.integration: drop forks.singleFork (removed in vitest 4;
fileParallelism: false + pool: forks already serializes within a
single fork).
- UI consumers: update bare-array readers to unwrap the new
{ students }, { courses }, { employees }, { assignments },
{ lessons }, { plans }, { pending }, { availability }, { messages },
{ parent }, { task }, { course }, { lesson }, { plan }, { employee },
{ student }, { assignment } envelopes returned by the gated routes.
Build, typecheck, and ESLint (pre-existing UI warnings excepted) clean.
…/checkout CheckoutPageClient was JSON.stringify'ing searchParams.get(...) values for pFName/pLName/sFName/sLName/email/password directly into the request body. When the params are absent (the authed-flow case), those values are null, and the route's strict Zod schema rejects null on z.string().optional(), producing a 400 before the route ever runs. Only include signup-only fields when studentId === "new", and drop the password field entirely (the route still tolerates it in the schema, but the audit flagged sending plaintext passwords through this endpoint).
Five docs deleted (superseded or historical):
PHASE6_BRIEF.md — handoff doc for the cold instance; work done.
PHASE6_STATUS.md — Phase 6 status report; covered by the
runbook summary + commit chain.
docs/api-conventions.md — pre-rewrite audit of route patterns. Every
pattern it documented (inline getCurrentUser,
manual role checks, hand-rolled verifyOwnership)
has been replaced by the contract layer.
api-contract.md / api-auth.md / api-ownership.md
are canonical now.
docs/testing-critique.md — motivated the rewrite. The rewrite happened;
the critique's advice (pair status assertions
with side-effect assertions, etc.) is now
embodied in the test files themselves.
docs/testing-strategy.md — original strategy doc. Tooling decisions
(Stripe mocking, MSW, vitest config) are now
in testing-coverage.md.
Five docs updated to reflect the post-rewrite state:
docs/test-rewrite-runbook.md — Phase 6 box ticked; stale lessonspace
recipient note fixed; status banner at
the top noting the rewrite is closed.
docs/testing-coverage.md — full rewrite. Old headline (146/117
pass/fail) was mid-rewrite snapshot.
New: 627 tests, 626 + 1 todo, all
intentional REDs cleared.
docs/repo-quality-audit.md — status banner. Body kept as historical
starting-state record. Residual list
surfaced at top.
CLAUDE.md — "Known quality issues" section replaced
with a contract-first orientation:
four-stage shape, helper pointers,
response-shape rules, residual list,
guidance for new code. Supporting docs
list refreshed and reorganised.
docs/api-contract.md +
docs/api-auth.md — small refs to deleted docs cleaned up.
GitHub Actions runners share IPs across many users; Docker Hub's anonymous-pull limit (100/6h per IP) is easy to hit on busy days. `supabase start` pulls 10+ images by default, of which 6 aren't used by integration tests: studio — UI; not used in tests imgproxy — image transforms; not used pooler — Supavisor connection pooler; tests connect directly vector — log shipping; not used edge-runtime — edge functions; not used mailpit — local inbox UI; Resend is mocked via MSW Kept: postgres, gotrue (auth), postgrest (data API), postgres-meta (schema introspection), storage-api (file uploads — coach/lesson-tasks + admin storage helpers use it). If we hit the limit again with the trimmed set, follow-up is to add Docker Hub credentials as a repo secret and `docker login` before `supabase start`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Contract rewrite: API + tests
Summary
127 files changed (+10,844 / −6,686). Brings every gated route in
src/app/api/**under a uniform contract:requireRolefor auth, Zod.strict()for validation,assertOwns*helpers for per-resource authorization,{ error: string }for failures, named-collection wrappersfor list responses. Adds a per-route test architecture, webhook contract tests, and resolves every CRITICAL finding from
docs/repo-quality-audit.md.Tests: 627 total — 626 passing, 1 todo, 0 failing (99 unit + 528 integration/contract across 36 files). CI is green on this branch.
Why
The original audit (
docs/repo-quality-audit.md) flagged ~30 security and consistency issues across the API surface:create-adminhad its RBAC check commented out — any authenticated user could grant admin.coach/lessonspace/[coachId]/[studentId]accepted IDs from the URL with no verification — anyone could mint a LessonSpace teacher link for any coach/student pair./api/checkoutaccepted, logged, and persisted plaintext passwords in Stripe metadata.studentIdbelonged to them.Every CRITICAL item above is fixed.
How (phased plan, executed in order)
The full history is in
docs/test-rewrite-runbook.md. Headline phases:requireRole,assertOwnsStudent,assertCoachAssignedToStudent,assertCoachOwnsConversation,assertCoachOwnsSession. Each unit-tested independently._auth-matrix.test.tsas the single declarative role-gate spec for every gated route.subscriptionsdomain rewrite — the worked example. 4 routes brought under the contract, 4 per-route 5-question test files (ownership / validation / response / persistence / external calls).checkout,attendance,parent/*), 7 admin business-logic, plus cleanups.invoice.paid(first payment + renewal),customer.subscription.deleted(idempotency), LessonSpacesession.summary. Stripe signature verification covered.tsc --noEmitclean,next buildsucceeds, ~17 UI consumers updated to read the new wrapped response shapes.What's new
Auth + ownership helpers (
src/lib/auth/server/)requireRole(allowedRoles)— returns{ user, account, supabase } | NextResponse. Line 1 of every gated route.assertOwnsStudent,assertCoachAssignedToStudent,assertCoachOwnsConversation,assertCoachOwnsSession— typed per-resource ownership checks. 404-vs-403 rule perdocs/api-ownership.md:166.Extracted domain logic (
src/lib/<domain>/server/)awardProgress.ts— token + badge cascade (was 150 lines inline incoach/lesson-progress).insertLessonIntoCourse.ts— linked-list head/tail maintenance (was inline inadmin/courses/[id]/lessons).previewPendingBooking.ts— scheduling math, conflict detection, occurrence generation (was 225 lines inline).getStudentLessonsByCourse.ts— lesson assembly + storage URL resolution.provisionStudentRoom.ts— replaces the deletedwebhooks/stripe/learningSpaceroute (was a public mutation endpoint disguised as a webhook).Test infrastructure (
tests/helpers/)db.ts—resetAll()(TRUNCATE all + clearauth.users). New test files usebeforeEach(resetAll).sideEffects.ts—expectRowExists/expectNoRow/getRowfor service-role observation.stripeMocks.ts,subscriptionFixtures.ts— domain-specific fixture helpers.request.ts—call(handler, opts)now supportsformData(multipart) in addition to JSON.Test architecture
tests/integration/api/_auth-matrix.test.ts— single parameterised file with oneAuthCaseper gated route. Adding a route = one row.tests/integration/api/<route>.test.ts. Pattern documented atdocs/test-rewrite-runbook.md:156.tests/contract/webhooks/. Stripe SDK module-mocked withwebhooks.constructEventkept real so signature verification runs.Middleware fixes — audit-flagged redirect bugs closed (
/signup,/forgot-password,/,/reset-password,/payments). Seesrc/middleware.ts.CI
.github/workflows/test.ymlwritesRESEND_API_KEYandLESSONSPACE_API_KEYdummies (route env-guards check presence; MSW intercepts the actual HTTP calls).vitest.integration.config.ts:fileParallelism: falseso tests run sequentially against the shared local Supabase.Intentionally NOT addressed (residuals tracked in
docs/repo-quality-audit.md)wdstalkmaze@gmail.com— product decision.account.emailresolution is wired in the route; the flip is a one-line change in the route + the contract test.admin/employees/[id]/availability,admin/courses/assign,insertLessonIntoCourse. Canonical fix is a Postgres function called viasupabase.rpc(...). RPC migration is a follow-up.react-hooks/set-state-in-effect,no-explicit-any, etc. All in dashboard components, all predate this PR.CourseLessonPanel.tsx,ParentProfilePageClient.tsx,LessonDetailClient.tsx,StudentProfilePageClient.tsx. Out of scope.Suggested review order
docs/api-contract.md,docs/api-auth.md,docs/api-ownership.md— the spec the rewrite produced. These are the only docs you need to read to evaluate the architecture.src/lib/auth/server/{requireRole,ownership}.ts— the helpers. Small, typed, unit-tested.src/app/api/subscriptions/cancel/route.ts— Phase 3 canonical example of the four-stage shape.src/app/api/coach/lesson-progress/route.ts+src/lib/lessons/server/awardProgress.ts— route + extracted domain logic, the cautionary tale called out inapi-contract.md §domain-logic-placement.tests/integration/api/_auth-matrix.test.ts— the role-gate matrix.tests/integration/api/subscriptions/cancel.test.ts— Phase 3 canonical 5-question test file.tests/contract/webhooks/stripe.invoice-paid.test.ts— webhook contract testing pattern.src/middleware.ts— restructured; documented step list at the top of the file.For depth:
docs/test-rewrite-runbook.mdhas the full phase-by-phase plan, decision log, and the templates used (5-question test file, matrix file).Test plan
npm run test:unit— 99 passing.npm run test:integration— 528 passing, 1 todo, 0 failing (requiresnpx supabase start+.env.test).PHASE6_STATUS.md(admin dashboards, coach dashboards, parent dashboards, checkout, profile selection, Stripe + LessonSpace webhook triggers). Should be manually walked through before merge — typeerrors don't catch shape mismatches that pass through
unknown.Caveats for reviewers
docs/test-rewrite-runbook.mddocuments judgment calls (e.g., 404 vs 403 for foreign-resource access, response-shape patterns).