Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Development

Prerequisites

To build and test a checkout, you need:

ToolNeeded forInstall
Rust (stable), with clippy and rustfmtEverything. CI uses the latest stable, and the repo doesn’t pin a version, so keep yours currentrustup, then rustup update stable and rustup component add clippy rustfmt
Node.js 22.12 or newer, with npmAny cargo build or cargo test, because crates/braid/build.rs builds the web UI, and the UI testsnodejs.org or your version manager
minisigncargo test: the installer tests fail if it’s missingbrew install minisign, apt install minisign, dnf install minisign, or apk add minisign

The first build also needs network access, to download crates and run npm ci. Setting SKIP_UI_BUILD=1 lets you build without Node.js, but braid ui then serves a stub page unless ui/dist/ has already been built.

These are only needed for specific tasks:

ToolNeeded forInstall
tauri-clicargo xtask viewer-dev, cargo xtask viewer-buildcargo install tauri-cli --version '^2' --locked; Linux also needs the system packages
mdbookcargo xtask docs, cargo xtask docs-servecargo install mdbook
cargo-auditThe housekeeping advisories checkcargo install cargo-audit --locked
cargo-macheteThe housekeeping unused checkcargo install cargo-machete --locked
lycheeThe housekeeping links checkcargo install lychee --locked or brew install lychee

Building and testing

cargo xtask ci    # the same pipeline as CI: fmt --check, clippy, build, tests, UI tests
cargo xtask fmt   # apply formatting
cargo test        # just the Rust tests (default members only)

Run cargo xtask ci before pushing. To have that happen automatically, install a pre-push hook with cargo xtask install-hooks.

The workspace has five crates: braid-core (schema, automerge hydrate/reconcile, ready/blocked logic — no I/O), braid (CLI, config discovery, cache, sync), braid-config (lean config/registry shared by braid and braid-viewer), xtask (repo automation, std-only), and braid-viewer (Tauri desktop app, excluded from default builds — use cargo xtask viewer-* or -p braid-viewer). Design decisions and phase history live in claude-notes/plans/2026/06/03/braid-design-kickoff.md; vocabulary in terminology. This repo dogfoods braid — run braid list here to see its own skein.

Housekeeping report

cargo xtask housekeeping prints a Markdown report of periodic repo chores. It never changes the repo, runs no dependency code (no build scripts or proc macros), and doesn’t touch your skein, so it’s safe to run on a dependency bump nobody has reviewed yet.

cargo xtask housekeeping                     # everything, comparing to origin/main
cargo xtask housekeeping --offline           # skip anything needing the network
cargo xtask housekeeping --only lockfile,links
cargo xtask housekeeping --base <ref>        # compare lockfiles to another ref
CheckReportsNeeds
lockfileCrates changed since the base ref, flagging build scripts, proc macros, non-crates.io sources, changed checksums, and versions published under 7 days ago
updatesAvailable Cargo updatesnetwork
advisoriesRustSec advisoriescargo-audit
unusedPossibly unused dependenciescargo-machete
npm-lockfileui/ packages changed since the base ref, flagging install scripts, non-npmjs sources, changed checksums, and versions published under 7 days ago
npm-outdated, npm-auditState of ui/ dependenciesnpm, network
linksBroken links in the docslychee
actionsGitHub Actions in use, flagging mixed versions
suppressions#[allow], #[ignore], TODO and FIXME in Rust files
notesHOUSEKEEPING: comments left for future runs, in any tracked file except Markdown

Install commands are under Prerequisites. A check whose tool is missing shows as skipped in the summary rather than passing. The command exits 0 when every check ran, even with findings or skips, 1 if a check failed to run, and 2 on a usage error.

Building these docs

This site is an mdBook built from the docs/ directory (book.toml at the repo root, docs/SUMMARY.md is the table of contents):

cargo xtask docs            # build to book/
cargo xtask docs-serve      # live-reload preview at http://localhost:3000

Every docs/*.md page must be listed in docs/SUMMARY.md — a drift test (crates/braid/tests/docs_drift.rs) fails the build otherwise. Pushes to main publish the site via .github/workflows/docs.yml.