florian42
AGENTS.md

Repository Guidelines

Project Structure & Modules

  • main.tsx: React SSR HTTP handler (default export authHandler); session + bookmark logic and TIDAL API integration.
  • deno.json: Deno config (TS, JSX, lint rules, Val.town types).
  • test-artist.ts: Ad‑hoc script to inspect TIDAL artist relationships.

Build, Run, and Test

  • Format: deno fmt — apply repository formatting.
  • Lint: deno lint — run configured lint rules.
  • Type check: deno check main.tsx — validate types without running.
  • Ad‑hoc test: deno run --allow-net --allow-env test-artist.ts — exercises artist fetching (requires TIDAL env vars).
  • Val.town (optional): vt dev to run locally and vt deploy to publish if you use the Val.town CLI.

Coding Style & Conventions

  • JSX pragma: start React files with /** @jsxImportSource https://esm.sh/react */.
  • Imports: prefer ESM (npm: specifiers and HTTPS URLs). No Node require.
  • Naming: PascalCase for React components, camelCase for functions/variables, .tsx for JSX modules.
  • Formatting: accept deno fmt defaults; do not hand‑tweak style.

Testing Guidelines

  • Prefer Deno’s built‑in tests; name files *.test.ts or *.test.tsx.
  • Keep tests deterministic; mock network calls. Example: deno test --allow-none for pure unit tests.
  • For coverage (optional): deno test --coverage=cov && deno coverage cov.

Commit & PR Guidelines

  • Commits: use Conventional Commits (e.g., feat: add bookmark deletion, fix: handle missing artist rel).
  • PRs: include summary, rationale, affected routes, and any schema changes. Link related issues. Add screenshots of UI states when applicable.
  • Keep PRs small and focused; include deno fmt and deno lint clean runs.

Security & Config

  • Required env vars: TIDAL_CLIENT_ID, TIDAL_CLIENT_SECRET, MUSICBOX_PASSWORD.
  • Do not commit secrets. Use the minimal permissions flags (--allow-env, --allow-net) when running scripts.

Architecture Overview

  • Runtime: Deno; Platform: Val.town. Server responds by rendering React to HTML via renderToString.
  • Storage: Val.town SQLite via https://esm.town/v/std/sqlite with sessions and bookmarks tables.
  • HTTP: default export handles routes (/, /login, /logout, /bookmark, /bookmark/delete).