Files
radicle-explorer/desktop/AGENTS.md
T
Rūdolfs Ošiņš 748f9e9da7 desktop: Refresh the cache after the user's own writes
Reviews and writes with announcing off or the node stopped never reach the
node's events, so each write command now invalidates the data it changes,
also when it fails partway. Views that pin data join that refetch instead
of starting another.
2026-11-20 19:32:17 +01:00

205 lines
8.2 KiB
Markdown

# radicle-desktop
Tauri desktop app for Radicle. Svelte 5 frontend communicates with a Rust
backend via Tauri IPC commands. TypeScript types are generated from Rust structs
using ts-rs (`crates/radicle-types/`).
The app lives in `desktop/` 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 desktop`, and run every other command here from
`desktop/`. All paths in this file are relative to it. Conventions shared with
explorer are in the root `AGENTS.md`, and UI code shared with it lives in
`shared/ui/`.
## Svelte syntax and aliases
- Svelte 5 with runes syntax (`$state`, `$derived`, `$props`, `$effect`)
- Path aliases: `@app` (src), `@bindings` (crates/radicle-types/bindings),
`@tests`
## Commands
### Development
```sh
npm run dev # full Tauri dev build with hot reload and devtools
npm run start:http # test-http-api backend on :8081 (no Tauri runtime)
npm start # Vite dev server; in a browser it talks to test-http-api
```
Set `VITE_LOG_INVOKE_TIMINGS=true` to log each command's duration
(`[invoke] <command> <ms>ms`) to the browser console. It is off by default.
### Checks and linting
```sh
npm run check # svelte-check, eslint, prettier, then scripts/check-rs
npm run format # auto-fix prettier issues
```
### Unit tests
```sh
npm run test:unit
```
DOMPurify does not sanitize under happy-dom (the unit-test environment):
`<script>` and `onerror=` pass through, and `setConfig` allowlists are ignored.
Don't assert sanitization in `tests/unit/`; verify it in the real app or in an
E2E test.
### E2E tests
```sh
npm run test:e2e
npm run test:e2e -- tests/e2e/<file>.spec.ts
```
Run `./scripts/install-binaries` once after cloning and whenever the Radicle
binaries are updated.
Peer keys have no passphrase, so the app authenticates without an ssh-agent.
Tests that need a running node use the `peer` fixture; tests that need an
ssh-agent use the `sshAuthSock` fixture and create a peer with a `passphrase`.
When a fixture depends on one peer seeing another's changes, wait for the node
event with `waitForEvent` instead of sleeping. Reload pages with `reload(page)`
from `@tests/support/fixtures.js`, not `page.reload()`, and navigate a page that
already shows the app with `goto(page, url)`: the app polls the backend, and the
harness would otherwise fail the test on the request the navigation cancels.
Tests run against a production build in `tests/tmp/build`, served by
`vite preview`; the build takes a few seconds at startup. Set `E2E_DEV_SERVER=1`
to run against the Vite dev server instead, e.g. for hot reload while writing
tests.
Each run writes `tests/artifacts/results.json` (Playwright's JSON report) and
per-test logs in `tests/artifacts/<test>/`. Read those to see what failed in a
run someone else started.
`SKIP_FIXTURE_CREATION=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, the Rust backend, or test
fixtures requires a full run.
```sh
SKIP_FIXTURE_CREATION=true npm run test:e2e
```
### Rust backend (`crates/`)
```sh
scripts/check-rs # cargo fmt --check, clippy on all targets, test
```
### Regenerate TypeScript bindings
Run after changing any type annotated with `#[derive(TS)]` in
`crates/radicle-types/`, and commit the regenerated bindings:
```sh
npm run generate-types
```
### Changes across layers
Adding or changing a Tauri command touches these layers in order:
1. `crates/radicle-types/src/` — add/update Rust types with `#[derive(TS)]` and
`#[ts(export)]`, run `npm run generate-types` to update `@bindings`
2. `crates/radicle-types/src/traits/` — add the method to the relevant port
trait; default implementation goes here, not in the command handler
3. `crates/radicle-tauri/src/commands/` — add the `#[tauri::command]` handler
(thin wrapper: `ctx.method()`), register in `crates/radicle-tauri/src/lib.rs`
4. `crates/test-http-api/src/` — mirror the same route so E2E tests keep
working; `cargo test -p test-http-api --test parity` fails until you do. A
command that can't work over HTTP goes in `TAURI_ONLY` in
`crates/test-http-api/tests/parity.rs`, with the reason
5. `src/` — call via `invoke<T>("command_name", args)`, import types from
`@bindings`
6. `src/lib/writes.ts` — a command that writes either names the cache keys it
affects in `writtenKeys` and `mappedWrites`, or is listed in `outsideCache`
in `tests/unit/writeCoverage.test.ts` with the reason; that test fails until
you do. Reads go in `outsideCache` too
### Tests for a feature
When adding tests for a feature, go through `docs/testing-checklist.md` and
report which items are covered and which don't apply. The testing strategy is in
`docs/adr/0001-testing-strategy.md`.
### Pre-push checklist
`npm run check:ci` runs everything CI runs on every PR (checks, unit tests,
`install-binaries`, E2E tests) and stops at the first failure. It writes the
full output, with each step's duration and exit code, to
`tests/tmp/check-ci.log`.
## Backend architecture
Three crates in a hexagonal architecture; the reasoning is in
`docs/adr/0002-backend-architecture.md`.
- `radicle-types` — domain types, ports (`src/traits/`), domain services
(`src/domain/`), the SQLite adapter (`src/outbound/`), ts-rs bindings
- `radicle-tauri` — Tauri driver; `AppState` implements the ports
- `test-http-api` — HTTP driver for E2E tests and `npm run start:http`;
`Context` implements the same ports
Ports have full default implementations, so a driver only implements `Profile`.
Paginated list views (issues, patches, notifications) go through a domain
`Service` backed by the SQLite adapter instead of the ports; new lists over
large data sets should do the same.
## Data and reactivity
Read `docs/adr/0005-reactivity.md` first. In short:
- Route loaders read cached data with `load(...)` from `@app/lib/cobQueries`,
and views read the same keys with `createQuery`, so that both share it. Keys
come from `@radicle-gui/core/keys`
- Data a view keeps itself, such as a paginated list, refreshes with
`onInvalidate`. Its loader calls `markLoading` on the same key before it
reads, so that an update during the load isn't lost
- The backend forwards the node's ref updates and the changes other processes
make to the node's databases, and `src/lib/startup.svelte.ts` invalidates the
keys they affect. `invoke()` invalidates the keys of the user's own writes
from `src/lib/writes.ts`, since the node doesn't announce every write
- New data must not move what the user is looking at: keep scroll position,
selection and drafts, and pin what the user is reading with `pinned` when
replacing it would disturb them
## Boards
Read `docs/adr/0005-boards.md` before working on boards.
## Code conventions
### Svelte components
- Props use `$props()`: `const { foo, bar = undefined }: Props = $props()`
- Respect reduced motion. CSS transitions and animations are handled globally in
`public/index.css`. Anything driven from JS is not: wrap every Svelte
`transition:`/`in:`/`out:`/`animate:` duration, `element.animate()` duration,
and `setTimeout` that waits on an animation in `motion(ms)`, and use
`scrollBehavior()` instead of `behavior: "smooth"` (both from
`@app/lib/motion`). Custom transition functions apply `motion()` to the
durations they return.
### TypeScript
- Import backend types from `@bindings/*` — these are generated by ts-rs, never
hand-write interfaces that duplicate them
- Call Tauri commands via `invoke<T>("command_name", { arg })` from
`@app/lib/invoke`
### Rust backend
- All serialized types live in `crates/radicle-types/src/`; annotate new types
with `#[derive(Serialize, TS)]`, `#[serde(rename_all = "camelCase")]`,
`#[ts(export)]`, and `#[ts(export_to = "<dir>/")]`
- Optional fields: `#[serde(skip_serializing_if = "Option::is_none")]`
- Error type: `radicle_types::error::Error`
- `rust-toolchain.toml` tracks heartwood's. When bumping the `radicle` crate,
check heartwood's toolchain too: an older rustc fails inside the dependency
with a confusing error (e.g. E0382 in `cob/identity.rs` for radicle 0.25)