mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-10-18 19:30:27 +08:00
Refine CLAUDE.md
This commit is contained in:
Daniel Norman
@@ -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
|
||||
@@ -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<Context>, Path(rid): Path<RepoId>) -> 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"
|
||||
|
||||
@@ -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<Context>, Path(rid): Path<RepoId>) -> 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
|
||||
Reference in New Issue
Block a user