fullstack-starter/AGENTS.md

# AGENTS.md - AI Coding Agent Guidelines

Guidelines for AI agents working in this Bun monorepo.

## Project Overview

> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**

- **Monorepo**: Bun workspaces + Turborepo orchestration
- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
- **Apps**:
  - `apps/server` - TanStack Start fullstack web app (see `apps/server/AGENTS.md`)
  - `apps/desktop` - Electron desktop shell, sidecar server pattern (see `apps/desktop/AGENTS.md`)
- **Packages**: `packages/tsconfig` (shared TS configs)

## Build / Lint / Test Commands

### Root Commands (via Turbo)
```bash
bun run dev              # Start all apps in dev mode
bun run build            # Build all apps
bun run compile          # Compile server to standalone binary (current platform)
bun run compile:darwin   # Compile server for macOS (arm64 + x64)
bun run compile:linux    # Compile server for Linux (x64 + arm64)
bun run compile:windows  # Compile server for Windows x64
bun run dist             # Package desktop distributable (current platform)
bun run dist:linux       # Package desktop for Linux (x64 + arm64)
bun run dist:mac         # Package desktop for macOS (arm64 + x64)
bun run dist:win         # Package desktop for Windows x64
bun run fix              # Lint + format (Biome auto-fix)
bun run typecheck        # TypeScript check across monorepo
```

### Server App (`apps/server`)
```bash
bun run dev                   # Vite dev server (localhost:3000)
bun run build                 # Production build -> .output/
bun run compile               # Compile to standalone binary (current platform)
bun run compile:darwin        # Compile for macOS (arm64 + x64)
bun run compile:darwin:arm64  # Compile for macOS arm64
bun run compile:darwin:x64    # Compile for macOS x64
bun run compile:linux         # Compile for Linux (x64 + arm64)
bun run compile:linux:arm64   # Compile for Linux arm64
bun run compile:linux:x64     # Compile for Linux x64
bun run compile:windows       # Compile for Windows (default: x64)
bun run compile:windows:x64   # Compile for Windows x64
bun run fix                   # Biome auto-fix
bun run typecheck             # TypeScript check

# Database (Drizzle)
bun run db:generate           # Generate migrations from schema
bun run db:migrate            # Run migrations
bun run db:push               # Push schema (dev only)
bun run db:studio             # Open Drizzle Studio
```

### Desktop App (`apps/desktop`)
```bash
bun run dev                   # electron-vite dev mode (requires server dev running)
bun run build                 # electron-vite build (main + preload)
bun run dist                  # Build + package for current platform
bun run dist:linux            # Build + package for Linux (x64 + arm64)
bun run dist:linux:x64        # Build + package for Linux x64
bun run dist:linux:arm64      # Build + package for Linux arm64
bun run dist:mac              # Build + package for macOS (arm64 + x64)
bun run dist:mac:arm64        # Build + package for macOS arm64
bun run dist:mac:x64          # Build + package for macOS x64
bun run dist:win              # Build + package for Windows x64
bun run fix                   # Biome auto-fix
bun run typecheck             # TypeScript check
```

### Testing
No test framework configured yet. When adding tests:
```bash
bun test path/to/test.ts              # Run single test file
bun test -t "pattern"                 # Run tests matching pattern
```

## Code Style (TypeScript)

### Formatting (Biome)
- **Indent**: 2 spaces | **Line endings**: LF
- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
- **Arrow parentheses**: Always `(x) => x`

### Imports
Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)

```typescript
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
import { db } from '@/server/db'
import type { ReactNode } from 'react'
```

### TypeScript Strictness
- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true`
- Use `@/*` path aliases (maps to `src/*`)

### Naming Conventions
| Type | Convention | Example |
|------|------------|---------|
| Files (utils) | kebab-case | `auth-utils.ts` |
| Files (components) | PascalCase | `UserProfile.tsx` |
| Components | PascalCase arrow | `const Button = () => {}` |
| Functions | camelCase | `getUserById` |
| Constants | UPPER_SNAKE | `MAX_RETRIES` |
| Types/Interfaces | PascalCase | `UserProfile` |

### React Patterns
- Components: arrow functions (enforced by Biome)
- Routes: TanStack Router file conventions (`export const Route = createFileRoute(...)`)
- Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())`
- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)

### Error Handling
- Use `try-catch` for async operations; throw descriptive errors
- ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`)
- Never use empty catch blocks

## Database (Drizzle ORM v1 beta + postgres-js)

- **ORM**: Drizzle ORM `1.0.0-beta` (RQBv2)
- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts` (contains schema info, so `drizzle()` only needs `{ relations }`)
- **Query style**: RQBv2 object syntax (`orderBy: { createdAt: 'desc' }`, `where: { id: 1 }`)

```typescript
export const myTable = pgTable('my_table', {
  id: uuid().primaryKey().default(sql`uuidv7()`),
  name: text().notNull(),
  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
})
```

## Environment Variables

- Use `@t3-oss/env-core` with Zod validation in `src/env.ts`
- Server vars: no prefix | Client vars: `VITE_` prefix required
- Never commit `.env` files

## Dependency Management

- All versions centralized in root `package.json` `catalog` field
- Workspace packages use `"catalog:"` — never hardcode versions
- Internal packages use `"workspace:*"` references

## Development Principles

> **These principles apply to ALL code changes. Agents MUST follow them on every task.**

1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks "just in case".
2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart. This includes updating code snippets in docs when imports, APIs, or patterns change.
3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns in the same codebase.

## Critical Rules

**DO:**
- Run `bun run fix` before committing
- Use `@/*` path aliases (not relative imports)
- Include `createdAt`/`updatedAt` on all tables
- Use `catalog:` for dependency versions
- Update `AGENTS.md` and other docs whenever code patterns change

**DON'T:**
- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
- Edit `src/routeTree.gen.ts` (auto-generated)
- Use `as any`, `@ts-ignore`, `@ts-expect-error`
- Commit `.env` files
- Use empty catch blocks `catch(e) {}`
- Hardcode dependency versions in workspace packages
- Leave docs out of sync with code changes

## Git Workflow

1. Make changes following style guide
2. `bun run fix` - auto-format and lint
3. `bun run typecheck` - verify types
4. `bun run dev` - test locally
5. Commit with descriptive message

## Directory Structure

```
.
├── apps/
│   ├── server/           # TanStack Start fullstack app
│   │   ├── src/
│   │   │   ├── client/   # ORPC client + TanStack Query utils
│   │   │   ├── components/
│   │   │   ├── routes/   # File-based routing
│   │   │   └── server/   # API layer + database
│   │   │       ├── api/  # ORPC contracts, routers, middlewares
│   │   │       └── db/   # Drizzle schema
│   │   └── AGENTS.md
│   └── desktop/          # Electron desktop shell
│       ├── src/
│       │   ├── main/
│       │   │   └── index.ts       # Main process entry
│       │   └── preload/
│       │       └── index.ts       # Preload script
│       ├── electron.vite.config.ts
│       ├── electron-builder.yml   # Packaging config
│       └── AGENTS.md
├── packages/
│   └── tsconfig/         # Shared TS configs
├── biome.json            # Linting/formatting config
├── turbo.json            # Turbo task orchestration
└── package.json          # Workspace root + dependency catalog
```

## See Also

- `apps/server/AGENTS.md` - Detailed TanStack Start / ORPC patterns
- `apps/desktop/AGENTS.md` - Electron desktop development guide