AGENTS.md

Quick reference for AI agents performing quality assurance tasks in this monorepo.

Quick Commands

# Quality gates (run ALL before committing)
bun run typecheck:all    # Type checking
bun run test             # All tests (Vitest)
bun run lint             # ESLint
bun run format:check     # Prettier

# Fix issues
bun run lint:fix         # Auto-fix lint
bun run format           # Auto-format

# Single file/package testing
npx vitest run <path>    # Run specific test
bun run test:watch       # Watch mode
bun run test:sqlite      # SQLite tests only

⚠️ NEVER use

bun test

— incompatible with Vitest APIs (

vi.hoisted

vi.mocked

, jsdom).

Quality Gate Checklist

Before any commit:

Gate	Command	Requirement
Types	`bun run typecheck:all`	Zero errors
Tests	`bun run test`	All pass
Lint	`bun run lint`	No errors
Format	`bun run format:check`	Clean

All four must pass. No exceptions.

Testing

Framework: Vitest

Node environment default,
```
jsdom
```
for browser simulation
Globals enabled (
```
describe
```
,
```
it
```
,
```
expect
```
without imports)

Coverage Targets

Category	Minimum
API routes	80%
Business logic	90%
Utilities	70%
UI components	60%

Must Test

Happy path for all public APIs
Error responses: 400, 401, 403, 404, 500
Authentication/authorization checks
Zod validation (valid and invalid inputs)
Edge cases: null, empty, boundary values

Skip Testing

Private functions / implementation details
Third-party library internals
Trivial getters/setters

Hono Route Testing Pattern

const { default: routes } = await import("../../routes/api-keys")
const app = new Hono()
app.onError(testErrorHandler)
app.route("/api/api-keys", routes)

const response = await app.request("/api/api-keys/ep_123/keys")
expect(response.status).toBe(200)

Mocking Pattern

vi.mock("../../lib/db", () => ({
  getDb: vi.fn(() => mockDb),
}))

beforeEach(() => vi.clearAllMocks())

Type Checking

Rules

No
```
any
```
without justification comment
Prefer
```
unknown
```
+ type guards over
```
any
```
No
```
@ts-ignore
```
— use
```
@ts-expect-error
```
with linked issue if unavoidable
No
```
!
```
non-null assertions — handle nullability properly

Common Fixes

// Bad: any
const data: any = await fetch(url)

// Good: unknown + guard
const data: unknown = await fetch(url)
if (isUser(data)) {
  /* typed */
}

// Bad: assertion
const user = data as User

// Good: validation
const user = UserSchema.parse(data)

Code Style

Prettier Config

No semicolons
Double quotes
2-space indentation
Trailing commas (ES5)

Naming

Type	Convention	Example
Variables	camelCase	`userId`
Constants	UPPER_SNAKE	`MAX_RETRIES`
Functions	camelCase	`getUserById`
Types	PascalCase	`UserWithRole`
Files	kebab-case	`user-service.ts`
Components	PascalCase	`UserProfile.tsx`

Unused Variables

Prefix with underscore:

function handler(_req: Request, res: Response) {
  // _req intentionally unused
}

Package-Specific Commands

# Database
cd packages/db && bun run migrate

# Gateway binary
cd packages/gateway && bun run build:binary

# Desktop app
cd apps/desktop && bun run tauri:dev

# API server
cd apps/api && bun run dev

# Platform
cd apps/platform && bun run dev

Workflow

Plan — Break task into steps
Implement — Code incrementally
Test — Write/run tests
Review — Use code-reviewer agent
Verify — Run all quality gates
Commit — Atomic commits, conventional format

Commit Format

<type>(<scope>): <subject>

Types: feat, fix, refactor, test, docs, chore
Scope: package or app name

Examples:

```
feat(gateway): add trace collection
```
```
fix(api): handle null user ID
```
```
test(db): add migration tests
```

When Stuck

Type Errors

Read the full error message
Check if type definitions exist (
```
@types/*
```
)
Verify import paths
Check
```
tsconfig.json
```
includes

Test Failures

Run single test:
```
npx vitest run <file>
```
Check mock setup (cleared in
```
beforeEach
```
?)
Verify test isolation (no shared state)
Check async/await handling

Lint Errors

Run
```
bun run lint:fix
```
first
Check
```
.eslintrc
```
for rule config
Unused imports → remove them
Console calls → use structured logger (see Logging section)

Logging

Use the structured logger from

@athreei/shared

instead of

console.log/error/warn

import { createLogger, honoLogger } from "@athreei/shared"

// Create service logger
const logger = createLogger({
  service: "api",
  level: process.env.LOG_LEVEL || "info",
  pretty: process.env.NODE_ENV !== "production",
})

// Use structured logging
logger.info("Operation completed", { userId, duration })
logger.warn("Rate limit approaching", { current: 95, limit: 100 })
logger.error("Database error", { error, query })

// For Hono apps, use middleware
app.use("*", honoLogger({ logger }))

// Access request-scoped logger in routes
const log = c.get("logger")
log.info("Processing request") // Includes requestId

When to use each level

Level	Use for
`debug`	Detailed debugging (disabled in production)
`info`	Normal operations, startup messages
`warn`	Recoverable issues, deprecation notices
`error`	Errors requiring attention

Security Checklist

Input validated with Zod at boundaries
Authorization checked before data access
No secrets in code or logs
No SQL injection (use Drizzle ORM)
No XSS (sanitize user content)

AGENTS.md

