Appearance
Commands
Everything runs from the repository root. apps/* have their own scripts, but the root wraps them.
Running it
| Command | What it does |
|---|---|
pnpm dev:server | The API and collaboration socket on :3211, with a watcher |
pnpm dev | The web app on :3210 |
pnpm build:web | Production build of the web app |
pnpm start:web | Serve that build on :3210 |
pnpm dev:server:auth | The server with sign-in required and links written to a file — for the auth browser suites |
Stop the dev server with pkill -f tsx, not by killing whatever holds the port — that process is a child, and the watcher respawns it.
Checks
| Command | What it checks |
|---|---|
pnpm test | Every unit and integration suite. pnpm test <filter> runs one |
pnpm typecheck | tsc over the packages, the server and the scripts, then the web app |
pnpm typecheck:web | Only the web app's half of that |
pnpm test:watch | The unit suites, re-run as files change |
pnpm check:invariants | Markdown libraries stay confined to one package — one projection, three consumers |
pnpm check:tenancy | No control-plane query may read a tenant table |
pnpm check:postgres | The store suite against a throwaway Postgres, including a connection as a role that owns nothing |
pnpm pilot | Imports this repository's own docs and uses them: every file written, at least 97% of local links becoming page links, at least 80% of files exported back to their own path, search finding a document by its subject, and nothing recorded when every page is read twice |
pnpm report:fidelity | Regenerates the fidelity table from the block registry |
pnpm report:openapi | Regenerates docs/openapi.json and this site's HTTP API page from the route catalogue |
Browser suites
Playwright, and both processes must already be serving — they are much steadier against pnpm build:web && pnpm start:web than against pnpm dev. Each suite creates its own page (and some their own workspace), so runs do not interfere.
Against pnpm dev:server — the ones marked ✓ are what pnpm smoke:all runs:
| Command | What it drives | smoke:all |
|---|---|---|
pnpm smoke:web | The editor: input rules, slash menu, clipboard, persistence | ✓ |
pnpm smoke:format | Words: the selection bar, links, a code block's language and Copy, images from /, find and replace, folding | ✓ |
pnpm smoke:devteam | A software team's pages: a fence's file name and a diff, short references, decision records, a page read as a log | ✓ |
pnpm smoke:highlight | Code highlighting, as drawn | ✓ |
pnpm smoke:math | Rendered mathematics | ✓ |
pnpm smoke:diagram | Drawn diagrams | ✓ |
pnpm smoke:pages | The page tree: create, switch, rename, trash, restore | ✓ |
pnpm smoke:navigation | Breadcrumbs, recent pages, moving pages in the tree, Back to the timeline | ✓ |
pnpm smoke:templates | Starting a page from a template | ✓ |
pnpm smoke:archive | Archiving a page, and bringing it back | ✓ |
pnpm smoke:freshness | The review badge on a page due a look | ✓ |
pnpm smoke:collab | Two browsers converging, attribution, replay | ✓ |
pnpm smoke:saving | The save indicator telling the truth, a lost response retried once, two tabs | ✓ |
pnpm smoke:timeline | The thesis in a browser: journal, timeline, provenance, revert | ✓ |
pnpm smoke:links | [[page]] links, backlinks, search, embeds, unlinked mentions | ✓ |
pnpm smoke:references | Names, regions and references between pages, in both editors and the export | ✓ |
pnpm smoke:search | Search on its own page: grouped by page, the options, the address, a result opened at its block | ✓ |
pnpm smoke:markdown | A Markdown-first page: switching, typing, block leases, clashes, offline, keeping formatting | ✓ |
pnpm smoke:preview | Live preview on a Markdown page | ✓ |
pnpm smoke:inbox | The inbox panel | ✓ |
pnpm smoke:comments | Commenting, and what happens to an anchor when the text changes | ✓ |
pnpm smoke:files | Dropping an attachment, and how the server serves it back | ✓ |
pnpm smoke:import | Importing a Logseq graph: preview, pages, image, block ref, links | ✓ |
pnpm smoke:views | A database view and its board | ✓ |
pnpm smoke:review | Proposing a change, and deciding it block by block | ✓ |
pnpm smoke:outline | Rearranging sections, and the block ids surviving it | ✓ |
pnpm smoke:offline | Writing with the network cut, and the dates surviving it | ✓ |
pnpm smoke:print | What the print stylesheet actually produces | ✓ |
pnpm smoke:responsive | Every pane reachable at desktop, laptop and phone widths | ✓ |
pnpm smoke:stability | Nothing moves or closes under the person: typing through saves, menus while a peer edits | ✓ |
pnpm smoke:tenancy | Two workspaces, and the boundary between them, through the consoles | ✓ |
pnpm smoke:agent | An agent's whole loop: read, suggest, be refused, a person decides | ✓ |
pnpm smoke:stars | Starred pages, signed in | ✓ |
pnpm smoke:mattermost | A Mattermost webhook made in the console, and heard from | ✓ |
smoke:agent, smoke:stars and smoke:mattermost sign in, so they need the server started with NOTESFLOW_LINK_LOG=/tmp/notesflow-links.txt.
Against pnpm dev:server:auth (sign-in required, links written to a file), run on their own:
| Command | What it drives |
|---|---|
pnpm smoke:auth | The sign-in flow |
pnpm smoke:permissions | Sharing a page between two browsers |
pnpm smoke:workspaces | Asking for a workspace, and an operator approving it |
pnpm smoke:sites | Publishing a page as a site: the sitemap review, the audience, signing in and coming back |
pnpm smoke:subdomains | A site on its own subdomain — also needs NOTESFLOW_SITES_DOMAIN=sites.localhost and NOTESFLOW_API_URL=http://localhost:3211 |
pnpm smoke:settings | Settings: name, inbox switches, a new address, signing out a device, leaving, deleting the account |
pnpm smoke:passwords | A password account: sign-up, signing in, two-step sign-in, a reset, a recovery code |
Two notes that save an afternoon:
- Chromium is expected at
/usr/bin/chromium-browser; override withCHROMIUM_PATH. - The suites that sign in spend sign-in links against a per-process limiter (ten per caller per ten minutes). Running them repeatedly means restarting the server between batches; the symptom is "No sign-in link arrived".
Markdown and git
| Command | What it does |
|---|---|
pnpm export:git [dir] | The workspace as a git repository of .md files |
pnpm mirror:git [dir] | The same, continuously. --once for a cron job |
pnpm merge:git [dir] | Reconcile externally edited .md back in. --apply to write, --propose to send for review |
pnpm import:md <dir> | A folder, an Obsidian vault or a Logseq graph in. Previews unless --apply — see importing |
All four need the server running. See Markdown and git.
Database
| Command | What it does |
|---|---|
pnpm migrate | Apply pending migrations to a real Postgres, as its owner. Safe to run from several places at once |
pnpm migrate --status | Which migrations the database has and which are pending; changes nothing. Exits 2 while any are pending |
pnpm migrate --role <name> --password '…' | Migrate, and create the unprivileged role the server should run as |
pnpm backup:verify <backup.tar.gz> | Restore a PGlite backup into a scratch directory and read it back: its manifest, schema version, counts, and attachments missing their bytes |
pnpm restore <backup.tar.gz> <empty dir> | Restore a PGlite backup into a new data directory. Never overwrites |
pnpm backup:keygen <key file> | Make an age key pair for copies off the host, as age-keygen does. Prints the recipient to set; keep the file off the server. Never overwrites |
pnpm backup:decrypt <backup.tar.gz.age> <key file> | Decrypt a copy downloaded from the bucket, as age -d does, and put its manifest beside it for backup:verify. Never overwrites |
pnpm repair:read-edits [--apply] | Set aside edits that were only somebody reading (see operations). Previews unless --apply |
Benchmarks
| Command | What it measures |
|---|---|
pnpm bench:timeline | Timeline query latency at 100k ops |
pnpm bench:scope | What a workspace-scoped statement costs over an unscoped one |
pnpm bench:git-export | Export determinism, and repository growth over 90 commits |
pnpm bench:growth | What the append-only log costs as it grows, and rebuilding a page from it |
This site
| Command | What it does |
|---|---|
pnpm docs:dev | This documentation site, with live reload |
pnpm docs:build | Build it into site/.vitepress/dist |
pnpm docs:preview | Serve that build |