158 lines
4.3 KiB
Markdown
158 lines
4.3 KiB
Markdown
# AGENTS.md
|
|
|
|
Guide for agentic coding assistants working in the Officer monorepo.
|
|
|
|
## Quick Start Commands
|
|
|
|
### Development
|
|
|
|
```bash
|
|
bun dev # Dashboard + API server (port 5000)
|
|
bun dev:tracking # Tracking server (port 5001)
|
|
bun dev:experiments # Experiments server
|
|
bun dev:emailer # Emailer workspace
|
|
```
|
|
|
|
### Building & Database
|
|
|
|
```bash
|
|
bun run prebuild # Run prebuild tasks
|
|
bun run build:dashboard # Build dashboard
|
|
bun run build:editor # Build editor (app + extension + runtime)
|
|
bun run build:runtime # Build all runtime scripts
|
|
bun run db:gen && db:push # Generate & push officer_db migrations
|
|
bun run db:gen:stats && db:push:stats # Generate & push statistics_db
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
bun format # Format all files (Prettier, required before commit)
|
|
bun format:check # Check formatting without writing
|
|
bunx tsgo # TypeScript type checking (comprehensive, slow)
|
|
```
|
|
|
|
**Note:** No automated tests configured yet. Always run `bun format` before committing.
|
|
|
|
## Code Style Guide
|
|
|
|
### Imports
|
|
|
|
Order: **types → external → workspace → relative**
|
|
|
|
```ts
|
|
import type { Experiment } from 'types';
|
|
import { useState } from 'react';
|
|
import { useQuery } from '@tanstack/react-query';
|
|
import { useExperiment } from 'hooks/use-experiment';
|
|
import { formatDate } from '../helpers';
|
|
```
|
|
|
|
### TypeScript
|
|
|
|
- Strict mode always - no `any`
|
|
- Prefer `type` over `interface`
|
|
- Colocate prop types with components as named exports
|
|
- Early returns for null/undefined guards
|
|
- Use optional chaining and nullish coalescing: `obj?.prop ?? fallback`
|
|
|
|
### Functions
|
|
|
|
- Arrow functions for simple/one-liners
|
|
- Regular functions for complex multi-line logic
|
|
- Named exports only (never default exports)
|
|
|
|
```ts
|
|
export const formatDate = (ts: number) => new Date(ts).toLocaleDateString();
|
|
export function calculateStats(data: DataPoint[]) {
|
|
/* ... */
|
|
}
|
|
```
|
|
|
|
### React Components
|
|
|
|
- Functional components with named prop types
|
|
- Arrow function syntax
|
|
- No useMemo/useCallback (React 19 compiler handles optimization)
|
|
|
|
```tsx
|
|
type CardProps = { title: string; onClick: () => void };
|
|
export const Card = ({ title, onClick }: CardProps) => <div onClick={onClick}>{title}</div>;
|
|
```
|
|
|
|
### State Management
|
|
|
|
- **Manager pattern** for complex hooks - return object with state + methods
|
|
- **Colocation** - all feature state in one hook
|
|
- **Derived state** - compute in hook, not in components
|
|
|
|
```ts
|
|
export const useExperimentManager = (id: number) => {
|
|
const [exp, setExp] = useState<Experiment | null>(null);
|
|
const isActive = exp?.status === 'running';
|
|
return {
|
|
exp,
|
|
isActive,
|
|
update: (data) => {
|
|
/* ... */
|
|
},
|
|
};
|
|
};
|
|
```
|
|
|
|
### Naming Conventions
|
|
|
|
- **Components**: `PascalCase.tsx` (e.g., `ExperimentCard.tsx`)
|
|
- **Everything else**: `kebab-case.ts` (e.g., `use-experiment.ts`, `format-date.ts`)
|
|
- **Hooks**: `use-*.ts` or `useFeatureName.ts`
|
|
|
|
### Formatting (Prettier)
|
|
|
|
- Semicolons: always
|
|
- Quotes: single (JS/TS), double (JSX)
|
|
- Trailing commas: all
|
|
- Indent: 2 spaces
|
|
- Line width: 120 characters
|
|
|
|
### Error Handling
|
|
|
|
- Use try/catch for async operations
|
|
- Include context in error messages (IDs, resource names)
|
|
- Log with `console.error` and re-throw appropriately
|
|
- Handle database connection errors explicitly
|
|
|
|
### Async/Await
|
|
|
|
- Always use async/await (never .then() chains)
|
|
- Minimize nesting
|
|
|
|
## Project Structure
|
|
|
|
- `src/apps/dashboard/` - Admin UI (React 19)
|
|
- `src/apps/editor/` - Visual editor
|
|
- `src/servers/api/` - REST API (Hono, port 5000)
|
|
- `src/servers/tracking/` - Event collection (port 5001)
|
|
- `src/databases/` - PostgreSQL schemas (3 DBs: officer_db, statistics_db, ephemeral_db)
|
|
- `src/workspaces/` - Shared: components, hooks, helpers, types
|
|
|
|
## Path Aliases
|
|
|
|
- `@/` → `src/apps/dashboard/`
|
|
- `@@/` → `src/servers/`
|
|
|
|
## Tech Stack
|
|
|
|
- **Runtime**: Bun
|
|
- **Language**: TypeScript 5.9 (strict mode)
|
|
- **Frontend**: React 19, React Router, React Query, Tailwind CSS, shadcn/ui
|
|
- **Backend**: Hono, PostgreSQL, Drizzle ORM
|
|
- **Build**: Vite
|
|
|
|
## General Guidelines
|
|
|
|
- **Database-first** approach - schema → API → UI
|
|
- **Self-documenting code** - clear naming, minimal comments
|
|
- **Explicit over implicit** - no magic
|
|
- **Workspace dependencies** - use `workspace:*`
|
|
- **Environment variables** - use `.env`, access directly in code
|