Quick reference for AI agents performing quality assurance tasks in this monorepo.

Quick Commands

# Quality gates (run ALL before committing)
bun run typecheck:all    # Type checking
bun run test             # All tests (Vitest)
bun run lint             # ESLint
bun run format:check     # Prettier

# Fix issues
bun run lint:fix         # Auto-fix lint
bun run format           # Auto-format

# Single file/package testing
npx vitest run <path>    # Run specific test
bun run test:watch       # Watch mode
bun run test:sqlite      # SQLite tests only

⚠️ NEVER use

bun test

— incompatible with Vitest APIs (

vi.hoisted

vi.mocked

, jsdom).

Quality Gate Checklist

Before any commit:

Gate	Command	Requirement
Types	`bun run typecheck:all`	Zero errors
Tests	`bun run test`	All pass
Lint	`bun run lint`	No errors
Format	`bun run format:check`	Clean

All four must pass. No exceptions.

Testing

Framework: Vitest

Node environment default,
```
jsdom
```
for browser simulation
Globals enabled (
```
describe
```
,
```
it
```
,
```
expect
```
without imports)

Coverage Targets

Category	Minimum
API routes	80%
Business logic	90%
Utilities	70%
UI components	60%

Must Test

Happy path for all public APIs
Error responses: 400, 401, 403, 404, 500
Authentication/authorization checks
Zod validation (valid and invalid inputs)
Edge cases: null, empty, boundary values

Skip Testing

Private functions / implementation details
Third-party library internals
Trivial getters/setters

Hono Route Testing Pattern

const { default: routes } = await import("../../routes/api-keys")
const app = new Hono()
app.onError(testErrorHandler)
app.route("/api/api-keys", routes)

const response = await app.request("/api/api-keys/ep_123/keys")
expect(response.status).toBe(200)

Mocking Pattern

vi.mock("../../lib/db", () => ({
  getDb: vi.fn(() => mockDb),
}))

beforeEach(() => vi.clearAllMocks())

Type Checking

Rules

No
```
any
```
without justification comment
Prefer
```
unknown
```
+ type guards over
```
any
```
No
```
@ts-ignore
```
— use
```
@ts-expect-error
```
with linked issue if unavoidable
No
```
!
```
non-null assertions — handle nullability properly

Common Fixes

// Bad: any
const data: any = await fetch(url)

// Good: unknown + guard
const data: unknown = await fetch(url)
if (isUser(data)) {
  /* typed */
}

// Bad: assertion
const user = data as User

// Good: validation
const user = UserSchema.parse(data)

Code Style

Prettier Config

No semicolons
Double quotes
2-space indentation
Trailing commas (ES5)

Naming

Type	Convention	Example
Variables	camelCase	`userId`
Constants	UPPER_SNAKE	`MAX_RETRIES`
Functions	camelCase	`getUserById`
Types	PascalCase	`UserWithRole`
Files	kebab-case	`user-service.ts`
Components	PascalCase	`UserProfile.tsx`

Unused Variables

Prefix with underscore:

function handler(_req: Request, res: Response) {
  // _req intentionally unused
}

Package-Specific Commands

# Database
cd packages/db && bun run migrate

# Gateway binary
cd packages/gateway && bun run build:binary

# Desktop app
cd apps/desktop && bun run tauri:dev

# API server
cd apps/api && bun run dev

# Platform
cd apps/platform && bun run dev

Workflow

Plan — Break task into steps
Implement — Code incrementally
Test — Write/run tests
Review — Use code-reviewer agent
Verify — Run all quality gates
Commit — Atomic commits, conventional format

Commit Format

<type>(<scope>): <subject>

Types: feat, fix, refactor, test, docs, chore
Scope: package or app name

Examples:

```
feat(gateway): add trace collection
```
```
fix(api): handle null user ID
```
```
test(db): add migration tests
```

When Stuck

Type Errors

Read the full error message
Check if type definitions exist (
```
@types/*
```
)
Verify import paths
Check
```
tsconfig.json
```
includes

Test Failures

Run single test:
```
npx vitest run <file>
```
Check mock setup (cleared in
```
beforeEach
```
?)
Verify test isolation (no shared state)
Check async/await handling

Lint Errors

Run
```
bun run lint:fix
```
first
Check
```
.eslintrc
```
for rule config
Unused imports → remove them
Console calls → use structured logger (see Logging section)

Logging

Use the structured logger from

@athreei/shared

instead of

console.log/error/warn

import { createLogger, honoLogger } from "@athreei/shared"

// Create service logger
const logger = createLogger({
  service: "api",
  level: process.env.LOG_LEVEL || "info",
  pretty: process.env.NODE_ENV !== "production",
})

// Use structured logging
logger.info("Operation completed", { userId, duration })
logger.warn("Rate limit approaching", { current: 95, limit: 100 })
logger.error("Database error", { error, query })

// For Hono apps, use middleware
app.use("*", honoLogger({ logger }))

// Access request-scoped logger in routes
const log = c.get("logger")
log.info("Processing request") // Includes requestId

When to use each level

Level	Use for
`debug`	Detailed debugging (disabled in production)
`info`	Normal operations, startup messages
`warn`	Recoverable issues, deprecation notices
`error`	Errors requiring attention

Security Checklist

Input validated with Zod at boundaries
Authorization checked before data access
No secrets in code or logs
No SQL injection (use Drizzle ORM)
No XSS (sanitize user content)

AGENTS.md

Related Skills

Markdown Converter

Nano Banana Pro

1password