wind-sport-planner

Imported from jaakkos/wind-sport-planner (AGENTS.md). Install upstream with npx skills add jaakkos/wind-sport-planner. Copyright stays with the author.

Agent instructions — Fjell Lift (wind-sport-planner)

Git commits — non-negotiable

Do not mention AI, assistants, or AI-based dev tools anywhere in Git commit metadata. This applies no matter who or what produced the diff. Treat it as a hard repo rule: violating it is incorrect work, not a stylistic choice.

In scope (must stay clean):

• Commit subject and body
• Merge or squash messages you write
• Tags or release notes only if they are generated from commit messages (keep source commits clean)

Forbidden (examples, not exhaustive): names or logos of tools (e.g. Cursor, Copilot, ChatGPT, Claude, “AI”, “LLM”), trailers such as Made-with: …, Generated-by: …, “assisted by …”, or Co-authored-by: lines that identify an automated assistant. If you use Git trailers, they must not attribute the change to AI.

Do instead: normal, factual messages — what changed and why — in the same tone as hand-written project history. No attribution of the implementation to any product or model.

What this repo is

Next.js app: magic-link auth (Auth.js), PostgreSQL + PostGIS (Prisma), MapLibre map, Open-Meteo weather, practice areas and session logging. Production is Coolify — README.md and docs/deploy-coolify.md (app fjelllift, public https://fjelllift.com).

Next.js

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Code changes

• Match existing patterns in the file you touch (imports, types, component style). Prefer small, focused diffs; no drive-by refactors or unrelated files.
• Before finishing work that touches app or library code, run what CI runs: npm run lint, npm run test, npm run build. If you changed flows covered by E2E, run npm run test:e2e (needs local Postgres migrated and env configured; Playwright can start next dev itself).

Environment & configuration

• Node.js 22.12+ (Prisma 7 and tooling; repo pins 22.14 — use .nvmrc with nvm use / fnm use, and match Coolify NODE_VERSION in docs/deploy-coolify.md).
• .npmrc sets legacy-peer-deps=true so nodemailer 8 (security fixes) installs cleanly with next-auth v5 beta, which still peer-declares nodemailer 7. npm ci respects this file (CI and Coolify).
• Copy .env.example → .env (and optionally .env.local). Never commit real secrets; keep them in env files or the host’s secret store.
• AUTH_SECRET: long random string (see .env.example). AUTH_URL: canonical public URL with no trailing slash; wrong values break magic links and new URL(...) usage (see comments in .env.example and src/auth.ts).
• Email: local dev uses Mailpit (Docker) via EMAIL_SERVER_* when RESEND_API_KEY is unset; production (Coolify) uses platform SMTP (EMAIL_SERVER_*, EMAIL_FROM). Do not set RESEND_API_KEY in production.
• Optional: NEXT_PUBLIC_MAPTILER_API_KEY for MapTiler basemap, NEXT_PUBLIC_* legal contact vars on /privacy.

Local services (Docker)

• docker compose up -d: PostGIS postgis/postgis:16-3.4 (user/db/password align with .env.example: wind / wind_sport) and Mailpit (SMTP 1025, UI http://localhost:8025).
• After schema changes: npm run db:dev (iterate) or npx prisma migrate deploy (apply existing migrations). Then npm run dev → http://localhost:3000.

Repository layout

Imports use the @/* alias → src/* (see tsconfig.json).

TypeScript, ESLint, styling

• TypeScript: strict mode; prefer explicit types at boundaries (API payloads, Prisma results you reshape).
• ESLint: flat config in eslint.config.mjs (eslint-config-next core-web-vitals + TypeScript + eslint-plugin-react-hooks). npm run lint. Generated client under src/generated/prisma/** is ignored — fix issues in prisma/schema or app code, not generated files.
• Hard rules (not warnings): @typescript-eslint/no-unused-vars, @typescript-eslint/no-unused-expressions, react-hooks/rules-of-hooks, react-hooks/exhaustive-deps. Prefix intentionally-unused parameters with _.
• Size caps (errors, application code only): max-lines 600 per file, max-lines-per-function 400. If a function is creeping toward the cap, extract a hook into src/components/map-hub/hooks/ or a pure helper into src/lib/ rather than raising the limit. Tests under tests/** and e2e/** are exempt from both caps.
• Dead-code & cycles: npm run audit:dead (Knip — unused files/exports/dependencies, also wired into CI) and npm run audit:cycles (Madge — import cycles in src/). Run these when you finish a feature so the report stays clean.
• Tailwind CSS v4 with PostCSS; global styles in src/app/globals.css. Follow existing utility and layout patterns on nearby pages.

npm scripts (common)

Testing

• Vitest (vitest.config.mts): Node environment, tests in tests/**/*.test.ts, tests/setup.ts resets mocks after each test. Coverage is configured for src/lib/**/*.ts — add unit tests next to new pure logic in src/lib/ when behavior is non-trivial.
• Playwright (playwright.config.ts): specs in e2e/, loads .env.local then .env, E2E_PORT overrides port (default 3000). CI uses npx next dev as web server; locally it can reuse an already running dev server.

Database (Prisma)

• Edit prisma/schema.prisma; create migrations with npm run db:dev (or equivalent prisma migrate dev). Commit migration SQL under prisma/migrations/.
• Client output is src/generated/prisma (generator output in schema). postinstall runs prisma generate; npm run build also generates. Do not commit hand-edits inside src/generated/prisma.
• Production applies migrations in Coolify pre-deploy (npx prisma migrate deploy — see docs/deploy-coolify.md) — avoid workflows that only migrate locally.

CI and deploy gate

• .github/workflows/ci.yml on push/PR to main/master: npm ci → Prisma migrate against service Postgres → lint → Vitest with coverage → production build → Playwright.
• Keep CI green before deploying main on Coolify (docs/deploy-coolify.md).

API, auth, and server boundaries

• Prefer Route Handlers in src/app/api/ for JSON APIs; validate input with Zod. Domain-specific schemas live next to their domain (e.g. src/lib/practiceArea/schema.ts). Keep route files thin — parse → query/mutate → return.
• Use the shared helpers in src/lib/api/ instead of rolling your own:
  • requireUserSession and isErrorResponse (handler.ts) — auth gate that returns a 401 NextResponse you forward unchanged.
  • parseJsonBody(req, schema) (handler.ts) — Zod-validated body parsing that returns either the parsed value or a 400 response.
  • parseSportParam / parseAtParam / parseOptimalWindHalfWidthDegParam (forecastQuery.ts) — common forecast query-string parsers shared across forecast routes.
• Session/auth through Auth.js (src/auth.ts, src/app/api/auth/[...nextauth]/route.ts). Respect existing patterns for protected data (Prisma queries scoped by user where applicable).

Project conventions (preserve these)

The codebase has been deliberately reshaped around a few patterns; keep new work consistent with them.

• src/components/MapHub.tsx is an orchestrator, not a god component. Heavy state and effects belong in dedicated hooks under src/components/map-hub/hooks/ (useMapBundle, useForecastRanking, useMapInteractionMode, etc.). Pure rendering of a sub-region belongs in its own component under src/components/map-hub/. The orchestrator should mostly be hook calls + JSX.
• Pure logic lives in src/lib/ (geo helpers, ranking heuristics, wind formatting, schema validation, API clients). Each module is testable in Node and is the place to add new unit coverage. Prefer small, single-purpose files — split when a module grows past a couple of clearly different concerns.
• API client modules live in src/lib/<domain>/client.ts and are the only place components call fetch for backend routes. Tests mock fetch against these modules instead of mocking it inside components.
• Sidebar UX uses CollapsibleSection with summary text so collapsed sections still convey state. New sidebar content should follow the existing tab/section pattern (PlanTab, MapTab, YouTab).
• No as any in application code; use proper types or a Zod-validated boundary instead.

Maps and weather

• Map UI: MapLibre / react-map-gl, heavy UI in src/components/ (e.g. map hub). Styles/helpers in src/lib/map/.
• Weather: src/lib/weather/ (router, Met.no, Open-Meteo). Keep provider boundaries clear when adding sources or debug flags.

Debugging production / Coolify deployments

When a deploy fails or the app errors in prod:

1. Coolify UI (WireGuard) — http://10.20.0.10:8000 → project fjelllift → deployment logs / runtime logs.
2. SSH (via infra jump) — docker logs on the app container / coolify-proxy for Traefik/ACME.
3. API — COOLIFY_TOKEN from 1Password vamelivo-infra Coolify API token; see vamelivo-infra docs/runbooks/coolify.md.

Do not paste Coolify/API tokens or DB passwords into source files, AGENTS.md, or commit messages.

Cursor Cloud specific instructions

Services overview

Docker in the Cloud VM

Docker is not pre-installed. Install Docker CE, fuse-overlayfs, and switch iptables to legacy before starting dockerd:

sudo dockerd &>/tmp/dockerd.log &
sudo chmod 666 /var/run/docker.sock

The daemon config at /etc/docker/daemon.json must use fuse-overlayfs as the storage driver (required by the VM's nested-container kernel).

Startup sequence (after npm install from update script)

1. Start Docker daemon (see above).
2. docker compose up -d — starts PostGIS and Mailpit.
3. npx prisma migrate deploy — applies pending migrations.
4. npm run dev — starts the Next.js dev server on port 3000.

Environment

• .env is created from .env.example; set AUTH_SECRET (e.g. openssl rand -base64 32). DATABASE_URL defaults to the docker-compose PostGIS.
• No external API keys are required for basic development. MapTiler key is optional (OSM/OpenTopoMap fallback works without it).

Lint / Test / Build

Standard commands per package.json scripts — see the npm scripts table in the main section above. All three (npm run lint, npm run test, npm run build) should pass cleanly on a fresh setup.

E2E tests (Playwright)

Require Chromium: npm run playwright:install (or npx playwright install chromium --with-deps). PostGIS must be running and migrated. Playwright auto-starts next dev as the web server.