desktop: run prettier format

This commit is contained in:
Daniel Norman
2026-10-27 11:12:02 +01:00
parent 9b5b20f646
commit 280d642e6d
8 changed files with 258 additions and 276 deletions
+42 -40
View File
@@ -1,18 +1,19 @@
# 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/`).
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 its own npm
package and Cargo workspace: run every command here from `desktop/`, and all
paths in this file are relative to it. Conventions shared with explorer
are in the root `AGENTS.md`.
paths in this file are relative to it. Conventions shared with explorer are in
the root `AGENTS.md`.
## Svelte syntax and aliases
- Svelte 5 with runes syntax (`$state`, `$derived`, `$props`, `$effect`)
- Path aliases: `@app` (src), `@bindings` (crates/radicle-types/bindings), `@tests`
- Path aliases: `@app` (src), `@bindings` (crates/radicle-types/bindings),
`@tests`
## Commands
@@ -41,9 +42,9 @@ 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.
`<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
@@ -55,29 +56,28 @@ 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.
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.
`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.
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.
`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
@@ -104,21 +104,22 @@ 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
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
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`
5. `src/` — call via `invoke<T>("command_name", args)`, import types from
`@bindings`
### 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`.
report which items are covered and which don't apply. The testing strategy is in
`docs/adr/0001-testing-strategy.md`.
### Pre-push checklist
@@ -138,10 +139,10 @@ Three crates in a hexagonal architecture; the reasoning is in
- `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.
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.
## Code conventions
@@ -153,7 +154,8 @@ lists over large data sets should do the same.
- 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`
- Call Tauri commands via `invoke<T>("command_name", { arg })` from
`@app/lib/invoke`
### Rust backend
+62 -73
View File
@@ -4,8 +4,8 @@
- Added Releases and Release views for browsing a repository's releases and
their artifacts, with links, mentions, a warning on releases and artifacts
published by others, and the artifact node and rad-artifact CLI versions
in the status popover
published by others, and the artifact node and rad-artifact CLI versions in
the status popover
- Added smart links and better mentions: `rad:` links now open in the app,
Radicle entities in comments are linked, and mentions search node aliases
- Added a repository identity document view
@@ -15,18 +15,18 @@
- Markdown now renders Mermaid diagrams, GitHub style alerts and repository
images in READMEs
- Task list items in Markdown can now be checked and unchecked
- AsciiDoc READMEs are now rendered in the source view, with cross
references linked to their source
- AsciiDoc READMEs are now rendered in the source view, with cross references
linked to their source
- Document links now stay inside the app
- Merged patches are now sorted by merge time
- The patch list now shows the latest revision's diffstat
- You can seed a missing repository directly from mentions
- Adding new repositories will immediately fetch them from the network
- Issues can now be created with only a subject
- The issue page now matches the patch page design, with the metadata
buttons in the action row
- Collapsed sidebar items now show tooltips, and private repositories show
a lock on their avatar
- The issue page now matches the patch page design, with the metadata buttons in
the action row
- Collapsed sidebar items now show tooltips, and private repositories show a
lock on their avatar
- Polished sidebar animations and spacing
**Bug fixes**
@@ -50,23 +50,22 @@
- [brandonoxendine](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkpwnLQxFBQXyMK3Es91s8A7Ew7G11BFFyng1dqZR8QhG3)
- [efstajas](https://radicle.network/nodes/iris.radicle.network/users/z6MkqG3Pu18RWuZ8GrqGQ9s4yoi5rfhcLq9rpo1ZZX8en994)
### v0.16.0
**Features**
- Added a collapsible, resizable sidebar that remembers its width and
collapsed state across launches
- Repositories that are only in local storage can now be shown alongside
seeded ones, controlled by a new setting
- Private repositories are now marked with a lock and public ones with a
globe in the sidebar
- Added "Stop seeding" to the sidebar context menu, with the option to
delete the repository files as well
- Patches now show the branch they are opened against, in the patch list,
the patch page and the merge activity item
- The author and committer popover now shows emails, lists co-authors, and
shows both the authored and committed time
- Added a collapsible, resizable sidebar that remembers its width and collapsed
state across launches
- Repositories that are only in local storage can now be shown alongside seeded
ones, controlled by a new setting
- Private repositories are now marked with a lock and public ones with a globe
in the sidebar
- Added "Stop seeding" to the sidebar context menu, with the option to delete
the repository files as well
- Patches now show the branch they are opened against, in the patch list, the
patch page and the merge activity item
- The author and committer popover now shows emails, lists co-authors, and shows
both the authored and committed time
- The detected git binary is now shown in the settings
- The Guide button in the sidebar can now be hidden
- Added a Cmd+, shortcut to open Settings
@@ -75,40 +74,36 @@
**Bug fixes**
- Fixed patch diffs for revisions whose head is a merge commit dropping
most of their commits
- Fixed a single duplicate path, such as a symlink replaced by a regular
file, emptying the whole Changes tab
- Git and rad are now resolved outside the session PATH, fixing git not
being found when the app is launched from the desktop
- Editing a patch title no longer resets its target branch to the default
branch
- Fixed patch diffs for revisions whose head is a merge commit dropping most of
their commits
- Fixed a single duplicate path, such as a symlink replaced by a regular file,
emptying the whole Changes tab
- Git and rad are now resolved outside the session PATH, fixing git not being
found when the app is launched from the desktop
- Editing a patch title no longer resets its target branch to the default branch
- The patch description is no longer collapsed while it is being edited
- Reacting or commenting no longer makes the view jump
- Clicking a commit in a patch no longer shifts the layout
- The window stays draggable while a modal is open
- Save buttons are now disabled instead of hidden when there is nothing to
save
- Save buttons are now disabled instead of hidden when there is nothing to save
- Commit time is now used instead of author time consistently
**Shout-out to our contributors 🙏✨**
- [2color](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MktwkohCx8aHZ1QCjVZUiLmX92oPZFxRiFZkbq32Tk5Tkm)
- [brandonoxendine](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkpwnLQxFBQXyMK3Es91s8A7Ew7G11BFFyng1dqZR8QhG3)
- [upbeat-molar](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkmRaBHeJuJKQE21aRVSe2uW3j5T7gQQAEAY7UF4tr5jRn)
### v0.15.0
**Features**
- Reworked the patch page UX, review UI and activity timeline
- Patch changes are now rendered with Pierre's diff viewer
- Added a comment column to the review view: every line comment is listed
beside the files, and clicking one scrolls the diff to it
- The review view's column can now switch between comments and a file tree,
show only the commented files, or be put away to give the diff full width
- Added a comment column to the review view: every line comment is listed beside
the files, and clicking one scrolls the diff to it
- The review view's column can now switch between comments and a file tree, show
only the commented files, or be put away to give the diff full width
- Added a comment stepper to the Changes tab for walking a diff's comments
- Diff settings now live in the settings modal, grouped with the code font,
instead of a per-view popover
@@ -119,12 +114,10 @@
- Timestamps now show their absolute value on hover
- Added dismissible hints to textboxes
**Shout-out to our contributors 🙏✨**
- [brandonoxendine](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkpwnLQxFBQXyMK3Es91s8A7Ew7G11BFFyng1dqZR8QhG3)
### v0.14.0
**Features**
@@ -135,11 +128,10 @@
**Bug fixes**
- Links now use your configured explorer and preferred seed instead of
hardcoded defaults
- Links now use your configured explorer and preferred seed instead of hardcoded
defaults
- Fixed console windows flashing when navigating repos on Windows
**Shout-out to our contributors 🙏✨**
- [brandonoxendine](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkpwnLQxFBQXyMK3Es91s8A7Ew7G11BFFyng1dqZR8QhG3)
@@ -147,7 +139,6 @@
- [hlatimer266](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkkwiqeqFrjPNvSNuNACpynpwiuVHqF8YHwGLzCBSfNJzZ)
- [justarandomgeek](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkwfrBy9mKTfcVELcV4wc6zfN379FPMnAqsxnwt4j2TdQ2)
### v0.13.0
**Features**
@@ -156,7 +147,8 @@
**Performance**
- Virtualized the file tree, commit diff, and patch-review diff views for smoother scrolling on large repositories and diffs
- Virtualized the file tree, commit diff, and patch-review diff views for
smoother scrolling on large repositories and diffs
- Sped up opening files and computing diff stats in large repositories
- Sped up commit counting using git's bitmap index
- Improved issues list loading performance
@@ -166,8 +158,8 @@
- Fixed patches list pagination loading everything at once instead of paging
- Fixed the update checker reading a stale cached version file
- Fixed the Linux launcher showing the wrong app name
- List scroll position is now restored when navigating back and forth through history
- List scroll position is now restored when navigating back and forth through
history
### v0.12.0
@@ -185,7 +177,6 @@
- Fixed the Linux AppImage failing to launch on non-Debian distributions
- Fixed duplicate CI job runs by deduplicating them by run ID
### v0.11.0
**Features**
@@ -194,10 +185,12 @@
- Added repo pinning to keep favorite repos at the top of the sidebar
- Added a fuzzy filter to the notification inbox
- Added a reload button to the sidebar
- Added a custom in-app context menu for sidebar items and disabled the native browser menu app-wide
- Added a custom in-app context menu for sidebar items and disabled the native
browser menu app-wide
- Redesigned the CI job status popover and added it to the single-commit view
- Reviews can now be started directly from a code comment on a revision diff
- Issue and patch breadcrumbs now show status-specific labels and link back to the matching filter
- Issue and patch breadcrumbs now show status-specific labels and link back to
the matching filter
- The first revision description is now shown on the patch view
- Replies are now indented into individual boxes for clearer threading
- Reactions have been restyled and your own reactions are highlighted
@@ -227,7 +220,6 @@
- Worked around alias lookups failing in some cases
- Improved Windows compatibility (CLI detection and npm script hints)
**Shout-out to our contributors 🙏✨**
- [2color](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MktwkohCx8aHZ1QCjVZUiLmX92oPZFxRiFZkbq32Tk5Tkm)
@@ -239,7 +231,6 @@
- [lorenz](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkkPvBfjP4bQmco5Dm7UGsX2ruDBieEHi8n9DVJWX5sTEz)
- [yarikoptic](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkfCGiLM9j7AstSVNGhqtz9zkAhfb863etsbkRnXsipuRr)
### v0.10.0
- Fixed app loading indicator
@@ -251,7 +242,6 @@
- [lorenz](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkkPvBfjP4bQmco5Dm7UGsX2ruDBieEHi8n9DVJWX5sTEz)
### v0.9.0
- Redesigned the entire app with a new UI kit — typography, colors, icons,
@@ -268,7 +258,8 @@
- Getting started guide shown to new users on first launch
- Added a setting to disable the notification badge
- Added a code font setting
- Fixed reactions and edits incorrectly targeting the root comment instead of the intended reply
- Fixed reactions and edits incorrectly targeting the root comment instead of
the intended reply
- Restricted issue/patch state, labels, and assignees to delegates only
**Shout-out to our contributors 🙏✨**
@@ -276,25 +267,25 @@
- [brandonhaslegs](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkpwnLQxFBQXyMK3Es91s8A7Ew7G11BFFyng1dqZR8QhG3)
- [julien](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkgvaRdahQZfnf7ccMHByeHtTYrMrM3MuSGYawF6ZL6DNj)
### v0.8.0
- CI job run statuses are now shown for the default branch and in patch revision commit lists
- CI job run statuses are now shown for the default branch and in patch revision
commit lists
- Fixed an issue where commit listings reversed when switching between patches
- Fixed a bug that prevented replying to review comments
- Fixed app version check feature
- Fixed incorrect IDs (e.g., patch revision, comments) being copied to clipboard
- Improved accessibility and keyboard navigation in repository filters on the home view
- Improved accessibility and keyboard navigation in repository filters on the
home view
**Shout-out to our contributors 🙏✨**
- [geigerzaehler](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6Mki9XNNHeVRnYS88U59iCBzKUp2xWM3f4zvA3cXuKJFvWF)
### v0.7.1
- Fixed a bug in patch and notification lists caused by a library incompatibility
- Fixed a bug in patch and notification lists caused by a library
incompatibility
### v0.7.0
@@ -307,12 +298,11 @@
- [geigerzaehler](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6Mki9XNNHeVRnYS88U59iCBzKUp2xWM3f4zvA3cXuKJFvWF)
### v0.6.1
- Fixed a bug where the app wouldn't onboard new users or locked identities
- Fixed regression where the current version of the app wasn't including the commit it was built from
- Fixed regression where the current version of the app wasn't including the
commit it was built from
### v0.6.0
@@ -326,7 +316,6 @@
- [geigerzaehler](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6Mki9XNNHeVRnYS88U59iCBzKUp2xWM3f4zvA3cXuKJFvWF)
### v0.5.0
- The app is now officially available via Arch packaging
@@ -337,8 +326,10 @@
- Fullscreen error shown if COB schemas need upgrading
- UI improvements: themed scrollbars that auto-hide and match the color scheme
- Repos can now be seeded by RID directly from the app
- Added warning and one-click recovery when COB cache is out of date, fixing mismatched patch/issue counters
- Fixed regression where single patch view didn’t load additional items on scroll
- Added warning and one-click recovery when COB cache is out of date, fixing
mismatched patch/issue counters
- Fixed regression where single patch view didn’t load additional items on
scroll
**Shout-out to our contributors 🙏✨**
@@ -347,17 +338,16 @@
- [lorenz](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkkPvBfjP4bQmco5Dm7UGsX2ruDBieEHi8n9DVJWX5sTEz)
- [tippfehlr](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MksSTAFPKk7eQju9aGzK64qpfiSnKQ1tJWv1rdzRd5bMHU)
### v0.4.1
- Fixed a bug in the release pipeline to update the latest artifacts
- Added WSL2 installation instructions to https://radworks.garden
### v0.4.0
- Notification inbox is now accessible from any view without navigating away
- App icon now shows a badge with the unread notification count and polls for updates
- App icon now shows a badge with the unread notification count and polls for
updates
- Added global breadcrumbs for easier navigation
- Added quick copy actions for IDs and links to https://radicle.network
- Syntax highlighting added for diffs in markdown code blocks (` ```diff `)
@@ -373,7 +363,6 @@
- [tshepang](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MkfPSKW7AgQqXSi8fgEJMduHpm9ABmsPYwPhMeF7PssonK)
- [youthlic](https://radicle.network/nodes/iris.radicle.network/users/did:key:z6MktsSuE4bVYbuTtEPjmhrQWA7dMri7GUg9Qp9o8tRCsmhu)
### v0.3.0
- New onboarding guide to help users get started faster
@@ -382,13 +371,13 @@
- Settings now show version and commit hash for easier support
- Fixed notification count and comment placement bugs
### v0.2.0
- Added font size controls for enhanced readability and accessibility
- Introduced contextual explainers in key areas to guide users and improve overall user experience
- Enhanced contrast in both dark and light modes to improve legibility and visual clarity
- Introduced contextual explainers in key areas to guide users and improve
overall user experience
- Enhanced contrast in both dark and light modes to improve legibility and
visual clarity
### v0.1.0
+6 -4
View File
@@ -1,6 +1,7 @@
# Radicle Desktop
This desktop application lets you interact with [Radicle][rad], a peer-to-peer code collaboration and publishing stack.
This desktop application lets you interact with [Radicle][rad], a peer-to-peer
code collaboration and publishing stack.
It lives in the `desktop/` folder of the radicle-gui repository, next to the
Radicle web explorer. Run all commands below from `desktop/`.
@@ -44,8 +45,8 @@ npm run dev
```
To log how long every backend command takes, for performance work, set
`VITE_LOG_INVOKE_TIMINGS=true`. Each call then prints `[invoke] <command> <ms>ms`
to the browser console (visible at debug level):
`VITE_LOG_INVOKE_TIMINGS=true`. Each call then prints
`[invoke] <command> <ms>ms` to the browser console (visible at debug level):
```
VITE_LOG_INVOKE_TIMINGS=true npm run dev
@@ -82,7 +83,8 @@ with `scripts/release --list` and `scripts/release --help`. Releases are tagged
## Getting in touch
To get in touch with the maintainers, sign up to our [official chat on Zulip][zul].
To get in touch with the maintainers, sign up to our [official chat on
Zulip][zul].
## License
+29 -34
View File
@@ -8,56 +8,51 @@ Accepted
## Context
The app has many features and few tests. We need a way to decide what to
test, at which layer, and in what order, without trying to reach full
coverage.
The app has many features and few tests. We need a way to decide what to test,
at which layer, and in what order, without trying to reach full coverage.
## Decision
Prioritise by risk: how bad a failure is (corrupt COB writes are worse than
wrong display), how likely it is (complex logic, churn, crossing the Rust/TS
boundary) and how hard it is to notice manually (multi-peer, caching,
timing).
boundary) and how hard it is to notice manually (multi-peer, caching, timing).
Test each behaviour at the cheapest layer that can catch its failure:
| Layer | Tool | Scope |
| -------- | ----------------------------- | ------------------------------------------------------------------------ |
| TS unit | Vitest, `tests/unit/` | Pure logic: parsing, routing, formatting, filters, diff and review logic |
| Rust | `cargo test` | Trait default implementations, type conversions, error codes |
| E2E | Playwright + `test-http-api` | User journeys and every write path against a real Radicle profile |
| Manual | Tauri build | Native-only features: dialogs, clipboard images, drag and drop, badges |
| Layer | Tool | Scope |
| ------- | ---------------------------- | ------------------------------------------------------------------------ |
| TS unit | Vitest, `tests/unit/` | Pure logic: parsing, routing, formatting, filters, diff and review logic |
| Rust | `cargo test` | Trait default implementations, type conversions, error codes |
| E2E | Playwright + `test-http-api` | User journeys and every write path against a real Radicle profile |
| Manual | Tauri build | Native-only features: dialogs, clipboard images, drag and drop, badges |
Rules:
- Unit tests come first because they are the cheapest.
- Every bug fix adds a regression test, at the cheapest layer that
reproduces the bug, and the test fails without the fix.
- Every bug fix adds a regression test, at the cheapest layer that reproduces
the bug, and the test fails without the fix.
- Non-trivial logic inside a component (branching, ordering, grouping,
deduplication, parsing) is extracted into a module in `src/lib/` and
tested there. A one-line helper with a single caller stays in the
component. Comments that explain why the code is the way it is move with
it.
deduplication, parsing) is extracted into a module in `src/lib/` and tested
there. A one-line helper with a single caller stays in the component. Comments
that explain why the code is the way it is move with it.
- Tests assert behaviour: an outcome, a property or a relationship between
inputs. They don't restate UI copy, CSS classes, selector strings or
constant tables, since such tests only ever change in lockstep with the
code.
- A test earns its place by failing when the logic it covers breaks. New
tests are checked by mutating that logic (flip a comparison, drop a
filter, shift a boundary), and a test that never fails is removed.
- Extracted logic is tested in isolation, so the component flow that wires
it into a write path still needs its E2E test.
- Every mutating command gets at least one E2E happy path and one
permission or error case. Reads are covered by unit tests plus one E2E
test showing the data renders.
- Combinations such as filters and sort orders are covered in unit tests,
not in E2E.
inputs. They don't restate UI copy, CSS classes, selector strings or constant
tables, since such tests only ever change in lockstep with the code.
- A test earns its place by failing when the logic it covers breaks. New tests
are checked by mutating that logic (flip a comparison, drop a filter, shift a
boundary), and a test that never fails is removed.
- Extracted logic is tested in isolation, so the component flow that wires it
into a write path still needs its E2E test.
- Every mutating command gets at least one E2E happy path and one permission or
error case. Reads are covered by unit tests plus one E2E test showing the data
renders.
- Combinations such as filters and sort orders are covered in unit tests, not in
E2E.
- State persisted in `localStorage` gets one reload test in E2E.
- Sanitisation is asserted in E2E only, since DOMPurify is a no-op under
happy-dom.
- `test-http-api` mirrors every Tauri command. Logic lives in
`radicle-types` so that both drivers stay thin wrappers, and a parity test
fails when a command, route or frontend `invoke` has no counterpart.
- `test-http-api` mirrors every Tauri command. Logic lives in `radicle-types` so
that both drivers stay thin wrappers, and a parity test fails when a command,
route or frontend `invoke` has no counterpart.
New features follow [the testing checklist](../testing-checklist.md).
+36 -39
View File
@@ -8,16 +8,15 @@ Accepted
## Context
The app needs the same backend behaviour in two places: inside Tauri for
the desktop app, and over HTTP so the frontend can run in a browser for E2E
tests and development without the Tauri runtime. If each runtime held its
own logic, the two would drift and the E2E tests would stop exercising the
code users run.
The app needs the same backend behaviour in two places: inside Tauri for the
desktop app, and over HTTP so the frontend can run in a browser for E2E tests
and development without the Tauri runtime. If each runtime held its own logic,
the two would drift and the E2E tests would stop exercising the code users run.
Most reads and writes go straight through the `radicle` crate. Some list
views can't: reading patches, issues and notifications through heartwood's
caches loads and sorts every item in memory on each page, which is too slow
for large repositories.
Most reads and writes go straight through the `radicle` crate. Some list views
can't: reading patches, issues and notifications through heartwood's caches
loads and sorts every item in memory on each page, which is too slow for large
repositories.
This ADR records a design that grew from 2024 onwards (the HTTP driver in
October 2024, the first domain service for the inbox in January 2025).
@@ -26,44 +25,42 @@ October 2024, the first domain service for the inbox in January 2025).
The backend follows a hexagonal architecture split across three crates:
| Crate | Role |
| --------------- | ---------------------------------------------------------- |
| `radicle-types` | Domain types, ports, adapters and the ts-rs bindings |
| `radicle-tauri` | Tauri driver: thin IPC wrappers around port methods |
| `test-http-api` | Axum driver: the same ports exposed as HTTP routes |
| Crate | Role |
| --------------- | ---------------------------------------------------- |
| `radicle-types` | Domain types, ports, adapters and the ts-rs bindings |
| `radicle-tauri` | Tauri driver: thin IPC wrappers around port methods |
| `test-http-api` | Axum driver: the same ports exposed as HTTP routes |
Both drivers depend on `radicle-types` and share no code with each other.
**Ports with default implementations.** Each port is a trait in
`radicle-types/src/traits/` whose methods have full default
implementations built on `Profile::profile()`. A driver gets the whole
behaviour by implementing `Profile` and declaring empty `impl` blocks, so
`AppState` (Tauri) and `Context` (HTTP) behave identically by construction.
Business logic goes in these defaults, never in a command handler or route.
`radicle-types/src/traits/` whose methods have full default implementations
built on `Profile::profile()`. A driver gets the whole behaviour by implementing
`Profile` and declaring empty `impl` blocks, so `AppState` (Tauri) and `Context`
(HTTP) behave identically by construction. Business logic goes in these
defaults, never in a command handler or route.
**Domain services for hot reads.** Where going through `radicle` is too
slow, a module in `radicle-types/src/domain/` defines its own storage port
and a generic `Service` over it. The `Sqlite` adapter in `src/outbound/`
implements those ports by querying Radicle's COB cache and notifications
database directly (read-only). Both drivers construct the services at
startup and use them for the matching list endpoints; everything else
keeps going through the ports. Releases are the exception: `radicle-artifact`
keeps its own SQLite cache of release COBs, so `list_releases` reads through
that instead of a domain service.
**Domain services for hot reads.** Where going through `radicle` is too slow, a
module in `radicle-types/src/domain/` defines its own storage port and a generic
`Service` over it. The `Sqlite` adapter in `src/outbound/` implements those
ports by querying Radicle's COB cache and notifications database directly
(read-only). Both drivers construct the services at startup and use them for the
matching list endpoints; everything else keeps going through the ports. Releases
are the exception: `radicle-artifact` keeps its own SQLite cache of release
COBs, so `list_releases` reads through that instead of a domain service.
**Parity is enforced.** Every Tauri command has a matching HTTP route.
`cargo test -p test-http-api --test parity` fails when a command, route or
frontend `invoke` has no counterpart, unless the command is listed in
`TAURI_ONLY` with a reason.
**Moving away from radicle-surf.** Repository browsing (trees, commit
history, diff structure) still goes through `radicle-surf`, and we intend
to replace it with our own code in `radicle-types`. Surf may not be
maintained in the long run, and we want finer control over performance and
features: the slow paths (diff stats, opening files, commit counts) already
bypass it with the `git` binary or `git2`. Owning this code behind a narrow
interface would also let us swap the git backend later, for example to
gitoxide. Surf is read-only and does no verification; trust comes from the
signed refs that `radicle` resolves before surf reads anything, so the
replacement doesn't have to preserve any security property. This is not
scheduled yet.
**Moving away from radicle-surf.** Repository browsing (trees, commit history,
diff structure) still goes through `radicle-surf`, and we intend to replace it
with our own code in `radicle-types`. Surf may not be maintained in the long
run, and we want finer control over performance and features: the slow paths
(diff stats, opening files, commit counts) already bypass it with the `git`
binary or `git2`. Owning this code behind a narrow interface would also let us
swap the git backend later, for example to gitoxide. Surf is read-only and does
no verification; trust comes from the signed refs that `radicle` resolves before
surf reads anything, so the replacement doesn't have to preserve any security
property. This is not scheduled yet.
+29 -29
View File
@@ -8,20 +8,20 @@ Accepted
## Context
Issue and patch text needs to point at repos, issues, patches, commits,
files and people. That text lives in COBs as plain text and is read by every client
(this app, radicle-explorer, the CLI, IDE plugins), each rendering it as it
sees fit.
Issue and patch text needs to point at repos, issues, patches, commits, files
and people. That text lives in COBs as plain text and is read by every client
(this app, radicle-explorer, the CLI, IDE plugins), each rendering it as it sees
fit.
References are mostly shared as explorer URLs today, which tie the content
to one instance and seed, and make clients reverse-parse a presentation URL.
RIP 4 (`rips/0004-general-uri-scheme`) defines a general `rad:` URI instead,
and heartwood is adopting it through the `radicle-uri` crate.
References are mostly shared as explorer URLs today, which tie the content to
one instance and seed, and make clients reverse-parse a presentation URL. RIP 4
(`rips/0004-general-uri-scheme`) defines a general `rad:` URI instead, and
heartwood is adopting it through the `radicle-uri` crate.
## Decision
**Store canonical identifiers, not URLs.** A reference is written into the
text as an absolute identifier:
**Store canonical identifiers, not URLs.** A reference is written into the text
as an absolute identifier:
| Entity | Identifier |
| ----------------- | -------------------------------------------------- |
@@ -38,36 +38,36 @@ text as an absolute identifier:
| Person | `did:key:<NID>` |
- Object ids are always full. The composer expands a prefix and offers every
match when several objects share it. It searches only delegate releases;
a full release id or link resolves any release.
match when several objects share it. It searches only delegate releases; a
full release id or link resolves any release.
- Identifiers are never relative to the current repo.
- Explorer URLs are accepted as input and normalised on insert. Where a URL
is ambiguous, as in `/tree/<branch>/<path>` with a branch containing
slashes, the repo's refs decide when the reference is written.
- Explorer URLs are accepted as input and normalised on insert. Where a URL is
ambiguous, as in `/tree/<branch>/<path>` with a branch containing slashes, the
repo's refs decide when the reference is written.
- Detail RIP 4 has no form for, such as a patch revision or tab or a list's
filters, is dropped. A page with no form at all, such as a log, stays a
plain explorer link.
filters, is dropped. A page with no form at all, such as a log, stays a plain
explorer link.
**One TypeScript library for the URI.** It lives in this repo with no
dependencies on the rest of the app, so radicle-explorer can adopt it. It
parses and formats all of RIP 4 plus `did:key:`, and maps identifiers to and
from explorer routes. It is tested against the RIP 4 vectors and
`radicle-uri`'s cases.
dependencies on the rest of the app, so radicle-explorer can adopt it. It parses
and formats all of RIP 4 plus `did:key:`, and maps identifiers to and from
explorer routes. It is tested against the RIP 4 vectors and `radicle-uri`'s
cases.
**Clients decide presentation.** This app shows repos, issues, patches,
releases, commits and people as chips, and every other entity above as a link
labelled with the repo name, such as `heartwood: src/lib.rs`. Either
navigates in-app when the repo is local and falls back to the configured
`publicExplorer`, which a right click also offers. A resource a client does
not support renders as a plain link. Sanitizers allow `rad:` and `did:`
hrefs, which cannot execute; this app also registers as the OS `rad:`
handler, so a link clicked elsewhere opens in it.
labelled with the repo name, such as `heartwood: src/lib.rs`. Either navigates
in-app when the repo is local and falls back to the configured `publicExplorer`,
which a right click also offers. A resource a client does not support renders as
a plain link. Sanitizers allow `rad:` and `did:` hrefs, which cannot execute;
this app also registers as the OS `rad:` handler, so a link clicked elsewhere
opens in it.
## Consequences
- References don't depend on any explorer instance or seed.
- Clients that don't understand `rad:` show the identifier or label without
a working link; radicle-explorer is one today.
- Clients that don't understand `rad:` show the identifier or label without a
working link; radicle-explorer is one today.
- Terminals such as kitty, iTerm2 and VTE only detect links of the form
`scheme://`, so a canonical `rad:<RID>/…` is not clickable there while the
equivalent `rad:///<RID>/…` is. Stored references and the app's "Copy rad:
@@ -8,75 +8,73 @@ Proposed
## Context
Releases and their artifacts are COBs, so anyone can create a release in a
repo they replicate, and anyone can register an artifact on any release,
including a delegate's. An artifact is a file a user downloads and may run.
A release that sits in a well-known repo gets some of that repo's trust in
the eyes of a user who doesn't know what a delegate is. This makes it easy
to trick a user into downloading something malicious.
Releases and their artifacts are COBs, so anyone can create a release in a repo
they replicate, and anyone can register an artifact on any release, including a
delegate's. An artifact is a file a user downloads and may run. A release that
sits in a well-known repo gets some of that repo's trust in the eyes of a user
who doesn't know what a delegate is. This makes it easy to trick a user into
downloading something malicious.
Trust is set at two levels:
- **Release:** its creator decides the title, tag and commit.
- **Artifact:** its author decides the bytes behind the CID.
The two can differ. A delegate's release can carry an artifact a
non-delegate registered, and a delegate can register an artifact on a
non-delegate's release.
The two can differ. A delegate's release can carry an artifact a non-delegate
registered, and a delegate can register an artifact on a non-delegate's release.
The app, like radicle-explorer, splits releases and artifacts into two
disjoint scopes by author: Delegates and Others. In the code the scopes are
`trusted` and `untrusted`. The discussion is in the
The app, like radicle-explorer, splits releases and artifacts into two disjoint
scopes by author: Delegates and Others. In the code the scopes are `trusted` and
`untrusted`. The discussion is in the
[Artifacts topic](https://radicle.zulipchat.com/#narrow/channel/444463-Desktop/topic/Artifacts/with/624009755)
on Zulip.
## Decision
**Trust follows delegates.** A release or artifact is trusted when its
creator or author is a delegate of the repo, and untrusted otherwise. The
UI keeps the labels Delegates and Others, as "Untrusted" reads as too
alarming for content that is often harmless.
**Trust follows delegates.** A release or artifact is trusted when its creator
or author is a delegate of the repo, and untrusted otherwise. The UI keeps the
labels Delegates and Others, as "Untrusted" reads as too alarming for content
that is often harmless.
**Warn where untrusted content shows.** A short warning
(`UntrustedWarning.svelte`) says the content is not from a delegate and to
download it only if the user trusts its author. It stays small, so it
informs without alarm. It shows:
download it only if the user trusts its author. It stays small, so it informs
without alarm. It shows:
- above the Others releases list;
- on a release by a non-delegate, for the whole release;
- on a delegate's release, while it shows artifacts by non-delegates;
- in the download popover of an artifact by a non-delegate, whatever the
release, because that is where the user acts;
- in the browser tab of a delegate's artifact, while it lists links added
by non-delegates, as those downloads are not checked against the CID.
- in the browser tab of a delegate's artifact, while it lists links added by
non-delegates, as those downloads are not checked against the CID.
**Count only delegate attestations.** The attestation badge on an artifact
counts delegates only, as anyone can make keys that attest their own
artifact. The full list still shows every attestation.
counts delegates only, as anyone can make keys that attest their own artifact.
The full list still shows every attestation.
**Keep untrusted content visible.** Others' releases and artifacts stay
listed by default, behind their own filter.
**Keep untrusted content visible.** Others' releases and artifacts stay listed
by default, behind their own filter.
## Alternatives considered
- **Hide Others by default**, behind a global setting. This protects users
best, and avoids showing links to malware at all, which is a reputation
risk a warning doesn't remove. It also hides legitimate contributions,
such as builds by a release manager who is not a delegate. It is still
open.
- **Rename Delegates to Official** or Others to Untrusted. This changes
only the wording and leaves the warning to a single label.
- **Hide Others by default**, behind a global setting. This protects users best,
and avoids showing links to malware at all, which is a reputation risk a
warning doesn't remove. It also hides legitimate contributions, such as builds
by a release manager who is not a delegate. It is still open.
- **Rename Delegates to Official** or Others to Untrusted. This changes only the
wording and leaves the warning to a single label.
- **A list of trusted publishers in the repo identity**, like canonical ref
rules. This lets non-delegates publish trusted releases, but adds a
second trust model. Linking a release to a canonical annotated tag gives
part of this already, so canonical refs are the preferred path.
rules. This lets non-delegates publish trusted releases, but adds a second
trust model. Linking a release to a canonical annotated tag gives part of this
already, so canonical refs are the preferred path.
## Consequences
- Users see a warning before they download an untrusted artifact, also when
it sits on a trusted release.
- A trusted artifact on an untrusted release still shows the release
warning, as its title, tag and commit are not trusted.
- Delegation is the only trust signal. Release managers who are not
delegates show as Others until releases can use canonical ref rules.
- Users see a warning before they download an untrusted artifact, also when it
sits on a trusted release.
- A trusted artifact on an untrusted release still shows the release warning, as
its title, tag and commit are not trusted.
- Delegation is the only trust signal. Release managers who are not delegates
show as Others until releases can use canonical ref rules.
- radicle-explorer should show the same warnings so that both clients agree.
+16 -17
View File
@@ -1,29 +1,28 @@
# Testing checklist
Go through this list for every feature or bug fix. Tick an item when it's
covered, or say in the commit or patch description why it doesn't apply.
The strategy behind it is in [ADR 1](adr/0001-testing-strategy.md).
covered, or say in the commit or patch description why it doesn't apply. The
strategy behind it is in [ADR 1](adr/0001-testing-strategy.md).
## Bug fixes
- [ ] The fix comes with a regression test that fails without it, written
at the cheapest layer that reproduces the bug.
- [ ] The fix comes with a regression test that fails without it, written at the
cheapest layer that reproduces the bug.
## Unit (`tests/unit/`)
- [ ] New or changed pure logic in `src/lib/` has unit tests.
- [ ] Non-trivial logic that was added inside a component (filtering,
grouping, sorting, parsing) has been moved into `src/lib/` and tested.
One-line helpers with a single caller stay where they are.
- [ ] Tests assert behaviour, not UI copy, CSS, selector strings or copies
of constant tables.
- [ ] Non-trivial logic that was added inside a component (filtering, grouping,
sorting, parsing) has been moved into `src/lib/` and tested. One-line
helpers with a single caller stay where they are.
- [ ] Tests assert behaviour, not UI copy, CSS, selector strings or copies of
constant tables.
- [ ] Each new test was seen to fail when the logic it covers was broken.
- [ ] Edge cases are covered: empty input, a single item, invalid input,
boundaries.
- [ ] New routes or URL parameters are covered by the router round-trip
tests.
- [ ] New `localStorage` schemas have tests for their defaults and for
invalid stored values.
- [ ] New routes or URL parameters are covered by the router round-trip tests.
- [ ] New `localStorage` schemas have tests for their defaults and for invalid
stored values.
## Rust (`crates/`)
@@ -35,11 +34,11 @@ The strategy behind it is in [ADR 1](adr/0001-testing-strategy.md).
- [ ] A new Tauri command has a matching route in `crates/test-http-api`
(enforced by `cargo test -p test-http-api --test parity`).
- [ ] A new write path, meaning any command that changes a COB, a repo or
the node's state, has a happy-path E2E test, even when its logic is
- [ ] A new write path, meaning any command that changes a COB, a repo or the
node's state, has a happy-path E2E test, even when its logic is
unit-tested in `src/lib/`.
- [ ] Actions limited to authors or delegates have a test for the user who
isn't allowed.
- [ ] Actions limited to authors or delegates have a test for the user who isn't
allowed.
- [ ] New persisted UI state survives a reload.
- [ ] New keyboard shortcuts are exercised at least once.