domainstack.io AGENTS.md

Repository Guidelines

Pre-Commit Checklist

CRITICAL: Before declaring victory on any task and before committing to git, the following four commands must pass with NO WARNINGS:

1. pnpm lint — Must pass with zero warnings
2. pnpm fmt:check — Must pass with zero warnings
3. pnpm check-types — Must pass with zero warnings
4. pnpm test — Must pass with zero warnings

Do not proceed with commits until all four checks are clean.

Commands

Development

• pnpm dev — Start Next.js dev server at http://localhost:3000
• pnpm build — Compile production bundle
• pnpm check-types — Run tsc --noEmit for type diagnostics

Linting & Formatting

• pnpm lint — Run oxlint lint
• pnpm fmt — Apply oxfmt formatting

Testing

• pnpm test — Run all tests once
• pnpm test path/to/file.test.ts — Run a single test file
• pnpm test -t "test name" — Run tests matching a pattern
• pnpm test:coverage — Run tests with coverage report

Database

• pnpm db:generate — Generate Drizzle migrations
• pnpm db:push — Push schema to database
• pnpm db:migrate — Apply migrations
• pnpm db:studio — Open Drizzle Studio

Code Style

General

• TypeScript only, strict enabled
• 2-space indentation (oxfmt enforces)
• Prefer small, pure modules
• Node.js >= 24 required

Naming Conventions

• Files/folders: kebab-case (user-settings.ts)
• React components: PascalCase exports (UserSettings)
• Helpers/hooks: camelCase named exports (useUserSettings)

Imports

• Use @/... path aliases for app-specific imports
• Import shared UI components from @domainstack/ui/* (e.g., @domainstack/ui/button)
• oxfmt auto-organizes imports on save
• Client components must start with "use client"

Types

• Shared domain types in @domainstack/types package
• Enum const arrays (primitives) in @domainstack/constants (Drizzle pgEnums derive from these)
• Do NOT use Zod for simple enums or internal database types
• Import types from @domainstack/types