Update AGENTS.md

2026-07-16 20:23:59 -05:00
parent 2d0cf98ed3
commit f5896aa575
5 changed files with 1351 additions and 284 deletions
@@ -0,0 +1,363 @@
+# portal.Rhemawavetech.com
+
+SvelteKit 2 + Svelte 5 (runes) + Tailwind CSS v4 + Prisma 7 + PostgreSQL + Better-Auth.
+
+## Quick start
+
+```sh
+npm install          # engine-strict=true in .npmrc
+npm run prepare      # svelte-kit sync (generate types)
+npm run dev          # vite dev on :5173
+```
+
+Requires `.env` with at least `DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`.
+
+## Commands
+
+| npm run ...                | What it does                                     |
+| -------------------------- | ------------------------------------------------ |
+| `check`                    | `svelte-kit sync && svelte-check` (typecheck)    |
+| `lint`                     | `prettier --check . && eslint .` (order matters) |
+| `format`                   | `prettier --write .`                             |
+| `test`                     | `vitest --run` (single run)                      |
+| `test:unit`                | `vitest` (watch mode)                            |
+| `migrate -- --name <name>` | Create a Prisma migration                        |
+| `deploy`                   | Apply pending migrations                         |
+| `build`                    | Production build (adapter-node)                  |
+
+## Testing quirks
+
+- **Two Vitest projects**: `client` (Playwright/Chromium headless, `src/**/*.svelte.{test,spec}.{js,ts}`) and `server` (node env, everything else — `src/**/*.{test,spec}.{js,ts}` excluding `.svelte.*`). Tests co-located beside source files.
+- **`expect: { requireAssertions: true }`** — every test must assert something. No assertions = test fails.
+- **All route tests mock `$lib/db`** (Prisma client) and `$lib/auth-client`/`$lib/auth` via `vi.mock()`. Stub factories in `src/lib/test-utils.ts`.
+- **No `.env.test`** — mocking `$lib/db` makes real DB unnecessary.
+- **Mock `$app/forms`** for any component using `use:enhance` — provide `enhance: () => () => {}` (action → destroy fn).
+- **Mock TipTap** for client tests rendering ProclamationForm — the Svelte 5 component mock pattern is a function `($anchor: Element) => { …; $anchor.replaceWith(div); }`.
+
+## Architecture notes
+
+- **Route groups**: `(protected)/` requires auth + profile; `(user)/` is user-facing; `admin/` requires roleId <= 3 (STAFF+).
+- **Admin forms**: Each route has its own form component (e.g. `ProclamationForm.svelte`, `CategoryForm.svelte`). The generic `AdminForm.svelte` / `AdminPage.svelte` were **deleted**. Registry config (`registry.ts`) still provides metadata, list fields, search fields, relation options, etc., but forms are hand-written per route.
+- **Prisma client** generated to `src/lib/generated/prisma/` (not `node_modules/.prisma/client`). Lazy singleton via Proxy in `src/lib/db.ts`.
+- **Better-Auth** server instance in `src/lib/auth.ts`, browser client in `src/lib/auth-client.ts`. Session fetched in `src/hooks.server.ts`.
+- **Roles**: integer hierarchy (SUPER=1, ADMIN=2, STAFF=3, USER=4). `canAccessAdmin` checks roleId <= 3.
+- **Payments are stubbed** (`src/lib/payments.ts` — setTimeout + console.log).
+- **API keys**: SHA-256 hashed before storage (`ApiKey` model); only prefix (11 chars) stored for identification. `/api/v1/*` requires `Authorization: Bearer <key>`, except `/api/v1/automations/` (GHL webhook, no API key needed). Rotation: normal (48h grace via `expiresAt`) or emergency (immediate via `revokedAt`). Super-only admin page at `/admin/api-keys`.
+
+## Formatting conventions
+
+- Tabs, single quotes, no trailing commas, 100 print width (enforced by Prettier).
+- Svelte 5 runes only (`$state`, `$derived`, `$effect`, `$props`). No legacy stores (`writable`, `derived`, etc.).
+
+---
+
+## Svelte 5 Runes Gotchas & Patterns
+
+### `$state` initialization vs `$effect` sync
+
+State variables declared with `$state('')` are set once on component mount. To keep them in sync with a changing `$props()` value, use a **separate `$effect`**:
+
+```svelte
+<script lang="ts">
+	let { record = {} as Record<string, unknown> } = $props();
+
+	let name = $state('');
+	let freq = $state('');
+
+	// Sync local state when prop changes
+	$effect(() => {
+		name = String(record.name ?? '');
+		freq = String(record.solfeggioFrequencyId ?? '');
+	});
+</script>
+```
+
+This is the **only correct pattern** for form fields that edit an existing record. Do NOT initialize `$state` directly from the prop — that only captures the initial value and won't re-sync when the parent changes the record (e.g. switching from one row to another in a modal).
+
+### `$effect` ordering matters
+
+Effects run in declaration order. If you have multiple effects, the first one's writes are applied before the second one runs. This matters for the `dirty` flag:
+
+```svelte
+let dirty = $state(false);
+
+// Runs first — resets dirty on mount / record change
+$effect(() => {
+	dirty = false;
+});
+
+// Runs second — syncs field values
+$effect(() => {
+	name = String(record.name ?? '');
+	// …
+});
+```
+
+Both effects run synchronously during mount, so by the time the browser paints, all state is consistent.
+
+### `bind:value` on `<select>` is broken with `$effect`-driven state
+
+**DO NOT USE** `bind:value={stateVar}` on `<select>` elements when the state is set from a `$effect`. Svelte 5's select binding does not respond to `$state` changes triggered inside `$effect`. Instead:
+
+**Use `selected` on `<option>` + `onchange` on `<select>`:**
+
+```svelte
+<select name="solfeggioFrequencyId" onchange={(e) => freq = (e.target as HTMLSelectElement).value}>
+	<option value="">-- Select --</option>
+	{#each options as opt (opt.value)}
+		<option value={opt.value} selected={String(opt.value) === freq}>{opt.label}</option>
+	{/each}
+</select>
+```
+
+This pattern applies to ALL `<select>` elements in form components. The `value={stateVar}` prop directive also does not work reliably — always use `selected` on options.
+
+### `bind:value` on `<input>` works fine
+
+Unlike `<select>`, `bind:value` on `<input type="text">` works correctly with `$effect`-driven state. Feel free to use it for text inputs.
+
+### `$props()` destructuring
+
+Always destructure `$props()` with defaults:
+
+```svelte
+let {
+	record = {} as Record<string, unknown>,
+	fieldErrors = {} as Record<string, string>,
+	isSuper = false,
+}: { record?: Record<string, unknown>; … } = $props();
+```
+
+The type annotation on the destructuring object is REQUIRED for Svelte 5 to infer prop types. Default values are used when the parent doesn't pass that prop.
+
+### Component mocking for client tests
+
+When mocking a Svelte 5 component in `vi.mock`, use a function that takes `($anchor, props)`:
+
+```ts
+vi.mock('$lib/components/tiptap/TipTap.svelte', () => ({
+	default: ($anchor: Element, _props: Record<string, unknown>) => {
+		const div = document.createElement('div');
+		div.setAttribute('data-testid', 'tiptap-mock');
+		$anchor.replaceWith(div);
+	}
+}));
+```
+
+---
+
+## Testing Patterns & Gotchas
+
+### What tests to write
+
+For every admin route, write BOTH:
+
+1. **Server test** (`page.server.spec.ts`): Test the `load` function and all `actions` (upsert, delete). Cover role-based access control (Super vs non-Super content stripping, rejection of unauthorized mutations). Mock `$lib/db` and `$lib/svelte-admin/crud`.
+
+2. **Client test** (`Component.svelte.spec.ts`): Test the form component rendering in Playwright/Chromium. Cover:
+   - All fields render
+   - Pre-fill on edit (name input, select values)
+   - Conditional field visibility (e.g. content hidden for non-Super)
+   - Submit button disabled/enabled by dirty state
+   - No visual regression testing — only functional assertions.
+
+### Available Playwright/Vitest Browser Locator API
+
+These methods are available on `page` from `vitest/browser`:
+
+| Method              | Works? | Example                                       |
+| ------------------- | ------ | --------------------------------------------- |
+| `getByRole`         | ✅     | `page.getByRole('textbox', { name: 'Name' })` |
+| `getByText`         | ✅     | `page.getByText('Content')`                   |
+| `getByPlaceholder`  | ✅     | `page.getByPlaceholder('Email Address')`      |
+| `getByAltText`      | ✅     | `page.getByAltText('Sign In with Google')`    |
+| `getByTestId`       | ✅     | `page.getByTestId('tiptap-mock')`             |
+| `getByLabel`        | ❌     | Not available in this version                 |
+| `getByDisplayValue` | ❌     | Not available in this version                 |
+
+For label-identified elements, use `getByRole` with `name` option:
+
+- Text inputs → `getByRole('textbox', { name: /^Name$/ })`
+- Selects → `getByRole('combobox', { name: /^Frequency$/ })`
+- Buttons → `getByRole('button', { name: 'Save' })`
+
+**Always use regex `{ name: /^Exact$/ }`** for role queries to avoid strict-mode violations from substring matches (e.g. `'Category'` matching both `'Category'` and `'Sub-Category'`).
+
+### Querying select values in client tests
+
+Since `bind:value` on selects doesn't work with `$effect`-driven state, and we use `selected` on `<option>` instead, you can check the select's value directly:
+
+```ts
+const el = (await page
+	.getByRole('combobox', { name: /^Frequency$/ })
+	.element()) as HTMLSelectElement;
+expect(el.value).toBe('2');
+```
+
+The `.element()` call returns the underlying DOM element. This works synchronously because `selected` is set during render.
+
+### Server test patterns
+
+**Always call `vi.clearAllMocks()` in `beforeEach`.**
+
+Mock `$lib/db` with the exact Prisma model methods the code under test uses:
+
+```ts
+vi.mock('$lib/db', () => ({
+	prisma: {
+		proclamation: {
+			findMany: vi.fn(),
+			findUnique: vi.fn(),
+			create: vi.fn(),
+			update: vi.fn(),
+			delete: vi.fn()
+		},
+		proclamationCategory: { findMany: vi.fn() }
+	}
+}));
+```
+
+Mock `$lib/svelte-admin/crud` when the route uses custom upsert/delete logic:
+
+```ts
+vi.mock('$lib/svelte-admin/crud', () => ({
+	loadRecords: vi.fn(),
+	deleteRecord: vi.fn(),
+	superFormErrorsToFieldErrors: vi.fn(() => ({ error: '', fieldErrors: {} }))
+}));
+```
+
+Use `createLocals(mockUser({ roleId: 4 }) as any)` to simulate different user roles.
+Use `createFormRequest({ name: 'test' })` for form submissions.
+Use `.catch((e) => e)` + `isHttpError()` for error assertions.
+
+### `createLocals` nuances
+
+- `createLocals()` (no arg) → unauthenticated (session is `undefined`).
+- `createLocals(mockUser() as any)` → authenticated with the mock user object.
+- Cast to `any` when passing to load/action functions: `{ locals: createLocals(mockUser()) } as any`.
+
+### `vi.mock` hoisting
+
+All `vi.mock()` calls must be at the top level of the test file. Values needed inside `vi.mock` factories must use `vi.hoisted()`:
+
+```ts
+const { mockFn } = vi.hoisted(() => ({ mockFn: vi.fn() }));
+vi.mock('$lib/some-module', () => ({ default: mockFn }));
+```
+
+Imports of the mocked module must come AFTER `vi.mock()` calls.
+
+---
+
+## Admin Form Architecture
+
+### Per-route form components
+
+Each admin route under `admin/[model]/` has its own form component (e.g. `ProclamationForm.svelte`). These components:
+
+- Receive `record`, `fieldErrors`, `formError`, `relationOptionsData`, and model-specific extras (e.g. `categories`, `isSuper`) as props.
+- Use `$state` + `$effect` for field values (see "Svelte 5 Runes Gotchas" above).
+- Use `selected` on `<option>` for selects.
+- Use `oninput` on the `<form>` to track dirty state: `<form oninput={markDirty}>`.
+- Submit via `action="?/upsert"` with SvelteKit's `use:enhance`.
+
+### Server actions
+
+Routes with custom requirements (like proclamation's Super-only restriction) override the generic `upsertRecord`/`deleteRecord` with their own actions. The generic functions in `crud.ts` are still available and used by simpler routes.
+
+### Super-only proclamation restriction
+
+- **Load**: content field is stripped from records for non-Super users before returning.
+- **Upsert**: returns `{ success: false, error: 'Only Super admins can edit proclamations' }` for non-Super.
+- **Delete**: same early return for non-Super; delegates to `deleteRecord` for Super.
+- **Content field in form**: wrapped in `{#if isSuper}` block — hidden from non-Super users.
+- **Row click / New button**: disabled for non-Super in `+page.svelte`.
+
+### Dirty-state submit pattern
+
+When editing an existing record (`record.id` is truthy), the submit button is disabled until the user modifies at least one field. The form tracks dirtiness with `let dirty = $state(false)` and a `markDirty()` handler:
+
+```svelte
+<form oninput={markDirty}>
+	<button disabled={!!record?.id && !dirty}>Save</button>
+</form>
+```
+
+The `$effect` resets `dirty = false` on mount (when the record prop changes).
+
+---
+
+## Generated / build artifacts
+
+- `.svelte-kit/` — SvelteKit generated types (gitignored)
+- `src/lib/generated/prisma/` — Prisma client output (not gitignored; regenerate with `npx prisma generate`)
+
+---
+
+## API v1 Endpoints
+
+| Route                                | Method | Auth     | Description                                      |
+| ------------------------------------ | ------ | -------- | ------------------------------------------------ |
+| `/api/v1/categories`                | GET    | API key  | List all proclamation categories                 |
+| `/api/v1/frequencies`               | GET    | API key  | List all solfeggio frequencies                   |
+| `/api/v1/proclamations`             | GET    | API key  | List proclamations (with optional `?key` + `?email` filter) |
+| `/api/v1/license`                   | POST   | API key  | Validate key: `{ license_key, email_address }`     |
+| `/api/v1/automations/create/account` | POST  | None     | GHL webhook: create user + license key + emails   |
+
+## GHL Webhook — Auto Account Creation
+
+`POST /api/v1/automations/create/account` — excluded from API key auth in `hooks.server.ts`.
+
+**Payload:**
+
+```json
+{ "email": "...", "name": "...", "subscription_level": "Basic" }
+```
+
+`subscription_level` must match a `SubscriptionLevel.name` in the database.
+
+**Flow:**
+1. If user email doesn't exist → `auth.api.signUpEmail()` with random temp password
+2. Query `Verification` table for the auto-generated verification token → construct verify URL
+3. Send `automated-user-registration` Resend template (variables: `firstName`, `tempPassword`, `verifyUrl`, `loginUrl`)
+4. Create `LicenseKey` record (`active: true`, `level: subscription_level`)
+5. Send `license-key-delivery` Resend template (variables: `firstName`, `license_key`)
+6. If user already exists → skip signup, just create key + send delivery email
+
+**Better Auth email callbacks** (`sendVerificationEmail`, `sendResetPassword`) use `void` + `.catch()` — template send failures are logged, never crash the server.
+
+## Resend Email Templates
+
+| Template ID                    | Variables                                                       | Subject (API-level)            |
+| ------------------------------ | --------------------------------------------------------------- | ------------------------------ |
+| `automated-user-registration`  | `firstName`, `tempPassword`, `verifyUrl`, `loginUrl`            | "Your account is ready"        |
+| `license-key-delivery`         | `firstName`, `license_key`                                      | "Your Rhemawave License Key"   |
+| `email-verification-email`     | `target_email_address`, `verification_link`                     | "Verify your email address"    |
+
+Variables must be declared in the Resend template editor's Variables section. Undeclared variables render as literal `{{{varName}}}` text.
+
+Controlled by `src/lib/server/resend.ts` (`sendMail`) and `src/lib/server/email-verification.ts`.
+
+## AdminTable Drag-and-Drop
+
+AdminTable supports full-`<tr>` drag-and-drop reorder via props:
+
+- `draggable: boolean` — enables drag handles on rows
+- `onReorder: (ids: string[]) => Promise<void>` — called after drop with new row ID order
+- `copyableFields: string[]` — field keys to show a copy-to-clipboard icon
+
+**Pattern:** `$derived` + `dragOverride` — no `$effect` sync. `handleDragOver` always calls `preventDefault()` for reliable drop targets. `handleDrop` awaits `onReorder` then calls `invalidateAll()`.
+
+See `src/lib/components/admin/AdminTable.svelte` and `src/routes/(protected)/admin/proclamation-categories/+page.svelte` for example usage.
+
+## License Key Admin
+
+- **Create**: `/admin/license-keys` form → `?/createKey` action. Requires email + subscription level. Generates key, persists to DB, emails the key via Resend template.
+- **Replace**: Table row action → `?/replace` action. Deletes old key, creates new one with same user + level. No email sent.
+- **Subscription level** stored as `SubscriptionLevel.name` string (not a FK).
+
+## Key Generation
+
+- **License keys**: 16 uppercase hex chars in `XXXX-XXXX-XXXX-XXXX` format. `crypto.randomUUID()` → strip dashes → uppercase → 4x4 chunks. Level stored as `SubscriptionLevel.name` string (not FK).
+- **API keys**: `sk_` + 64 random hex chars. SHA-256 hashed for storage; first 11 chars stored as `keyPrefix` for identification.