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.