apoena.dev
forked from
stevedylan.dev/sequoia
A CLI for publishing standard.site documents to ATProto
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7Sequoia 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.remanso.note`) and publishes them to a user's PDS.
8
9Website: <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
16Bun workspaces manage the monorepo.
17
18## Commands
19
20```bash
21# Build CLI
22bun run build:cli
23
24# Run CLI in dev (build + link)
25cd packages/cli && bun run dev
26
27# Run tests
28bun run test:cli
29
30# Run a single test file
31cd packages/cli && bun test src/lib/markdown.test.ts
32
33# Lint (auto-fix)
34cd packages/cli && bun run lint
35
36# Format (auto-fix)
37cd packages/cli && bun run format
38
39# Docs dev server
40bun 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- `remanso.ts` — Creates `space.remanso.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
85Never add 'Co-authored-by' lines to git commits unless explicitly asked.