hackerspace.sh/docs/HANDOFF-audit-cleanup.md

HANDOFF — audit / cleanup / architecture engagement

Branch: audit/cleanup-architecture (40 commits ahead of main, not pushed). Status: all gates green — tsc 0 errors · eslint 0 errors · 645 tests · next build ✓. Full audit + plan + progress log: docs/AUDIT-2026-08.md. Architecture: ARCHITECTURE.md.

⚠️ main auto-deploys to production on push (.github/workflows/deploy.yml → SSH → droplet deploy.sh). Do not push to main until this branch is reviewed and you intend to deploy.

What was done

Delivered against the original brief (audit → fixes → tests → refactor → docs), then a second separation-of-concerns pass on top.

• Type safety. 586 → 0 tsc errors; removed next.config typescript.ignoreBuildErrors, so every build/deploy now type-checks. Root cause was the @supabase/ssr ↔ supabase-js version drift (schema collapsed to never), fixed by annotating the client factories (no dependency bump).
• Tooling / CI. Added ESLint 9 flat config (eslint.config.mjs), a typecheck script, and a checks-only CI workflow (.github/workflows/ci.yml: typecheck + lint + unit tests), separate from deploy.
• Confirmed bugs fixed (one commit + regression test each): invite max_uses TOCTOU (atomic CAS), board invite re-arming, appealIncident admin-gate + orphan rollback, SSRF hex-IPv6, payment dues regression (advance-only) + payment member_id IDOR scoping, three null-deref crashes, broken member-directory visibility gate, equipment/proposals scoping + unverified-member gating, door-log parser, CSV-import hang, and a plaintext-secrets security bug (ops "Add Secret" wrote the value unencrypted from the browser — now via createSecret, AES-GCM).
• Tests. Replaced a tautological actions.test.ts (asserted string literals) with real authz/IDOR tests; added authz-primitive tests and per-fix regression tests.
• Refactor (all 10 slices). lib/validations.ts (143 exports) → lib/validations/* barrel; lib/types.ts → types/domain/*; lib/actions/{classes,door,forms}.ts → per-capability folders behind the lib/actions barrel; the 663–956-line ops/settings/members client components decomposed into thin orchestrators + panels/+components/ (also fixed a form-field-focus footgun); dead code removed. types/database.ts is left pristine (regenerate, don't hand-edit).
• Separation of concerns. No client component writes to the DB directly anymore. The ops area-lead roster and the comms message send were the last holdouts — both now go through server actions (validated, authz-gated, space-scoped, audited); comms derives sender identity server-side (was impersonation-prone). Only browser-client usage left: auth (login/signup) and the comms realtime read.
• Verification. A re-audit found zero refactor regressions (every authz gate + space_id scope + handler independently verified across the splits/decompositions). A final independent adversarial review of the separation-of-concerns commits found no introduced bug, security hole, or regression.

How to verify (from a clean checkout of the branch)

pnpm install --frozen-lockfile
pnpm run typecheck   # 0 errors
pnpm run lint        # 0 errors (warnings are tracked debt)
pnpm run test:run    # 645 pass
pnpm build           # compiles + type-checks all routes

What is NOT done / residual risk

1. Full authenticated UI testing did not run — the dev environment had no Docker → no local Supabase. Public pages + routing were browser-smoke-tested (render clean; authed routes redirect to /login), and all routes compile via next build, but the decomposed ops/settings/members screens were not clicked through against real data. Do a manual smoke-test against a real backend before merge.
2. types/database.ts needs regeneration against the live schema (supabase gen types typescript --schema public > types/database.ts). That removes 3 hand-added RPC entries and ~11 // TODO(types) join casts, and lets the governance rows in types/domain/governance.ts collapse to Tables<>/ Enums<>. Needs DB credentials. Highest-leverage next step.
3. Deferred bug L3 — markOnboardingStepDone read-modify-writes a JSON column; a concurrent double-submit can drop a step. Needs a DB-side atomic append (RPC / jsonb operator + migration).
4. CI runs only unit tests — the integration + Playwright e2e suites need a DB service wired in (and the run should fail on 0 executed integration tests so a missing DB can't masquerade as passing).
5. Pre-existing comms realtime dedup edge case (app/(app)/comms/comms-client.tsx ~L82) — two identical messages fired in quick succession before the first realtime event lands can collapse onto one row (duplicate render / duplicate React key). Not introduced by this work (the old direct-insert path had the same race); the robust fix is a client-generated message id / nonce for dedup.
6. Commit granularity caveat — commits are logically split (one per fix), and most were gated before commit; a few in the final SoC round were split from a combined working tree and were not each independently tsc/test-gated. The final tree is fully green. If you need per-commit bisectability, verify per commit or squash-merge.

Recommended merge path

Review Phases A + B + CI first (low-risk, high-value: type safety, bug fixes, tests). Then the refactor slices (structural, verified by tsc + build + tests). Then the SoC pass. Merge via PR; a squash or merge-commit is fine. After merge to main it deploys — have the manual UI smoke-test done first.

---

Update — 2026-08-05 (merged to main, live)

The audit/cleanup branch was merged (PR #7) and deployed. The four residual items above are now resolved:

1. Manual UI smoke-test — DONE. The decomposed ops/settings/members screens (plus onboarding, dashboard, /me) were clicked through against a real seeded backend; a live mutation (area-lead create) and the certifications dialog were exercised. Zero console/server errors.
2. types/database.ts regenerated — DONE. Regenerated from the canonical scripts/schema.sql (built on a local Supabase). All 11 // TODO(types) join casts removed, hand-added RPCs now native, and types/domain/governance.ts collapsed to Tables<>/Enums<>. Two embeds that resolved to any[] were traced to the deliberately-wide ServerSupabase gate type and fixed by using createClient() directly.
3. Deferred bug L3 — FIXED. markOnboardingStepDone now routes through mark_onboarding_step_done (migration 055): a single atomic, ownership-guarded dedup-append into onboarding_progress. Covered by integration/onboarding-progress.test.ts (incl. a 12-way concurrency case).
4. CI DB-backed suites — DONE. .github/workflows/ci.yml now has an integration-e2e job that stands up a Supabase service, runs the integration suite and Playwright e2e, and fails if the integration suite executes 0 tests (so a missing DB can't masquerade as passing).

Items 5 (comms realtime dedup) and 6 (commit granularity) still stand as written.

Docs section + homepage fix (branch feat/docs-and-homepage-fix)

• Homepage redirect fix (app/(landing)/page.tsx): it used to redirect('/dashboard') for any signed-in visitor, so the marketing site (and the new docs) were unreachable while logged in. The redirect is gone; the nav/hero/closing CTAs are now auth-aware (signed-in shows a "Dashboard" button).
• Public /docs section organized by Diátaxis (tutorials / how-to / reference / explanation), 34 pages covering every module. Source of truth is lib/docs/nav.ts; content is markdown under content/docs/<category>/<slug>.md, read at build time (the routes are statically generated) and rendered by components/docs/docs-markdown.tsx (reuses the existing react-markdown stack, no new deps). The (docs) route group has its own theme (docs.css) matching the public site. Screenshots live in public/docs-media/ and are embedded as captioned figures. Docs prose contains no em-dashes by house style.
• Authoring notes: add a page = add it to DOC_CATEGORIES in lib/docs/nav.ts and drop the matching content/docs/<category>/<slug>.md. No H1 in the body (the page chrome renders the title). Cross-link docs as /docs/<category>/<slug> and app screens as /route. Screenshots go in public/docs-media/ and embed as ![caption](/docs-media/<name>.jpg) (the alt text becomes the figure caption). House style: no em-dashes. Every page was fact-checked against the code by an adversarial verify pass; the permission gotcha that recurs: server actions often allow board, but the space-config UI (/settings, /customize config panels, integrations) is admin-only.
• Middleware gotcha (bit the first deploy): proxy.ts (the Next 16 middleware) redirects any path not in its PUBLIC_ROUTES allowlist to /login. Any new public route group must be added to PUBLIC_ROUTES, or it 307s unauthenticated visitors to login. /docs is now listed; /docs-media/* static images already bypass via the image matcher. Test public pages with cookies cleared: a browser "new tab" keeps the session, so it is NOT a signed-out test.

Shipped: merged via PR #8 (+ a proxy.ts public-route hotfix) and deployed. Live at hackerspace.sh/docs (verified public: /docs returns 200 with no session; /dashboard still redirects to /login). Gates: tsc 0 · lint 0 errors · build ✓ (all 34 /docs pages prerendered) · CI green · deploy ✓.