commit 7998de31489cda661b1aa4eecdaaee5955c50465 · zbrox.com/jacquard

-13

.claude/settings.local.json

···

       1
       1
       -
       {

     

       2
       2
       -
         "permissions": {

     

       3
       3
       -
           "allow": [

     

       4
       4
       -
             "WebSearch",

     

       5
       5
       -
             "WebFetch(domain:atproto.com)",

     

       6
       6
       -
             "WebFetch(domain:github.com)",

     

       7
       7
       -
             "WebFetch(domain:raw.githubusercontent.com)",

     

       8
       8
       -
             "WebFetch(domain:docs.rs)"

     

       9
       9
       -
           ],

     

       10
       10
       -
           "deny": [],

     

       11
       11
       -
           "ask": []

     

       12
       12
       -
         }

     

       13
       13
       -
       }

-151

CLAUDE.md

···

       1
       1
       -
       # CLAUDE.md

     

       2
       2
       -
       

     

       3
       3
       -
       This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

     

       4
       4
       -
       

     

       5
       5
       -
       ## Project Overview

     

       6
       6
       -
       

     

       7
       7
       -
       Jacquard is a suite of Rust crates for the AT Protocol (atproto/Bluesky). The project emphasizes spec-compliant, validated, performant baseline types with minimal boilerplate. Key design goals:

     

       8
       8
       -
       

     

       9
       9
       -
       - Validated AT Protocol types including typed at:// URIs

     

       10
       10
       -
       - Custom lexicon extension support

     

       11
       11
       -
       - Lexicon `Value` type for working with unknown atproto data (dag-cbor or json)

     

       12
       12
       -
       - Using as much or as little of the crates as needed

     

       13
       13
       -
       

     

       14
       14
       -
       ## Workspace Structure

     

       15
       15
       -
       

     

       16
       16
       -
       This is a Cargo workspace with several crates:

     

       17
       17
       -
       

     

       18
       18
       -
       - **jacquard**: Main library crate with XRPC client and public API surface (re-exports jacquard-api and jacquard-common)

     

       19
       19
       -
       - **jacquard-common**: Core AT Protocol types (DIDs, handles, at-URIs, NSIDs, TIDs, CIDs, etc.) and the `CowStr` type for efficient string handling

     

       20
       20
       -
       - **jacquard-lexicon**: Lexicon parsing and Rust code generation from lexicon schemas

     

       21
       21
       -
       - **jacquard-api**: Generated API bindings from lexicon schemas (implementation detail, not directly used by consumers)

     

       22
       22
       -
       - **jacquard-derive**: Attribute macros (`#[lexicon]`, `#[open_union]`) for lexicon structures

     

       23
       23
       -
       

     

       24
       24
       -
       ## Development Commands

     

       25
       25
       -
       

     

       26
       26
       -
       ### Using Nix (preferred)

     

       27
       27
       -
       ```bash

     

       28
       28
       -
       # Enter dev shell

     

       29
       29
       -
       nix develop

     

       30
       30
       -
       

     

       31
       31
       -
       # Build

     

       32
       32
       -
       nix build

     

       33
       33
       -
       

     

       34
       34
       -
       # Run

     

       35
       35
       -
       nix develop -c cargo run

     

       36
       36
       -
       ```

     

       37
       37
       -
       

     

       38
       38
       -
       ### Using Cargo/Just

     

       39
       39
       -
       ```bash

     

       40
       40
       -
       # Build

     

       41
       41
       -
       cargo build

     

       42
       42
       -
       

     

       43
       43
       -
       # Run tests

     

       44
       44
       -
       cargo test

     

       45
       45
       -
       

     

       46
       46
       -
       # Run specific test

     

       47
       47
       -
       cargo test <test_name>

     

       48
       48
       -
       

     

       49
       49
       -
       # Run specific package tests

     

       50
       50
       -
       cargo test -p <package_name>

     

       51
       51
       -
       

     

       52
       52
       -
       # Run

     

       53
       53
       -
       cargo run

     

       54
       54
       -
       

     

       55
       55
       -
       # Auto-recompile and run

     

       56
       56
       -
       just watch [ARGS]

     

       57
       57
       -
       

     

       58
       58
       -
       # Format and lint all

     

       59
       59
       -
       just pre-commit-all

     

       60
       60
       -
       

     

       61
       61
       -
       # Generate API bindings from lexicon schemas

     

       62
       62
       -
       cargo run -p jacquard-lexicon --bin jacquard-codegen -- -i <input_dir> -o <output_dir> [-r <root_module>]

     

       63
       63
       -
       # Example:

     

       64
       64
       -
       cargo run -p jacquard-lexicon --bin jacquard-codegen -- -i crates/jacquard-lexicon/tests/fixtures/lexicons/atproto/lexicons -o crates/jacquard-api/src -r crate

     

       65
       65
       -
       ```

     

       66
       66
       -
       

     

       67
       67
       -
       ## String Type Pattern

     

       68
       68
       -
       

     

       69
       69
       -
       The codebase uses a consistent pattern for validated string types. Each type should have:

     

       70
       70
       -
       

     

       71
       71
       -
       ### Constructors

     

       72
       72
       -
       - `new()`: Construct from a string slice with appropriate lifetime (borrows)

     

       73
       73
       -
       - `new_owned()`: Construct from `impl AsRef<str>`, taking ownership

     

       74
       74
       -
       - `new_static()`: Construct from `&'static str` using `SmolStr`/`CowStr`'s static constructor (no allocation)

     

       75
       75
       -
       - `raw()`: Same as `new()` but panics instead of returning `Result`

     

       76
       76
       -
       - `unchecked()`: Same as `new()` but doesn't validate (marked `unsafe`)

     

       77
       77
       -
       - `as_str()`: Return string slice

     

       78
       78
       -
       

     

       79
       79
       -
       ### Traits

     

       80
       80
       -
       All string types should implement:

     

       81
       81
       -
       - `Serialize` + `Deserialize` (custom impl for latter, sometimes for former)

     

       82
       82
       -
       - `FromStr`, `Display`

     

       83
       83
       -
       - `Debug`, `PartialEq`, `Eq`, `Hash`, `Clone`

     

       84
       84
       -
       - `From<T> for String`, `CowStr`, `SmolStr`

     

       85
       85
       -
       - `From<String>`, `From<CowStr>`, `From<SmolStr>`, or `TryFrom` if likely to fail

     

       86
       86
       -
       - `AsRef<str>`

     

       87
       87
       -
       - `Deref` with `Target = str` (usually)

     

       88
       88
       -
       

     

       89
       89
       -
       ### Implementation Details

     

       90
       90
       -
       - Use `#[repr(transparent)]` when possible (exception: at-uri type and components)

     

       91
       91
       -
       - Use `SmolStr` directly as inner type if most instances will be under 24 bytes

     

       92
       92
       -
       - Use `CowStr` for longer strings to allow borrowing from input

     

       93
       93
       -
       - Implement `IntoStatic` trait to take ownership of string types

     

       94
       94
       -
       

     

       95
       95
       -
       ## Code Style

     

       96
       96
       -
       

     

       97
       97
       -
       - Avoid comments for self-documenting code

     

       98
       98
       -
       - Comments should not detail fixes when refactoring

     

       99
       99
       -
       - Professional writing within source code and comments only

     

       100
       100
       -
       - Prioritize long-term maintainability over implementation speed

     

       101
       101
       -
       

     

       102
       102
       -
       ## Testing

     

       103
       103
       -
       

     

       104
       104
       -
       - Write test cases for all critical code

     

       105
       105
       -
       - Tests can be run per-package or workspace-wide

     

       106
       106
       -
       - Use `cargo test <name>` to run specific tests

     

       107
       107
       -
       - Current test coverage: 89 tests in jacquard-common

     

       108
       108
       -
       

     

       109
       109
       -
       ## Lexicon Code Generation

     

       110
       110
       -
       

     

       111
       111
       -
       The `jacquard-codegen` binary generates Rust types from AT Protocol Lexicon schemas:

     

       112
       112
       -
       

     

       113
       113
       -
       - Generates structs with `#[lexicon]` attribute for forward compatibility (captures unknown fields in `extra_data`)

     

       114
       114
       -
       - Generates enums with `#[open_union]` attribute for handling unknown variants (unless marked `closed` in lexicon)

     

       115
       115
       -
       - Resolves local refs (e.g., `#image` becomes `Image<'a>`)

     

       116
       116
       -
       - Extracts doc comments from lexicon `description` fields

     

       117
       117
       -
       - Adds header comments with `@generated` marker and lexicon NSID

     

       118
       118
       -
       - Handles XRPC queries, procedures, subscriptions, and errors

     

       119
       119
       -
       - Generates proper module tree with Rust 2018 style

     

       120
       120
       -
       - **XrpcRequest trait**: Implemented directly on params/input structs (not marker types), with GATs for Output<'de> and Err<'de>

     

       121
       121
       -
       - **IntoStatic trait**: All generated types implement `IntoStatic` to convert borrowed types to owned ('static) variants

     

       122
       122
       -
       - **Collection trait**: Implemented on record types directly, with const NSID

     

       123
       123
       -
       

     

       124
       124
       -
       ## Current State & Next Steps

     

       125
       125
       -
       

     

       126
       126
       -
       ### Completed

     

       127
       127
       -
       - ✅ Comprehensive validation tests for all core string types (handle, DID, NSID, TID, record key, AT-URI, datetime, language, identifier)

     

       128
       128
       -
       - ✅ Validated implementations against AT Protocol specs and TypeScript reference implementation

     

       129
       129
       -
       - ✅ String type interface standardization (Language now has `new_static()`, Datetime has full conversion traits)

     

       130
       130
       -
       - ✅ Data serialization: Full serialize/deserialize for `Data<'_>`, `Array`, `Object` with format-specific handling (JSON vs CBOR)

     

       131
       131
       -
       - ✅ CidLink wrapper type with automatic `{"$link": "cid"}` serialization in JSON

     

       132
       132
       -
       - ✅ Integration test with real Bluesky thread data validates round-trip correctness

     

       133
       133
       -
       - ✅ Lexicon code generation with forward compatibility and proper lifetime handling

     

       134
       134
       -
       - ✅ IntoStatic implementations for all generated types (structs, enums, unions)

     

       135
       135
       -
       - ✅ XrpcRequest trait with GATs, implemented on params/input types directly

     

       136
       136
       -
       - ✅ HttpClient and XrpcClient traits with generic send_xrpc implementation

     

       137
       137
       -
       - ✅ Response wrapper with parse() (borrowed) and into_output() (owned) methods

     

       138
       138
       -
       - ✅ Structured error types (ClientError, TransportError, EncodeError, DecodeError, HttpError, AuthError)

     

       139
       139
       -
       

     

       140
       140
       -
       ### Next Steps

     

       141
       141
       -
       1. **Concrete HttpClient Implementation**: Implement HttpClient for reqwest::Client and potentially other HTTP clients

     

       142
       142
       -
       2. **Error Handling Improvements**: Add XRPC error parsing, better HTTP status code handling, structured error responses

     

       143
       143
       -
       3. **Authentication**: Session management, token refresh, DPoP support

     

       144
       144
       -
       4. **Body Encoding**: Support for non-JSON encodings (CBOR, multipart, etc.) in procedures

     

       145
       145
       -
       5. **Lexicon Resolution**: Fetch lexicons from web sources (atproto authorities, git repositories) and parse into corpus

     

       146
       146
       -
       6. **Custom Lexicon Support**: Allow users to plug in their own generated lexicons alongside jacquard-api types in the client/server layer

     

       147
       147
       -
       7. **Public API**: Design the main API surface in `jacquard` that re-exports and wraps generated types

     

       148
       148
       -
       8. **DID Document Support**: Parsing, validation, and resolution of DID documents

     

       149
       149
       -
       9. **OAuth Implementation**: OAuth flow support for authentication

     

       150
       150
       -
       10. **Examples & Documentation**: Create examples and improve documentation

     

       151
       151
       -
       11. **Testing**: Comprehensive tests for generated code and round-trip serialization

-120

regen.rs

···

       1
       1
       -
       use jacquard_lexicon::codegen::CodeGenerator;

     

       2
       2
       -
       use jacquard_lexicon::corpus::LexiconCorpus;

     

       3
       3
       -
       use prettyplease;

     

       4
       4
       -
       use std::collections::BTreeMap;

     

       5
       5
       -
       use std::fs;

     

       6
       6
       -
       use std::path::Path;

     

       7
       7
       -
       

     

       8
       8
       -
       fn main() -> Result<(), Box<dyn std::error::Error>> {

     

       9
       9
       -
           let lexicons_path = "lexicons/atproto";

     

       10
       10
       -
           let output_path = "crates/jacquard-api/src";

     

       11
       11
       -
           let root_module = "crate";

     

       12
       12
       -
       

     

       13
       13
       -
           println!("Loading lexicons from {}...", lexicons_path);

     

       14
       14
       -
           let corpus = LexiconCorpus::load_from_dir(lexicons_path)?;

     

       15
       15
       -
           println!("Loaded {} lexicons", corpus.len());

     

       16
       16
       -
       

     

       17
       17
       -
           println!("Generating code...");

     

       18
       18
       -
           let generator = CodeGenerator::new(&corpus, root_module);

     

       19
       19
       -
       

     

       20
       20
       -
           // Group by module

     

       21
       21
       -
           let mut modules: BTreeMap<String, Vec<(String, String)>> = BTreeMap::new();

     

       22
       22
       -
       

     

       23
       23
       -
           for (nsid, doc) in corpus.iter() {

     

       24
       24
       -
               let nsid_str = nsid.as_str();

     

       25
       25
       -
       

     

       26
       26
       -
               // Get module path: app.bsky.feed.post -> app_bsky/feed

     

       27
       27
       -
               let parts: Vec<&str> = nsid_str.split('.').collect();

     

       28
       28
       -
               let module_path = if parts.len() >= 3 {

     

       29
       29
       -
                   let first_two = format!("{}_{}", parts[0], parts[1]);

     

       30
       30
       -
                   if parts.len() > 3 {

     

       31
       31
       -
                       let middle: Vec<&str> = parts[2..parts.len() - 1].iter().copied().collect();

     

       32
       32
       -
                       format!("{}/{}", first_two, middle.join("/"))

     

       33
       33
       -
                   } else {

     

       34
       34
       -
                       first_two

     

       35
       35
       -
                   }

     

       36
       36
       -
               } else {

     

       37
       37
       -
                   parts.join("_")

     

       38
       38
       -
               };

     

       39
       39
       -
       

     

       40
       40
       -
               let file_name = parts.last().unwrap().to_string();

     

       41
       41
       -
       

     

       42
       42
       -
               for (def_name, def) in &doc.defs {

     

       43
       43
       -
                   match generator.generate_def(nsid_str, def_name, def) {

     

       44
       44
       -
                       Ok(tokens) => {

     

       45
       45
       -
                           let code = prettyplease::unparse(&syn::parse_file(&tokens.to_string())?);

     

       46
       46
       -
                           modules

     

       47
       47
       -
                               .entry(format!("{}/{}.rs", module_path, file_name))

     

       48
       48
       -
                               .or_default()

     

       49
       49
       -
                               .push((def_name.to_string(), code));

     

       50
       50
       -
                       }

     

       51
       51
       -
                       Err(e) => {

     

       52
       52
       -
                           eprintln!("Error generating {}.{}: {:?}", nsid_str, def_name, e);

     

       53
       53
       -
                       }

     

       54
       54
       -
                   }

     

       55
       55
       -
               }

     

       56
       56
       -
           }

     

       57
       57
       -
       

     

       58
       58
       -
           // Write files

     

       59
       59
       -
           for (file_path, defs) in modules {

     

       60
       60
       -
               let full_path = Path::new(output_path).join(&file_path);

     

       61
       61
       -
       

     

       62
       62
       -
               // Create parent directory

     

       63
       63
       -
               if let Some(parent) = full_path.parent() {

     

       64
       64
       -
                   fs::create_dir_all(parent)?;

     

       65
       65
       -
               }

     

       66
       66
       -
       

     

       67
       67
       -
               let content = defs.iter().map(|(_, code)| code.as_str()).collect::<Vec<_>>().join("\n");

     

       68
       68
       -
               fs::write(&full_path, content)?;

     

       69
       69
       -
               println!("Wrote {}", file_path);

     

       70
       70
       -
           }

     

       71
       71
       -
       

     

       72
       72
       -
           // Generate mod.rs files

     

       73
       73
       -
           println!("Generating mod.rs files...");

     

       74
       74
       -
           generate_mod_files(Path::new(output_path))?;

     

       75
       75
       -
       

     

       76
       76
       -
           println!("Done!");

     

       77
       77
       -
           Ok(())

     

       78
       78
       -
       }

     

       79
       79
       -
       

     

       80
       80
       -
       fn generate_mod_files(root: &Path) -> Result<(), Box<dyn std::error::Error>> {

     

       81
       81
       -
           // Find all directories

     

       82
       82
       -
           for entry in fs::read_dir(root)? {

     

       83
       83
       -
               let entry = entry?;

     

       84
       84
       -
               let path = entry.path();

     

       85
       85
       -
       

     

       86
       86
       -
               if path.is_dir() {

     

       87
       87
       -
                   let dir_name = path.file_name().unwrap().to_str().unwrap();

     

       88
       88
       -
       

     

       89
       89
       -
                   // Recursively generate for subdirectories

     

       90
       90
       -
                   generate_mod_files(&path)?;

     

       91
       91
       -
       

     

       92
       92
       -
                   // Generate mod.rs for this directory

     

       93
       93
       -
                   let mut mods = Vec::new();

     

       94
       94
       -
                   for sub_entry in fs::read_dir(&path)? {

     

       95
       95
       -
                       let sub_entry = sub_entry?;

     

       96
       96
       -
                       let sub_path = sub_entry.path();

     

       97
       97
       -
       

     

       98
       98
       -
                       if sub_path.is_file() {

     

       99
       99
       -
                           if let Some(name) = sub_path.file_stem() {

     

       100
       100
       -
                               let name_str = name.to_str().unwrap();

     

       101
       101
       -
                               if name_str != "mod" {

     

       102
       102
       -
                                   mods.push(format!("pub mod {};", name_str));

     

       103
       103
       -
                               }

     

       104
       104
       -
                           }

     

       105
       105
       -
                       } else if sub_path.is_dir() {

     

       106
       106
       -
                           if let Some(name) = sub_path.file_name() {

     

       107
       107
       -
                               mods.push(format!("pub mod {};", name.to_str().unwrap()));

     

       108
       108
       -
                           }

     

       109
       109
       -
                       }

     

       110
       110
       -
                   }

     

       111
       111
       -
       

     

       112
       112
       -
                   if !mods.is_empty() {

     

       113
       113
       -
                       let mod_content = mods.join("\n") + "\n";

     

       114
       114
       -
                       fs::write(path.join("mod.rs"), mod_content)?;

     

       115
       115
       -
                   }

     

       116
       116
       -
               }

     

       117
       117
       -
           }

     

       118
       118
       -
       

     

       119
       119
       -
           Ok(())

     

       120
       120
       -
       }