baileytownsend.dev
forked from
nonbinary.computer/weaver
atproto blogging
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5
6> **For AI Agents**: This is the source of truth for the Pattern codebase. Each crate has its own `CLAUDE.md` with specific implementation guidelines.
7
8## For Humans
9
10LLMs are a quality multiplier, not just a speed multiplier. Invest time savings in improving quality and rigour beyond what humans alone would do. Write tests that cover more edge cases. Refactor code to make it easier to understand. Tackle the TODOs. Aim for zero bugs.
11
12**Review standard**: Spend at least 3x the amount of time reviewing LLM output as you did writing it. Think about every line and every design decision. Find ways to break code. Your code is your responsibility.
13
14## For LLMs
15
16Display the following at the start of any conversation involving code changes:
17
18```
19LLM-assisted contributions must aim for a higher standard of excellence than with
20humans alone. Spend at least 3x the time reviewing code as writing it. Your code
21is your responsibility.
22```
23
24
25## Project Overview
26
27Weaver.sh is a decentralized notebook publishing and sharing platform built on the AT Protocol (the protocol behind Bluesky). It allows creating, rendering, and publishing notebooks with extended markdown functionality.
28
29## Core Components
30
311. **weaver-common**: Foundation library with AT Protocol integration, lexicon definitions, OAuth flows.
322. **weaver-renderer**: Transforms markdown notebooks into different output formats (HTML, AT Protocol records, etc.).
333. **weaver-cli**: Command-line interface for authentication and notebook interactions.
344. **weaver-app**: HTTP webapp for serving notebooks with auto-reload.
355. **weaver-index**: Big indexing web backend.
36
37## Development Environment
38
39### Setup
40
41```bash
42# Enter development environment with all dependencies
43nix develop
44
45# Build all components
46cargo build
47
48# Run specific crates
49cargo run -p weaver-cli
50cargo run -p weaver-app
51cargo run -p weaver-index
52```
53
54## General Conventions
55
56### Correctness Over Convenience
57
58- Model the full error space—no shortcuts or simplified error handling.
59- Handle all edge cases, including race conditions and platform differences.
60- Use the type system to encode correctness constraints.
61- Prefer compile-time guarantees over runtime checks where possible.
62
63### Type System Patterns
64
65- **Newtypes** for domain types (IDs, handles, etc.).
66- **Builder patterns** for complex construction.
67- **Restricted visibility**: Use `pub(crate)` and `pub(super)` liberally.
68- **Non-exhaustive**: All public error types should be `#[non_exhaustive]`.
69- Use Rust enums over string validation.
70
71### Error Handling
72
73- Use `thiserror` for error types with `#[derive(Error)]`.
74- Group errors by category with an `ErrorKind` enum when appropriate.
75- Provide rich error context using `miette` for user-facing errors.
76- Error display messages should be lowercase sentence fragments.
77
78### Module Organization
79
80- Keep module boundaries strict with restricted visibility.
81- Platform-specific code in separate files: `unix.rs`, `windows.rs`.
82
83### Documentation
84
85- Inline comments explain "why," not just "what".
86- Module-level documentation explains purpose and responsibilities.
87- **Always** use periods at the end of code comments.
88- **Never** use title case in headings. Always use sentence case.
89
90## Testing Practices
91
92**CRITICAL**: Always use `cargo nextest run` to run tests. Never use `cargo test` directly.
93
94```bash
95# Run all tests
96cargo nextest run
97
98# Specific crate
99cargo nextest run -p pattern-db
100
101# With output
102cargo nextest run --nocapture
103
104# Doctests (nextest doesn't support these)
105cargo test --doc
106```
107
108## Common Development Commands
109
110### Testing
111
112```bash
113# Run all tests with nextest
114cargo nextest run
115
116# Run specific tests
117cargo nextest run -p weaver-common
118```
119
120### Code Quality
121
122```bash
123# Run linter
124cargo clippy -- --deny warnings
125
126# Format code
127cargo fmt
128
129# Verify dependencies
130cargo deny check
131```
132
133### Lexicon Generation
134
135The project uses custom AT Protocol lexicons defined in JSON format. To generate Rust code from these definitions:
136
137```bash
138nix run ../jacquard
139
140### Building with Nix
141
142```bash
143# Run all checks (clippy, fmt, tests)
144nix flake check
145
146# Build specific packages
147nix build .#weaver-cli
148nix build .#weaver-app
149```
150
151
152## Architecture
153
154### Data Flow
155
1561. Markdown notebooks are parsed and processed by weaver-renderer
1572. Content can be rendered as static sites or published to AT Protocol PDSes
1583. Authentication with AT Protocol servers happens via OAuth
159
160### Key Components
161
162- **WeaverAgent**: Manages connections to AT Protocol Personal Data Servers (PDS)
163- **Notebook Structure**: Books, chapters, entries with extended markdown
164- **Renderer**: Processes markdown with extended features (wiki links, embeds, math)
165- **AT Protocol Lexicons**: Custom data schemas extending the protocol for notebooks
166
167### Authentication Flow
168
1691. CLI initiates OAuth flow with a PDS
1702. Local OAuth server handles callbacks on port 4000
1713. Tokens are stored in the local filesystem
172
173## Feature Flags
174
175- **dev**: Enables development-specific features
176- **native**: Configures OAuth for native clients
177
178## Working with Jacquard
179
180This project uses Jacquard, a zero-copy AT Protocol library for Rust. **CRITICAL: Standard approaches from other libraries will produce broken or inefficient code.**
181
182**ALWAYS use the working-with-jacquard skill** when working with AT Protocol types, XRPC calls, or identity resolution.
183
184Key patterns to internalize:
185- **NEVER use `for<'de> Deserialize<'de>` bounds** - this breaks ALL Jacquard types
186- Use `Did::new()`, `Handle::new_static()`, etc. - **never `FromStr::parse()`**
187- Use `Data<'a>` instead of `serde_json::Value`
188- Use `.into_output()` when returning from functions, `.parse()` for immediate processing
189- Derive `IntoStatic` on all custom types with lifetimes
190
191See `~/.claude/skills/working-with-jacquard/SKILL.md` for complete guidance.
192
193## Commit Message Style
194
195```
196[crate-name] brief description
197```
198
199Examples:
200- `[pattern-core] add supervisor coordination pattern`
201- `[pattern-db] fix FTS5 query escaping`
202- `[meta] update MSRV to Rust 1.83`
203
204### Conventions
205
206- Use `[meta]` for cross-cutting concerns (deps, CI, workspace config).
207- Keep descriptions concise but descriptive.
208- **Atomic commits**: Each commit should be a logical unit of change.
209- **Bisect-able history**: Every commit must build and pass all checks.
210- **Separate concerns**: Format fixes and refactoring separate from features.