Shaun Campbell
595b805722
All checks were successful
PR Checks / lint-test-and-docker-build (pull_request) Successful in 2m27s
72 lines
3.4 KiB
Markdown
72 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Tech Stack
|
|
|
|
- SvelteKit 5 + TypeScript + Bun + Tailwind v4 + better-sqlite3
|
|
- Auth via Synology SSO Server (OIDC) using Auth.js
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
bun run dev # Start dev server
|
|
bun run build # Production build
|
|
bun run check # TypeScript type-check
|
|
bun run lint # ESLint (must pass with 0 errors)
|
|
bun run format # Prettier formatting
|
|
bun run test # Run unit tests (must all pass)
|
|
bun run test:watch # Run tests in watch mode
|
|
bun run test:coverage # Run tests with coverage report
|
|
```
|
|
|
|
## Code Quality
|
|
|
|
### Linting and tests must pass before considering any task complete
|
|
|
|
After making changes, always verify:
|
|
1. `bun run lint` — must exit with 0 errors (warnings are acceptable)
|
|
2. `bun run test` — all tests must pass
|
|
|
|
For user-facing feature work, also add/update e2e coverage and validate it:
|
|
3. `bunx playwright test <target spec or suite>`
|
|
|
|
When work maps to a Gitea issue, upload an e2e run video to the issue:
|
|
- Generate one-off video artifacts with:
|
|
- `PW_VIDEO_MODE=on PW_TRACE_MODE=on bunx playwright test <target spec>`
|
|
- Prefer comment-level attachments: create a comment first, then attach video to that comment.
|
|
- `tea comment -l <login> -r <owner>/<repo> <issue-index> "<message>"`
|
|
- Upload with `curl` (the current `tea api` build here does not send multipart/form-data correctly for attachments):
|
|
- `TOKEN=$(awk '/- name: cloud.campbellwireless.net/{f=1} f && $1=="token:"{print $2; exit}' "$HOME/Library/Application Support/tea/config.yml")`
|
|
- `curl -fsS -X POST "https://cloud.campbellwireless.net/git/api/v1/repos/{owner}/{repo}/issues/comments/{comment_id}/assets" -H "Authorization: token $TOKEN" -F "name=<filename>" -F "attachment=@<path>"`
|
|
|
|
### Write unit tests after every major feature
|
|
|
|
When adding or significantly modifying server-side business logic (files under `src/lib/server/`), write corresponding unit tests in a `.test.ts` file alongside the module (e.g. `src/lib/server/lodgings.test.ts`).
|
|
|
|
Tests use Vitest with an in-memory SQLite database. Use the `setupTestDb()` helper from `src/tests/helpers.ts` to get a fresh DB per test:
|
|
|
|
```ts
|
|
import { setupTestDb } from '../../tests/helpers.js';
|
|
import type { Database } from './db/types.js';
|
|
|
|
let db: Database;
|
|
beforeEach(() => { db = setupTestDb(); });
|
|
afterEach(() => { db.close(); });
|
|
```
|
|
|
|
Test coverage should include the happy path, optional fields, ownership/authorisation checks, and any relationship linking (e.g. guests, travellers).
|
|
|
|
### ESLint notes
|
|
|
|
- `svelte/require-each-key` is set to `warn` — keyless `{#each}` blocks are acceptable where keys are not meaningful
|
|
- `@typescript-eslint/no-unused-expressions` is off — the `value;` reactivity-tracking pattern used in Svelte 5 `$effect` blocks is intentional
|
|
- Prefix unused variables/args/catch bindings with `_` to satisfy the no-unused-vars rule
|
|
- Use `// eslint-disable-next-line svelte/prefer-svelte-reactivity` for `new URLSearchParams()` used as local temporaries (not reactive state)
|
|
|
|
## DB / Testing Architecture
|
|
|
|
All server modules import `db` from `$lib/server/db/index.ts`. In tests, `_setDb()` is used to inject an in-memory SQLite instance, bypassing the `$env/dynamic/private` SvelteKit virtual module entirely. Never call `_setDb` in production code.
|
|
|
|
SvelteKit virtual modules (`$env/dynamic/private`, `$app/paths`) are stubbed via path aliases in `vitest.config.ts`.
|