From 19ab609aa3bbe8a43e077dc99541e13fd850d1cf Mon Sep 17 00:00:00 2001 From: Daniel Norman Date: Mon, 27 Jul 2026 16:20:13 +0200 Subject: [PATCH] Refine CLAUDE.md --- .claude/skills/radicle-ecosystem/SKILL.md | 53 ++++++++++++++++++ CLAUDE.md | 66 ++--------------------- crates/radicle-httpd/CLAUDE.md | 17 ++++++ 3 files changed, 73 insertions(+), 63 deletions(-) create mode 100644 .claude/skills/radicle-ecosystem/SKILL.md create mode 100644 crates/radicle-httpd/CLAUDE.md diff --git a/.claude/skills/radicle-ecosystem/SKILL.md b/.claude/skills/radicle-ecosystem/SKILL.md new file mode 100644 index 000000000..bf7ece58b --- /dev/null +++ b/.claude/skills/radicle-ecosystem/SKILL.md @@ -0,0 +1,53 @@ +--- +name: radicle-ecosystem +description: Map of the sibling Radicle repositories that radicle-httpd depends on (heartwood, radicle-git, radicle-job, rips, radicle.dev), with the key crates and files to read in each. Use when working on Rust code in radicle-httpd, when you need protocol or domain context, or when a type comes from a crate outside this repo. +--- + +# Radicle ecosystem (sibling repos) + +`radicle-httpd` depends on crates from sibling repositories. Read +source from these paths when working on Rust code. + +## heartwood (`../heartwood`) + +Core Radicle protocol implementation. Key crates used by httpd: +- `radicle` — standard library (storage, identity, COBs, git, node) +- `radicle-cob` — collaborative objects (issues, patches as CRDTs) +- `radicle-crypto` — Ed25519 signing, SSH key handling +- `radicle-core` — fundamental types (`RepoId`, etc.) + +Key files: +- `../heartwood/HACKING.md` — development guide, environment variables +- `../heartwood/ARCHITECTURE.md` — high-level architecture +- `../heartwood/crates/radicle/src/lib.rs` — main library entry point + +## radicle-git (`../radicle-git`) + +Git library wrappers. Key crate: +- `radicle-surf` — code browsing (files, diffs, commits, branches, + tags). This is what httpd uses to serve repository content. + +Key file: `../radicle-git/radicle-surf/src/lib.rs` + +## radicle-job (`../radicle-job`) + +Decentralized job execution (CI/CD) on the Radicle network. +Key file: `../radicle-job/README.md` + +## RIPs — protocol specs (`../rips`) + +- `../rips/0001-heartwood.md` — protocol overview +- `../rips/0002-identity.md` — identity system (DIDs, Ed25519) +- `../rips/0003-storage-layout.md` — git storage layout + +## Radicle documentation (`../radicle.dev`) + +Read these when you need domain context for UI work: +- `../radicle.dev/_guides/user.md` — end-to-end user workflows + (init, clone, seed, issues, patches, code review, private repos) +- `../radicle.dev/_guides/protocol.md` — protocol internals + (gossip, replication, identity documents, COB data model, trust) +- `../radicle.dev/_guides/seeder.md` — seed node operation + (seeding policies, httpd setup, DNS-SD) +- `../radicle.dev/_posts/2025-07-23-using-radicle-ci-for-development.md` — CI integration +- `../radicle.dev/_posts/2025-08-12-canonical-references.md` — canonical refs design diff --git a/CLAUDE.md b/CLAUDE.md index c03191da3..71ccc44a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,9 +13,6 @@ client (`http-client/`) and a Rust backend (`radicle-httpd/`). ## Tech stack - Svelte 5 with legacy syntax (`$:`, stores, `export let`) -- TypeScript, Vite, Vitest, Playwright -- Rust backend: `radicle-httpd/` -- Path aliases: `@app` (src), `@http-client`, `@public`, `@tests` ## Commands @@ -89,52 +86,9 @@ and fall back when they're absent. ## Radicle ecosystem (sibling repos) -`radicle-httpd` depends on crates from sibling repositories. Read -source from these paths when working on Rust code. - -### heartwood (`../heartwood`) - -Core Radicle protocol implementation. Key crates used by httpd: -- `radicle` — standard library (storage, identity, COBs, git, node) -- `radicle-cob` — collaborative objects (issues, patches as CRDTs) -- `radicle-crypto` — Ed25519 signing, SSH key handling -- `radicle-core` — fundamental types (`RepoId`, etc.) - -Key files: -- `../heartwood/HACKING.md` — development guide, environment variables -- `../heartwood/ARCHITECTURE.md` — high-level architecture -- `../heartwood/crates/radicle/src/lib.rs` — main library entry point - -### radicle-git (`../radicle-git`) - -Git library wrappers. Key crate: -- `radicle-surf` — code browsing (files, diffs, commits, branches, - tags). This is what httpd uses to serve repository content. - -Key file: `../radicle-git/radicle-surf/src/lib.rs` - -### radicle-job (`../radicle-job`) - -Decentralized job execution (CI/CD) on the Radicle network. -Key file: `../radicle-job/README.md` - -### RIPs — protocol specs (`../rips`) - -- `../rips/0001-heartwood.md` — protocol overview -- `../rips/0002-identity.md` — identity system (DIDs, Ed25519) -- `../rips/0003-storage-layout.md` — git storage layout - -### Radicle documentation (`../radicle.dev`) - -Read these when you need domain context for UI work: -- `../radicle.dev/_guides/user.md` — end-to-end user workflows - (init, clone, seed, issues, patches, code review, private repos) -- `../radicle.dev/_guides/protocol.md` — protocol internals - (gossip, replication, identity documents, COB data model, trust) -- `../radicle.dev/_guides/seeder.md` — seed node operation - (seeding policies, httpd setup, DNS-SD) -- `../radicle.dev/_posts/2025-07-23-using-radicle-ci-for-development.md` — CI integration -- `../radicle.dev/_posts/2025-08-12-canonical-references.md` — canonical refs design +See the `radicle-ecosystem` skill for the map of sibling repositories +(heartwood, radicle-git, radicle-job, rips, radicle.dev) and the key +crates and files in each. ## Domain glossary @@ -174,20 +128,6 @@ Read these when you need domain context for UI work: - API timestamps are in seconds; multiply by 1000 for JS `Date` - Relative imports inside `http-client/` use `.js` extension (ESM) -### Rust backend (radicle-httpd) - -- Each route module exposes `pub fn router(ctx: Context) -> Router`; - handlers are private `async fn`s -- Handler signature: - `async fn handler(State(ctx): State, Path(rid): Path) -> impl IntoResponse` -- Annotate the error type on Ok: `Ok::<_, Error>(Json(data))` -- All response structs: `#[serde(rename_all = "camelCase")]` -- Optional fields: `#[serde(skip_serializing_if = "Option::is_none")]` -- Use `json!()` macro for inline JSON; `immutable_response()` / - `cached_response()` helpers for Cache-Control headers -- Module structure: `api/v1/` handlers, `api/json/` serialization helpers, - `api/query.rs` query param types, `api/error.rs` error types - ## Commit messages - Imperative mood: "Add feature" not "Added feature" diff --git a/crates/radicle-httpd/CLAUDE.md b/crates/radicle-httpd/CLAUDE.md new file mode 100644 index 000000000..f7c394b9e --- /dev/null +++ b/crates/radicle-httpd/CLAUDE.md @@ -0,0 +1,17 @@ +# radicle-httpd + +Rust backend for radicle-explorer. + +## Code conventions + +- Each route module exposes `pub fn router(ctx: Context) -> Router`; + handlers are private `async fn`s +- Handler signature: + `async fn handler(State(ctx): State, Path(rid): Path) -> impl IntoResponse` +- Annotate the error type on Ok: `Ok::<_, Error>(Json(data))` +- All response structs: `#[serde(rename_all = "camelCase")]` +- Optional fields: `#[serde(skip_serializing_if = "Option::is_none")]` +- Use `json!()` macro for inline JSON; `immutable_response()` / + `cached_response()` helpers for Cache-Control headers +- Module structure: `api/v1/` handlers, `api/json/` serialization helpers, + `api/query.rs` query param types, `api/error.rs` error types