# Coder Development Guidelines

@.claude/docs/WORKFLOWS.md
@.cursorrules
@README.md
@package.json

## 🚀 Essential Commands

| Task              | Command                  | Notes                            |
|-------------------|--------------------------|----------------------------------|
| **Development**   | `./scripts/develop.sh`   | ⚠️ Don't use manual build        |
| **Build**         | `make build`             | Fat binaries (includes server)   |
| **Build Slim**    | `make build-slim`        | Slim binaries                    |
| **Test**          | `make test`              | Full test suite                  |
| **Test Single**   | `make test RUN=TestName` | Faster than full suite           |
| **Test Postgres** | `make test-postgres`     | Run tests with Postgres database |
| **Test Race**     | `make test-race`         | Run tests with Go race detector  |
| **Lint**          | `make lint`              | Always run after changes         |
| **Generate**      | `make gen`               | After database changes           |
| **Format**        | `make fmt`               | Auto-format code                 |
| **Clean**         | `make clean`             | Clean build artifacts            |

### Frontend Commands (site directory)

- `pnpm build` - Build frontend
- `pnpm dev` - Run development server
- `pnpm check` - Run code checks
- `pnpm format` - Format frontend code
- `pnpm lint` - Lint frontend code
- `pnpm test` - Run frontend tests

### Documentation Commands

- `pnpm run format-docs` - Format markdown tables in docs
- `pnpm run lint-docs` - Lint and fix markdown files
- `pnpm run storybook` - Run Storybook (from site directory)

## 🔧 Critical Patterns

### Database Changes (ALWAYS FOLLOW)

1. Modify `coderd/database/queries/*.sql` files
2. Run `make gen`
3. If audit errors: update `enterprise/audit/table.go`
4. Run `make gen` again

### LSP Navigation (USE FIRST)

#### Go LSP (for backend code)

- **Find definitions**: `mcp__go-language-server__definition symbolName`
- **Find references**: `mcp__go-language-server__references symbolName`
- **Get type info**: `mcp__go-language-server__hover filePath line column`
- **Rename symbol**: `mcp__go-language-server__rename_symbol filePath line column newName`

#### TypeScript LSP (for frontend code in site/)

- **Find definitions**: `mcp__typescript-language-server__definition symbolName`
- **Find references**: `mcp__typescript-language-server__references symbolName`
- **Get type info**: `mcp__typescript-language-server__hover filePath line column`
- **Rename symbol**: `mcp__typescript-language-server__rename_symbol filePath line column newName`

### OAuth2 Error Handling

```go
// OAuth2-compliant error responses
writeOAuth2Error(ctx, rw, http.StatusBadRequest, "invalid_grant", "description")
```

### Authorization Context

```go
// Public endpoints needing system access
app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)

// Authenticated endpoints with user context
app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
```

## 📋 Quick Reference

### Full workflows available in imported WORKFLOWS.md

### New Feature Checklist

- [ ] Run `git pull` to ensure latest code
- [ ] Check if feature touches database - you'll need migrations
- [ ] Check if feature touches audit logs - update `enterprise/audit/table.go`

## 🏗️ Architecture

- **coderd**: Main API service
- **provisionerd**: Infrastructure provisioning
- **Agents**: Workspace services (SSH, port forwarding)
- **Database**: PostgreSQL with `dbauthz` authorization

## 🧪 Testing

### Race Condition Prevention

- Use unique identifiers: `fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())`
- Never use hardcoded names in concurrent tests

### OAuth2 Testing

- Full suite: `./scripts/oauth2/test-mcp-oauth2.sh`
- Manual testing: `./scripts/oauth2/test-manual-flow.sh`

### Timing Issues

NEVER use `time.Sleep` to mitigate timing issues. If an issue
seems like it should use `time.Sleep`, read through https://github.com/coder/quartz and specifically the [README](https://github.com/coder/quartz/blob/main/README.md) to better understand how to handle timing issues.

## 🎯 Code Style

### Detailed guidelines in imported WORKFLOWS.md

- Follow [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)
- Commit format: `type(scope): message`

## 📚 Detailed Development Guides

@.claude/docs/OAUTH2.md
@.claude/docs/TESTING.md
@.claude/docs/TROUBLESHOOTING.md
@.claude/docs/DATABASE.md

## 🚨 Common Pitfalls

1. **Audit table errors** → Update `enterprise/audit/table.go`
2. **OAuth2 errors** → Return RFC-compliant format
3. **Race conditions** → Use unique test identifiers
4. **Missing newlines** → Ensure files end with newline

---

*This file stays lean and actionable. Detailed workflows and explanations are imported automatically.*