Build

Stable Rust. The engine workspace is stdlib-only. No crates.io deps in crates/.

Engine

# From repo root
cargo test --workspace
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Useful one-offs:

cargo run -p eelgrass-cli -- lex "orders |> filter status == .pending"
cargo run -p eelgrass-cli -- run path/to/queries.eel

Wasm profile and targets

Workspace profile wasm-size (root Cargo.toml) inherits release with opt-level = "z", LTO, single codegen unit, panic = "abort", strip.

rustup target add wasm32-unknown-unknown

cargo build --profile wasm-size --target wasm32-unknown-unknown -p eelgrass-lang
cargo build --profile wasm-size --target wasm32-unknown-unknown -p eelgrass-wasm

eelgrass-lang is the language/intel artifact; eelgrass-wasm is the browser session engine (mem + OPFS). Both must stay green. CI builds them every merge.

Studio / playground

cd clients/studio
npm ci
npm run build:wasm          # lang + wasm crates, then copy artifacts
npm run dev                 # Studio against a local eelgrass serve
npm run dev:playground      # in-tab wasm UI; open /?local=1
npm run test:unit           # builder IR tripwire (queryBuilder.test.ts)
npm run test:e2e            # Playwright: serve Studio via STUDIO_URL

Deploy-shaped build (what Tamer runs for play.eelgrass.dev):

npm run build:deploy

test:unit and playground-mobile Playwright (PLAYGROUND_URL, preview with VITE_PLAYGROUND=1) are outside the main CI e2e harness today. See Testing.

Public docs (VitePress)

cd docs
npm ci
npm run dev                 # local preview
npm run build               # must succeed in CI

mermaid code fences render through vitepress-mermaid-viewer plus the mermaid package (docs devDependencies). Wired in docs/.vitepress/config.ts via withMermaid. Mobile polish lives in docs/.vitepress/theme/mermaid.css. Tap a diagram to expand; pinch to zoom.

npm run build does not execute Mermaid. Parse every fence before merge:

cd docs && npm run check:mermaid   # also runs in the CI docs job

Gotchas that produce the red "Syntax error in text" SVG:

• sequenceDiagram + ; — a bare semicolon ends the statement. Do not put ; inside messages or notes (including inside atomic { … } examples). Prefer —, …, or the entity #59; if you need a visible semicolon.
• Prefer quoted labels when text has @, &, or other special characters (A["Schemas-as-code @vN"]). Unquoted forms often parse today but are brittle across Mermaid majors.
• Subgraphs: prefer subgraph id ["Title"] over a bare quoted title.

From repo root: npm run docs:dev / docs:build (see root package.json).

CI overview

Workflows under .github/workflows/:

Workflow	When	What
ci.yml PR gate	every PR	Parallel rust (fmt, clippy -D warnings, cargo test --workspace) + docs (VitePress). Aggregator job check must be green. Target wall clock ≤ ~3 min.
ci.yml heavy	push to apex, workflow_dispatch	Parallel: stress smoke, sim (200 seeds), fuzz-smoke (60s), wasm-size (eelgrass-lang + eelgrass-wasm), Studio Playwright, Miri on eelgrass-storage (skips async pager stress; MIRIFLAGS=-Zmiri-disable-isolation)
tamer-prod-deploy.yml	push to apex / manual	Tamer apply + deploy --env prod (docs + playground Workers)
tamer-pr-preview.yml	PR open/sync	Preview env pr-<n> + comment URLs
tamer-pr-cleanup.yml	PR closed	tamer destroy that preview env

Run the heavy suite locally or via Actions → CI → Run workflow before merging risky Studio / storage / wasm changes. Maintainer harnesses (not product CLI):

cargo run -p eelgrass-stress --release -- --profile smoke
cargo run -p eelgrass-sim --release -- --seed-start 1 --count 200 --ops 80
cargo run -p eelgrass-fuzz-smoke --release   # EELGRASS_FUZZ_SMOKE_SECS=60 in CI

See Testing and Deploy.