nvrl
4eb663e2d7
The README grew a section per feature and is a good reference, but nothing said where to begin. docs/wiki now has a getting-started page, a guide that walks through one day with the workspace and explains each part where it comes up, and a page per part of the app, each with screenshots of what it describes. Three pages are read out of the code rather than written, so they cannot drift from it: the keys and commands from Help.svelte and commands.ts, the same lists `:help` draws; the settings from .env.example, which gains a heading for the vault, trash and history settings so they no longer sit under mail; and the API from the README's table. `make wiki` writes them, and `--check` fails when one is stale or a link between pages leads nowhere. `--publish` lays the pages out for a GitHub wiki: links without `.md`, images beside them, `[[` escaped so the wiki does not take a command's help text for a link to a page. The screenshots are taken by `make screenshots`: the debug binary on a temporary data directory, with a password made up for the run, filled with an example workspace over the API, and a headless Chromium driven over the DevTools protocol through the views the docs show. Nothing outside the temporary directory is touched but docs/images, and the pictures are cut to 256 colours, a third of their size, which a dark UI does not show. The README opens with the banner, a CI badge, the guide, the features grouped by what they are for, and six of the screenshots.
3.7 KiB
Development
Running it from source
make dev-api # cargo run, serving the API on :4242
make dev-web # vite on :4243, proxying /api to :4242
Open http://127.0.0.1:4243. The Rust build embeds web/dist, so build the
frontend once (cd web && bun install && bun run build) before the first
cargo build; a debug build reads web/dist from disk after that.
Point WORKSPACE_DATA_DIR at a throwaway directory while trying things, so the
real data stays out of it.
The code
| where | what |
|---|---|
src/main.rs |
start-up, the router, security headers, background loops |
src/routes/ |
one module per area of the API: nodes, boards, trash, revisions, links, capture, diary, media, file_text, seal, share, import, export … |
src/sftp/ |
the SFTP mount |
src/backup/ |
the Proton Drive mirror |
src/mail/, src/notify/ |
the outbox, and what is worth a mail |
src/vault.rs |
the vault's keys and file format |
src/sweep.rs |
the daily clean-up: trash, old versions, unreferenced uploads |
migrations/ |
the SQLite schema, one numbered file per change |
web/src/App.svelte |
the keys |
web/src/lib/store.svelte.ts |
the client's state, and every call to the API |
web/src/lib/commands.ts |
the : commands |
web/src/lib/Help.svelte |
the ? screen |
The database is one SQLite file with FTS5 for search. Every migration is
applied at start, after a copy of the database is kept as
diary.db.pre-<version>. Many rules are enforced by triggers as well as in the
code, so no path can break them: a sealed file has no indexed text, a file in a
sealed folder is sealed, the diary cannot be deleted.
Checks
make check
runs what CI runs:
cargo fmt --checkcargo clippy --all-targets -- -D warningscargo testbun run checkinweb/(svelte-check)
The Rust tests run against an in-memory database; most modules have a test block at the bottom.
CI
.github/workflows/ci.yml runs on every push and pull request:
- rust: builds the frontend (the binary embeds it), then format, clippy and the tests;
- web: svelte-check;
- docs: checks that the generated wiki pages are up to date and that every link between the pages resolves.
.github/workflows/wiki.yml publishes docs/wiki to the GitHub wiki on every
push to main that changes it, or changes a file the generated pages are read
from.
The wiki
The pages live in docs/wiki and the pictures in docs/images. Edit them
there; an edit on GitHub's wiki page is overwritten by the next publish.
Three pages are generated by scripts/wiki.ts:
| page | read from |
|---|---|
| Keys and commands | web/src/lib/Help.svelte and web/src/lib/commands.ts |
| Configuration | .env.example |
| API | the API section of README.md |
After changing one of those, run make wiki and commit the result. CI fails
when they are stale.
Links between pages are written as Page-Name.md so that they work when the
files are read in the repository; the publish step drops the .md for the
wiki.
Screenshots
make screenshots
builds the app, starts it on a temporary data directory with a password made
up for the run, fills it with an example workspace, and drives a headless
Chromium through the views the docs show. The pictures are written to
docs/images. It needs chromium on the path (or CHROMIUM=/path/to/chrome),
and shrinks the pictures with ImageMagick when it is installed.
Conventions
- One finished feature per commit, with the README,
:helpand the tests in the same commit. - Commit messages are
area: a sentence, followed by prose about why. - Comments explain why, not what.