metabuilder/docs/development/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• frontends/nextjs/: primary Next.js app (source in src/, E2E in e2e/, local helper scripts in scripts/).
• packages/: JSON-driven component packages (seed/*.json, optional static_content/, and tests/ for schema/structure checks).
• dbal/: database abstraction layer (TypeScript library in dbal/development/; additional tooling/docs under dbal/).
• prisma/: Prisma schema and migrations (schema.prisma, migrations/).
• config/: shared config (Playwright/Vite/TS/ESLint) symlinked into frontends/nextjs/.
• tools/: repo utilities (quality checks, workflow helpers, code analysis).

Build, Test, and Development Commands

Run app workflows from frontends/nextjs/:

• npm install (or npm ci): install dependencies.
• npm run dev: start local dev server.
• npm run build / npm run start: production build and serve.
• npm run lint / npm run lint:fix: lint (and auto-fix where safe).
• npm run typecheck: TypeScript checking (tsc --noEmit).
• npm run test:unit / npm run test:coverage: Vitest unit tests (coverage output to frontends/nextjs/coverage/).
• npm run test:e2e: Playwright E2E tests.
• npm run db:generate / npm run db:push / npm run db:migrate: Prisma client + schema/migrations.

DBAL library workflows live in dbal/development/ (npm run build, npm run test:unit).

Coding Style & Naming Conventions

• TypeScript + ESM. Prefer @/… imports inside frontends/nextjs/src/.
• React components: PascalCase.tsx; hooks: useThing.ts; tests: *.test.ts(x).
• UI: use Material UI (@mui/*) and SCSS/modules as needed; do not introduce Radix UI or Tailwind (see UI_STANDARDS.md).
• Package metadata: keep packages/*/seed/metadata.json packageId in snake_case and versions semver (e.g. 1.2.3).

Testing Guidelines

• Unit: Vitest (frontends/nextjs/src/**/*.test.ts(x) and packages/*/tests/*.test.ts).
• E2E: Playwright (frontends/nextjs/e2e/).
• Add/adjust tests with behavior changes; keep tests deterministic (no network, stable clocks/IDs).

Commit & Pull Request Guidelines

• Commits generally follow Conventional Commits (examples in history: feat: …, fix: …, docs: …, refactor: …, chore: …).
• PRs should include: what/why, linked issue (if any), screenshots for UI changes, and notes on DB/schema changes.
• Before opening a PR, run npm run lint, npm run typecheck, and the relevant tests.

Agent-Specific Notes

• Check for scoped rules in nested AGENTS.md files (e.g., dbal/docs/AGENTS.md) before editing those areas.
• Keep changes focused, avoid dependency churn, and follow existing patterns/config in config/ and frontends/nextjs/.