notecrumbs

a nostr opengraph server build on nostrdb and egui
git clone git://jb55.com/notecrumbs
Log | Files | Refs | README | LICENSE

AGENTS.md (2136B)

      1 # notecrumbs · Agent Briefing
      2 
      3 ## Project Snapshot
      4 - notecrumbs is a Nostr OpenGraph renderer built on `nostrdb`, `egui`, and `skia`.
      5 - The HTTP server lives in `src/main.rs`; rendering logic is split across `src/render.rs` and `src/html.rs`.
      6 - Static assets (fonts, default profile picture) are loaded from the repo root, so run binaries from this directory.
      7 
      8 ## Environment & Tooling
      9 - Requires a Rust toolchain with Skia prerequisites installed (`clang`, `cmake`, Python, build essentials).
     10 - `nostrdb` stores data in the current working directory via `Ndb::new(".", …)`.
     11 - `TIMEOUT_MS` environment variable tunes remote fetch waits (default 2000 ms).
     12 
     13 ## Workflow Notes
     14 - Build: `cargo build --release` (first run is slow while Skia compiles).
     15 - Tests: `cargo test` (currently empty but should stay green).
     16 - Formatting: `cargo fmt`; lint: `cargo clippy -- -D warnings`.
     17 
     18 ## Coding Guidelines
     19 - Use `tracing` macros for logging.
     20 - HTML/attribute-escape user content before injecting into responses (`html.rs` has helpers).
     21 - Rendering paths should avoid blocking the async runtime; reuse cached textures.
     22 - `RenderData::complete` pairs nostrdb subscriptions with network fetches—keep it resilient to partially missing data.
     23 
     24 ## Testing Expectations
     25 - Add unit tests around pure helpers (e.g., `abbrev.rs`) when modifying them.
     26 - For nostrdb-heavy flows, prefer integration tests or mocked paths gated for CI.
     27 - Manually spot-check PNG (`/<bech32>.png`) and HTML (`/<bech32>`) outputs when touching rendering code.
     28 
     29 ## Open Threads
     30 - Consult `TODO` for active work (local relay model, formatting for unparsed notes).
     31 - README “Status” checklist highlights upcoming features like profile picture rendering/caching.
     32 
     33 ## Pre-PR Checklist
     34 - `cargo fmt --check`
     35 - `cargo clippy -- -D warnings`
     36 - `cargo test`
     37 - Optional: manual PNG/HTML smoke tests against representative notes/profiles.
     38 
     39 ## Contribution Practices
     40 1. Make every commit logically distinct.
     41 2. Ensure each commit is standalone so it can be dropped later without breaking the build.
     42 3. Keep code readable and reviewable by humans—favor clarity over cleverness.