Skip to content

Commands ​

Everything runs from the repository root. apps/* have their own scripts, but the root wraps them.

Running it ​

CommandWhat it does
pnpm dev:serverThe API and collaboration socket on :3211, with a watcher
pnpm devThe web app on :3210
pnpm build:webProduction build of the web app
pnpm start:webServe that build on :3210
pnpm dev:server:authThe 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 ​

CommandWhat it checks
pnpm testEvery unit and integration suite. pnpm test <filter> runs one
pnpm typechecktsc over the packages, the server and the scripts, then the web app
pnpm typecheck:webOnly the web app's half of that
pnpm test:watchThe unit suites, re-run as files change
pnpm check:invariantsMarkdown libraries stay confined to one package — one projection, three consumers
pnpm check:tenancyNo control-plane query may read a tenant table
pnpm check:postgresThe store suite against a throwaway Postgres, including a connection as a role that owns nothing
pnpm pilotImports 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:fidelityRegenerates the fidelity table from the block registry
pnpm report:openapiRegenerates 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:

CommandWhat it drivessmoke:all
pnpm smoke:webThe editor: input rules, slash menu, clipboard, persistence✓
pnpm smoke:formatWords: the selection bar, links, a code block's language and Copy, images from /, find and replace, folding✓
pnpm smoke:devteamA software team's pages: a fence's file name and a diff, short references, decision records, a page read as a log✓
pnpm smoke:highlightCode highlighting, as drawn✓
pnpm smoke:mathRendered mathematics✓
pnpm smoke:diagramDrawn diagrams✓
pnpm smoke:pagesThe page tree: create, switch, rename, trash, restore✓
pnpm smoke:navigationBreadcrumbs, recent pages, moving pages in the tree, Back to the timeline✓
pnpm smoke:templatesStarting a page from a template✓
pnpm smoke:archiveArchiving a page, and bringing it back✓
pnpm smoke:freshnessThe review badge on a page due a look✓
pnpm smoke:collabTwo browsers converging, attribution, replay✓
pnpm smoke:savingThe save indicator telling the truth, a lost response retried once, two tabs✓
pnpm smoke:timelineThe thesis in a browser: journal, timeline, provenance, revert✓
pnpm smoke:links[[page]] links, backlinks, search, embeds, unlinked mentions✓
pnpm smoke:referencesNames, regions and references between pages, in both editors and the export✓
pnpm smoke:searchSearch on its own page: grouped by page, the options, the address, a result opened at its block✓
pnpm smoke:markdownA Markdown-first page: switching, typing, block leases, clashes, offline, keeping formatting✓
pnpm smoke:previewLive preview on a Markdown page✓
pnpm smoke:inboxThe inbox panel✓
pnpm smoke:commentsCommenting, and what happens to an anchor when the text changes✓
pnpm smoke:filesDropping an attachment, and how the server serves it back✓
pnpm smoke:importImporting a Logseq graph: preview, pages, image, block ref, links✓
pnpm smoke:viewsA database view and its board✓
pnpm smoke:reviewProposing a change, and deciding it block by block✓
pnpm smoke:outlineRearranging sections, and the block ids surviving it✓
pnpm smoke:offlineWriting with the network cut, and the dates surviving it✓
pnpm smoke:printWhat the print stylesheet actually produces✓
pnpm smoke:responsiveEvery pane reachable at desktop, laptop and phone widths✓
pnpm smoke:stabilityNothing moves or closes under the person: typing through saves, menus while a peer edits✓
pnpm smoke:tenancyTwo workspaces, and the boundary between them, through the consoles✓
pnpm smoke:agentAn agent's whole loop: read, suggest, be refused, a person decides✓
pnpm smoke:starsStarred pages, signed in✓
pnpm smoke:mattermostA 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:

CommandWhat it drives
pnpm smoke:authThe sign-in flow
pnpm smoke:permissionsSharing a page between two browsers
pnpm smoke:workspacesAsking for a workspace, and an operator approving it
pnpm smoke:sitesPublishing a page as a site: the sitemap review, the audience, signing in and coming back
pnpm smoke:subdomainsA site on its own subdomain — also needs NOTESFLOW_SITES_DOMAIN=sites.localhost and NOTESFLOW_API_URL=http://localhost:3211
pnpm smoke:settingsSettings: name, inbox switches, a new address, signing out a device, leaving, deleting the account
pnpm smoke:passwordsA 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 with CHROMIUM_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 ​

CommandWhat 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 ​

CommandWhat it does
pnpm migrateApply pending migrations to a real Postgres, as its owner. Safe to run from several places at once
pnpm migrate --statusWhich 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 ​

CommandWhat it measures
pnpm bench:timelineTimeline query latency at 100k ops
pnpm bench:scopeWhat a workspace-scoped statement costs over an unscoped one
pnpm bench:git-exportExport determinism, and repository growth over 90 commits
pnpm bench:growthWhat the append-only log costs as it grows, and rebuilding a page from it

This site ​

CommandWhat it does
pnpm docs:devThis documentation site, with live reload
pnpm docs:buildBuild it into site/.vitepress/dist
pnpm docs:previewServe that build

Blocks and the op log are canonical. Markdown is a projection. Git is a target.