# Development Guide

## Prerequisites

- [Bun](https://bun.sh/) v1.3+

## Setup

```bash
bun install
```

## Project Structure

```
sitebase/
├── packages/
│   ├── core/       # Export library (@sitebase/core)
│   ├── cli/        # CLI tool (@sitebase/cli)
│   └── web/        # Web management UI (@sitebase/web)
├── scripts/        # Utility scripts
├── biome.json      # Linter/formatter config
└── tsconfig.json   # TypeScript config
```

## Commands

### Verification

Run these before committing:

```bash
# Run all checks (typecheck + lint)
bun run check

# Individual checks
bun run typecheck      # TypeScript type checking
bun run lint:check     # Biome lint (no auto-fix)
bun run format:check   # Biome format (no auto-fix)
```

### Fixing Issues

```bash
bun run lint      # Auto-fix lint issues
bun run format    # Auto-fix formatting
```

## Code Style

Enforced by [Biome](https://biomejs.dev/):

- **Indentation**: Tabs
- **Quotes**: Double quotes
- **Imports**: Auto-organized on save (via `biome.json` assist)

TypeScript is configured with strict mode and additional safety flags:
- `noUncheckedIndexedAccess` - Array/object index access may be undefined
- `noFallthroughCasesInSwitch` - Require break/return in switch cases
- `noImplicitOverride` - Require `override` keyword

## Packages

### @sitebase/core

Core export functionality. No runtime dependencies except Handlebars.

Key files:
- `src/types.ts` - Type definitions
- `src/export.ts` - Export logic
- `src/config.ts` - Config file loading
- `src/templates.ts` - Handlebars helpers, slugify
- `src/atproto.ts` - ATProto fetch utilities

### @sitebase/cli

CLI wrapper around core. Uses Commander for argument parsing.

```bash
cd packages/cli
bun run src/index.ts export --config ../path/to/config.ts
```

### @sitebase/web

Hono-based web server with ATProto OAuth.

```bash
cd packages/web
bun run dev
```

See `packages/web/CLAUDE.md` for web-specific details.

## ATProto Integration

The project uses ATProto lexicons:
- `site.standard.publication` - Blog/publication metadata
- `site.standard.document` - Individual documents/posts

Documents are fetched from any PDS via:
1. Parse AT URI to extract DID
2. Resolve DID to PDS endpoint via `plc.directory`
3. Fetch records via `com.atproto.repo.getRecord` / `listRecords`

## Adding Features

### New Handlebars Helper

Add to `packages/core/src/templates.ts` in `registerHelpers()`:

```typescript
hbs.registerHelper("myHelper", (arg1: unknown) => {
  // Return transformed value
  return String(arg1).toUpperCase();
});
```

### New Export Option

1. Add type to `packages/core/src/types.ts` in `ExportOptions` and `ExportTarget`
2. Handle in `packages/core/src/export.ts` in `exportPublication()`
3. Update `packages/core/src/config.ts` if it affects config loading
4. Document in README.md

## Workspace Dependencies

Use workspace protocol for internal deps:

```json
{
  "dependencies": {
    "@sitebase/core": "workspace:*"
  }
}
```