coracle-rust

coracle-lib - Struct definitions, stateless utilities related to nostr.
coracle-net - Networking utilities for working with relays
coracle-signer - Signer client/server utilities
coracle-domain - Domain-specific nostr types: profiles, follows, reactions, zaps, etc.
coracle-content - Text parsing and rendering utilities
coracle-storage - Storage adapters for different platforms

All code is written in a literate programming style and compiled to both html documentation and rust source code. The goal of this repository is threefold:

To create a complete resource for learning how to work with the nostr protocol for humans
To create a production-ready nostr utility library for inclusion in rust, KMP, and web projects.
To experiment with using literate programming to serve both as a library and context file for LLMs.

Prerequisites

Rust
just
mdbook (cargo install mdbook)

How it works

The source of truth is the book/ directory, which contains markdown files written in a literate programming style. Code blocks annotated with a file path are extracted ("tangled") into Rust source files by the coracle-tangle tool.

For example, a code block like this in a markdown file:

  ```rust {file=coracle-lib/src/event.rs}
  pub struct Event { ... }


will be extracted to `coracle-lib/src/event.rs`. Multiple blocks targeting the same file are concatenated in document order, so you can introduce a struct in one section and add methods to it later in the narrative.

Code blocks without a `{file=...}` annotation are illustrative only and are not tangled.

The `src/` directories of the library crates are generated artifacts and should not be edited directly. Edit the markdown in `book/` instead.

## Usage

```sh
# Tangle: extract code from markdown into .rs files
just tangle

# Build: tangle + compile all library crates
just build

# Check: tangle + type-check without full compilation
just check

# Weave: tangle + generate the HTML book (output in target/book/)
just weave

# Clean: remove all generated source and book output
just clean

# All: build + weave
just all

Project structure

book/               # Literate source (the single source of truth)
  book.toml         # mdBook configuration
  SUMMARY.md        # Table of contents
  01-introduction.md
  02-events.md      # etc.
coracle-tangle/     # The tangle/weave tool (Rust binary)
coracle-lib/        # Core nostr types and utilities (generated src/)
coracle-net/        # Relay networking (generated src/)
coracle-signer/     # Signing abstractions (generated src/)
coracle-content/    # Content parsing (generated src/)
coracle-storage/    # Storage adapters (generated src/)