From 357f4311f63e0ce24ee11512599a269267c39b9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C5=ABdolfs=20O=C5=A1i=C5=86=C5=A1?= Date: Tue, 13 Oct 2026 11:21:14 +0200 Subject: [PATCH] Document where the desktop app lives So both the docs and agents know `desktop/` is its own project, with commands run from there. --- CLAUDE.md | 163 +++++++++++++++++++++++---------- README.md | 3 + crates/radicle-httpd/CLAUDE.md | 3 +- desktop/CLAUDE.md | 6 ++ desktop/README.md | 12 ++- 5 files changed, 132 insertions(+), 55 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 16ae68673..03269420c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,109 @@ -# radicle-explorer +# radicle-gui -Svelte web app for browsing Radicle repositories with a TypeScript HTTP -client (`http-client/`) and a Rust backend (`radicle-httpd/`). +Monorepo for Radicle's graphical interfaces. It holds two independent +projects, each with its own npm package, Cargo workspace, toolchain files, +checks and conventions: -## Plan mode +- **Explorer** (repository root): the Svelte web app for browsing Radicle + repositories, its TypeScript HTTP client, and the `radicle-httpd` and + `radicle-search` backends it talks to. +- **Desktop** (`desktop/`): the Tauri desktop app. Its own `desktop/CLAUDE.md` + is the source of truth for anything under `desktop/`. + +## Layout + +| Path | Project | What it is | +|---|---|---| +| `src/`, `public/`, `tests/` | explorer | Svelte web app and its unit, e2e and visual tests | +| `http-client/` | explorer | TypeScript client for the httpd API | +| `crates/radicle-httpd/` | explorer | HTTP daemon serving the API (Rust), with its own `CLAUDE.md` for code conventions | +| `crates/radicle-search/` | explorer | Search service, released together with httpd (Rust) | +| `workers/` | explorer | Cloudflare workers (open-graph images) | +| `scripts/` | explorer | Check, CI and e2e helper scripts | +| `desktop/` | desktop | Tauri app: Svelte frontend in `desktop/src/`, Rust in `desktop/crates/` | +| `.github/workflows/` | both | GitHub CI: `check*.yml` for explorer, `desktop-*.yml` for desktop | +| `.buildkite/` | explorer | Radicle CI pipelines | +| `.ryph/` | both | Dev machine image and setup for agents, see `.ryph/environment.md` | + +## Working in this repo + +- Work out which project a change belongs to first, and run every command + from that project's root: the repository root for explorer, `desktop/` + for desktop. Root `npm` and `cargo` commands never cover `desktop/`, and + the root lint and format checks skip it on purpose. +- The two projects don't share code. A change that touches both is two + changes: check each project with its own commands. +- The rules under "Explorer" below don't apply in `desktop/`. In particular, + explorer uses legacy Svelte syntax while desktop uses Svelte 5 runes. + +### Plan mode - Propose the minimal MVP first — no tests, no docs, no speculative extras - Tests are added only when explicitly requested after MVP review - Keep plans concise: short bullet points listing what changes and where - Skip obvious details and boilerplate explanations -## Tech stack +### Shared conventions -- Svelte 5 with legacy syntax (`$:`, stores, `export let`) +- Prefer `undefined` over `null` +- Do not add comments unless explicitly asked. When writing comments, + use proper English sentences +- Ask before adding new dependencies +- Use npm, never `yarn` or `pnpm` +- Do not use `npm test` — neither project has a default test script +- Do not use `npx vitest` or `npx playwright test` — use the `npm run` scripts -## Commands +### Commit messages + +- Imperative mood: "Add feature" not "Added feature" +- Capitalize subject, no trailing period, max 50 chars +- Prefix backend-only commits with `httpd:` + +### Releases and tags + +Each project is released on its own. Release tags are +`releases//`; the `refs/tags/releases/*` rule in the +repository's identity decides when they become canonical. + +| Component | How it's released | Tag | +|---|---|---| +| Explorer web app | Deployed continuously, no releases or tags | — | +| `radicle-httpd` + `radicle-search` | Together, one version, see `RELEASE.md` | `releases/httpd/` | +| Desktop app | `desktop/scripts/release`, see `desktop/README.md` | `releases/desktop/` | + +The older `releases/` tags (httpd 0.22.0–0.29.0, desktop +0.9.0–0.16.0) are left over from before the two repositories were merged. +Never create, match or describe against them; scripts must always match a +component's own prefix. + +### Radicle ecosystem (sibling repos) + +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 + +- **RID** — Repository ID (`rad:z3gqc...`) +- **DID** — Decentralized Identifier, user identity (`did:key:z6Mk...`) +- **NID** — Node ID, public key suffix of a DID +- **COB** — Collaborative Object (issue, patch, or identity as a Git DAG) +- **Delegate** — authorized repo maintainer; signatures determine canonical state +- **Patch** — pull-request equivalent with immutable revisions and reviews +- **Seed** — hosting/replicating a repo; seed nodes are always-on servers +- **Canonical refs** — branches/tags resolved by delegate quorum + +## Explorer (repository root) + +Everything in this section applies to the repository root only. Run all +commands from there. + +### Tech stack + +- Svelte 5 with legacy syntax (`$:`, stores, `export let`). Do not use + Svelte 5 runes (`$state`, `$derived`, `$props`) here +- TypeScript, Vite, Vitest, Playwright, Zod +- Rust for `crates/radicle-httpd` and `crates/radicle-search` ### Checks and linting (tsc, svelte-check, eslint, prettier) @@ -46,17 +135,21 @@ or test fixtures requires a full run. SKIP_SETUP=true npm run test:e2e -- --project chromium ``` -### Rust backend (radicle-httpd) +### Rust backend (`crates/`) + +The same commands CI runs: ```sh -cd radicle-httpd && cargo clippy --all --tests -cd radicle-httpd && cargo fmt --all --check -cd radicle-httpd && cargo test --all-features +RUSTFLAGS="-D warnings" cargo clippy --workspace --all-features --tests +RUSTFLAGS="-D warnings" cargo clippy -p radicle-httpd --no-default-features --tests +cargo fmt --all -- --check +cargo test --workspace --all-features +cargo test -p radicle-httpd ``` E2E and http-client tests run against a stable pre-built httpd by -default. When changing `radicle-httpd/`, also test against the local -build and run both to verify backwards compatibility: +default. When changing `crates/radicle-httpd/`, also test against the +local build and run both to verify backwards compatibility: ```sh npm run test:e2e:local -- --project chromium @@ -66,7 +159,7 @@ npm run test:http-client:unit:local ### API changes across layers Adding or changing an API endpoint typically touches three layers: -1. `radicle-httpd/` — Rust handler (add route, types, logic) +1. `crates/radicle-httpd/` — Rust handler (add route, types, logic) 2. `http-client/` — TypeScript client (add fetch function, types) 3. `src/` — Svelte UI (consume the new data) @@ -84,30 +177,6 @@ and fall back when they're absent. 5. If Rust code changed: clippy, fmt, cargo test (see above), plus `:local` variants of e2e and http-client tests -## Radicle ecosystem (sibling repos) - -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 - -- **RID** — Repository ID (`rad:z3gqc...`) -- **DID** — Decentralized Identifier, user identity (`did:key:z6Mk...`) -- **NID** — Node ID, public key suffix of a DID -- **COB** — Collaborative Object (issue, patch, or identity as a Git DAG) -- **Delegate** — authorized repo maintainer; signatures determine canonical state -- **Patch** — pull-request equivalent with immutable revisions and reviews -- **Seed** — hosting/replicating a repo; seed nodes are always-on servers -- **Canonical refs** — branches/tags resolved by delegate quorum - -## Code conventions - -- Prefer `undefined` over `null` -- Do not add comments unless explicitly asked. When writing comments, - use proper English sentences -- Ask before adding new dependencies - ### Svelte components - Script order (enforced by prettier): `