apoena.dev
forked from
stevedylan.dev/sequoia
A CLI for publishing standard.site documents to ATProto
chore: add CLAUDE file
+85
CLAUDE.md
+85
CLAUDE.md
···
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Project Overview
6
+
7
+
Sequoia is a CLI tool for publishing Markdown documents with frontmatter to the AT Protocol (Bluesky's decentralized social network). It converts blog posts into ATProto records (`site.standard.document`, `space.litenote.note`) and publishes them to a user's PDS.
8
+
9
+
Website: <https://sequoia.pub>
10
+
11
+
## Monorepo Structure
12
+
13
+
- **`packages/cli/`** — Main CLI package (the core product)
14
+
- **`docs/`** — Documentation website (Vocs-based, deployed to Cloudflare Pages)
15
+
16
+
Bun workspaces manage the monorepo.
17
+
18
+
## Commands
19
+
20
+
```bash
21
+
# Build CLI
22
+
bun run build:cli
23
+
24
+
# Run CLI in dev (build + link)
25
+
cd packages/cli && bun run dev
26
+
27
+
# Run tests
28
+
bun run test:cli
29
+
30
+
# Run a single test file
31
+
cd packages/cli && bun test src/lib/markdown.test.ts
32
+
33
+
# Lint (auto-fix)
34
+
cd packages/cli && bun run lint
35
+
36
+
# Format (auto-fix)
37
+
cd packages/cli && bun run format
38
+
39
+
# Docs dev server
40
+
bun run dev:docs
41
+
```
42
+
43
+
## Architecture
44
+
45
+
**Entry point:** `packages/cli/src/index.ts` — Uses `cmd-ts` for type-safe subcommand routing.
46
+
47
+
**Commands** (`src/commands/`):
48
+
49
+
- `publish` — Core workflow: scans markdown files, publishes to ATProto
50
+
- `sync` — Fetches published records state from ATProto
51
+
- `update` — Updates existing records
52
+
- `auth` — Multi-identity management (app-password + OAuth)
53
+
- `init` — Interactive config setup
54
+
- `inject` — Injects verification links into static HTML output
55
+
- `login` — Legacy auth (deprecated)
56
+
57
+
**Libraries** (`src/lib/`):
58
+
59
+
- `atproto.ts` — ATProto API wrapper (two client types: AtpAgent for app-password, OAuth client)
60
+
- `config.ts` — Loads `sequoia.json` config and `.sequoia-state.json` state files
61
+
- `credentials.ts` — Multi-identity credential storage at `~/.config/sequoia/credentials.json` (0o600 permissions)
62
+
- `markdown.ts` — Frontmatter parsing (YAML/TOML), content hashing, atUri injection
63
+
64
+
**Extensions** (`src/extensions/`):
65
+
66
+
- `litenote.ts` — Creates `space.litenote.note` records with embedded images
67
+
68
+
## Key Patterns
69
+
70
+
- **Config resolution:** `sequoia.json` is found by searching up the directory tree
71
+
- **Frontmatter formats:** YAML (`---`), TOML (`+++`), and alternative (`***`) delimiters
72
+
- **Credential types:** App-password (PDS URL + identifier + password) and OAuth (DID + handle)
73
+
- **Build:** `bun build src/index.ts --target node --outdir dist`
74
+
75
+
## Tooling
76
+
77
+
- **Runtime/bundler:** Bun
78
+
- **Linter/formatter:** Biome (tabs, double quotes)
79
+
- **Test runner:** Bun's native test runner
80
+
- **CLI framework:** `cmd-ts`
81
+
- **Interactive UI:** `@clack/prompts`
82
+
83
+
## Git Conventions
84
+
85
+
Never add 'Co-authored-by' lines to git commits unless explicitly asked.