# radicle-explorer The Svelte web app for browsing Radicle repositories, its TypeScript HTTP client, and the `radicle-httpd` and `radicle-search` backends it talks to. The project lives in `explorer/` of the radicle-gui monorepo. It is a package in the root npm workspace and its own Cargo workspace: install npm dependencies at the repository root with `npm ci -w explorer`, and run every other command here from `explorer/`. All paths in this file are relative to it. Conventions shared with desktop are in the root `AGENTS.md`, and UI code shared with it lives in `shared/ui/`. ## Checks and linting (tsc, svelte-check, eslint, prettier) ```sh npm run check npm run format # auto-fix prettier issues ``` ## Unit tests ```sh npm run test:unit npm run test:http-client:unit ``` ## E2E tests ```sh npm run test:e2e -- --project chromium npm run test:e2e -- tests/e2e/.spec.ts --project chromium ``` `SKIP_SETUP=true` skips fixture creation for faster iteration. Only use it when you are solely editing `.spec.ts` files and fixtures already exist from a previous full run. Any change to app code, httpd, or test fixtures requires a full run. ```sh SKIP_SETUP=true npm run test:e2e -- --project chromium ``` ## Rust backend (`crates/`) The same commands CI runs: ```sh 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 `crates/radicle-httpd/`, also test against the local build and run both to verify backwards compatibility: ```sh npm run test:e2e:local -- --project chromium npm run test:http-client:unit:local ``` ## API changes across layers Adding or changing an API endpoint typically touches three layers: 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) **Backwards compatibility:** Only add to the backend API — never rename or remove fields/endpoints unless explicitly deprecating. The frontend must handle older nodes gracefully: treat new API fields as optional and fall back when they're absent. Put that fallback in `http-client/lib/compat.ts`, tagged with when it can go (`Client: remove when explorer drops httpd 0.30.`). Breaking changes go through expand and contract, see `docs/adr/0001-expand-and-contract-api-changes.md`, and get an entry in `docs/api-changes.md`. ## Pre-push checklist `npm run check:ci` runs the checks, unit, http-client, e2e and build smoke tests and the Open Graph worker bundle from the GitHub workflows, and stops at the first failure. It logs each step's output, duration and exit code to `tests/tmp/check-ci.log`. If Rust code changed, also run the Rust commands and the `:local` variants above. ## Svelte components - Optional props use `export let foo: T = undefined`, not `?:` ## `{@html}` and untrusted data (XSS) - Avoid `{@html}` with backend-derived data (branch/ref names, aliases, descriptions); when unavoidable, its argument must be DOMPurify-sanitized (`sanitizeConfig` in `src/lib/markdown.ts`) or built from `escape()`'d parts, in the component that renders it. ## TypeScript / HTTP client - Derive types from Zod schemas (`z.infer`), never hand-write interfaces that duplicate a schema - Schema naming: `fooSchema` (camelCase + Schema suffix) → type `Foo` - API timestamps are in seconds; multiply by 1000 for JS `Date` - Relative imports inside `http-client/` use `.js` extension (ESM)