stripstream/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/app/: Next.js App Router pages, layouts, API routes, and server actions.
• src/components/: UI and feature components (home/, reader/, layout/, ui/).
• src/lib/: shared services (Komga/API access), auth, logger, utilities.
• src/hooks/, src/contexts/, src/types/, src/constants/: reusable runtime logic and typing.
• src/i18n/messages/{en,fr}/: translation dictionaries.
• prisma/: database schema and Prisma artifacts.
• public/: static files and PWA assets.
• scripts/: maintenance scripts (DB init, admin password reset, icon generation).
• docs/ and devbook.md: implementation notes and architecture decisions.

Build, Test, and Development Commands

Use pnpm (lockfile and packageManager are configured for it).

• pnpm dev: start local dev server.
• pnpm build: create production build.
• pnpm start: run production server.
• pnpm lint: run ESLint across the repo.
• pnpm typecheck or pnpm -s tsc --noEmit: strict TypeScript checks.
• pnpm init-db: initialize database data.
• pnpm reset-admin-password: reset admin credentials.

Coding Style & Naming Conventions

• Language: TypeScript (.ts/.tsx) with React function components.
• Architecture priority: server-first. Default to React Server Components (RSC) for pages and feature composition.
• Data mutations: prefer Server Actions (src/app/actions/) over client-side fetch patterns when possible.
• Client components ("use client"): use only for browser-only concerns (event handlers, local UI state, effects, DOM APIs).
• Data fetching: do it on the server first (page.tsx, server components, services in src/lib/services), then pass serialized props down.
• Indentation: 2 spaces; keep imports grouped and sorted logically.
• Components/hooks/services: PascalCase for components, camelCase for hooks/functions, *.service.ts for service modules.
• Styling: Tailwind utility classes; prefer existing src/components/ui primitives before creating new ones.
• Quality gates: ESLint (eslint.config.mjs) + TypeScript must pass before merge.

Testing Guidelines

• No dedicated unit test framework is currently configured.
• Minimum validation for each change: pnpm lint and pnpm typecheck.
• For UI changes, perform a quick manual smoke test on affected routes (home, libraries, series, reader) and both themes.

Commit & Pull Request Guidelines

• Follow Conventional Commit style seen in history: fix: ..., refactor: ..., feat: ....
• Keep subjects imperative and specific (e.g., fix: reduce header/home spacing overlap).
• PRs should include:
  • short problem/solution summary,
  • linked issue (if any),
  • screenshots or short video for UI updates,
  • verification steps/commands run.

Security & Configuration Tips

• Never commit secrets; use .env based on .env.example.
• Validate Komga and auth-related config through settings flows before merging.
• Prefer server-side data fetching/services for sensitive operations.