Skip to content

AGENTS.md

Latest commit

 

History

History
39 lines (34 loc) · 2.13 KB

AGENTS.md

File metadata and controls

39 lines (34 loc) · 2.13 KB
Raw

Repository Guidelines

Project Structure & Module Organization

  • src/pages: Next.js Pages Router entry points and API routes in src/pages/api.
  • src/components: Reusable React UI components.
  • src/services: Business logic and KV/Nchan integrations.
  • src/nchan: Nchan configuration and pub/sub helpers.
  • src/utils: Shared utilities.
  • src/tests: Jest unit/integration tests and test utilities.
  • public: Static assets and standalone HTML pages (for example public/leaderboard.html).

Build, Test, and Development Commands

  • yarn dev: Start Next.js dev server (Turbo).
  • yarn build: Production build.
  • yarn start: Run the built app.
  • yarn lint: Type-check and lint the codebase.
  • yarn lint:smells: Run oxlint and duplication checks.
  • yarn prettify: Format src and public files.
  • yarn test: Jest suite (src/tests/jest.config.js).

Coding Style & Naming Conventions

  • Language: TypeScript with Next.js pages router.
  • Formatting: no semicolons, trailing commas in ES5.
  • Always run yarn prettify when work complete. always.
  • Linting: ESLint plus TypeScript checks via yarn lint.
  • Naming: Prefer descriptive component and test names; API route tests use api.*.test.ts (see src/tests).
  • Portability: Use globalThis instead of window, global, or self.

Testing Guidelines

  • Frameworks: Jest for unit/integration tests and Playwright for E2E.
  • Location: Add tests under src/tests and colocate fixtures there.
  • Naming: *.test.ts or *.test.tsx (for example src/tests/TableService.test.ts).
  • Always run: yarn test and yarn lint after changes.
  • Cloud-based LLM agents must not run yarn e2e/Playwright in this repo. E2E startup depends on server-side DB/KV credentials that are not available in hosted agent environments.
  • For cloud agents, validate changes with yarn test and yarn lint only, unless a human explicitly provides credentials and requests E2E.

Configuration & Ops Notes

  • KV and Nchan are required for full functionality; local tests may use mocks.
  • Static pages in public are deployed alongside Next.js pages; update both when touching the lobby/leaderboard flows.