trips/CLAUDE.md

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

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:

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.