seth.computer
this repo has no description
1# Development Guide
2
3## Prerequisites
4
5- [Bun](https://bun.sh/) v1.3+
6
7## Setup
8
9```bash
10bun install
11```
12
13## Project Structure
14
15```
16sitebase/
17├── packages/
18│ ├── core/ # Export library (@sitebase/core)
19│ ├── cli/ # CLI tool (@sitebase/cli)
20│ └── web/ # Web management UI (@sitebase/web)
21├── scripts/ # Utility scripts
22├── biome.json # Linter/formatter config
23└── tsconfig.json # TypeScript config
24```
25
26## Commands
27
28### Verification
29
30Run these before committing:
31
32```bash
33# Run all checks (typecheck + lint)
34bun run check
35
36# Individual checks
37bun run typecheck # TypeScript type checking
38bun run lint:check # Biome lint (no auto-fix)
39bun run format:check # Biome format (no auto-fix)
40```
41
42### Fixing Issues
43
44```bash
45bun run lint # Auto-fix lint issues
46bun run format # Auto-fix formatting
47```
48
49## Code Style
50
51Enforced by [Biome](https://biomejs.dev/):
52
53- **Indentation**: Tabs
54- **Quotes**: Double quotes
55- **Imports**: Auto-organized on save (via `biome.json` assist)
56
57TypeScript is configured with strict mode and additional safety flags:
58- `noUncheckedIndexedAccess` - Array/object index access may be undefined
59- `noFallthroughCasesInSwitch` - Require break/return in switch cases
60- `noImplicitOverride` - Require `override` keyword
61
62## Packages
63
64### @sitebase/core
65
66Core export functionality. No runtime dependencies except Handlebars.
67
68Key files:
69- `src/types.ts` - Type definitions
70- `src/export.ts` - Export logic
71- `src/config.ts` - Config file loading
72- `src/templates.ts` - Handlebars helpers, slugify
73- `src/atproto.ts` - ATProto fetch utilities
74
75### @sitebase/cli
76
77CLI wrapper around core. Uses Commander for argument parsing.
78
79```bash
80cd packages/cli
81bun run src/index.ts export --config ../path/to/config.ts
82```
83
84### @sitebase/web
85
86Hono-based web server with ATProto OAuth.
87
88```bash
89cd packages/web
90bun run dev
91```
92
93See `packages/web/CLAUDE.md` for web-specific details.
94
95## ATProto Integration
96
97The project uses ATProto lexicons:
98- `site.standard.publication` - Blog/publication metadata
99- `site.standard.document` - Individual documents/posts
100
101Documents are fetched from any PDS via:
1021. Parse AT URI to extract DID
1032. Resolve DID to PDS endpoint via `plc.directory`
1043. Fetch records via `com.atproto.repo.getRecord` / `listRecords`
105
106## Adding Features
107
108### New Handlebars Helper
109
110Add to `packages/core/src/templates.ts` in `registerHelpers()`:
111
112```typescript
113hbs.registerHelper("myHelper", (arg1: unknown) => {
114 // Return transformed value
115 return String(arg1).toUpperCase();
116});
117```
118
119### New Export Option
120
1211. Add type to `packages/core/src/types.ts` in `ExportOptions` and `ExportTarget`
1222. Handle in `packages/core/src/export.ts` in `exportPublication()`
1233. Update `packages/core/src/config.ts` if it affects config loading
1244. Document in README.md
125
126## Workspace Dependencies
127
128Use workspace protocol for internal deps:
129
130```json
131{
132 "dependencies": {
133 "@sitebase/core": "workspace:*"
134 }
135}
136```