Build and run
Everything ships from source. There is no binary, no installer and no update channel today, so this is also the installation path.
Prerequisites
- macOS, Apple silicon or Intel. It is the only supported platform for now.
- Node.js 22.18 or newer, with npm.
- A Rust toolchain, installed with rustup.
- The Xcode command line tools.
Development
npm ci # install from the lockfile
npm run tauri -- dev # the app, with the Vite server on 127.0.0.1:1420
npm run dev # Vite only, if you open the renderer in a browser
npm run sidecar # rebuild the MCP bridge (debug)npm run tauri -- devis the normal loop: it starts Vite on port 1420 and opens the Tauri window.- A Rust change triggers a rebuild and a window restart; the workspace is restored on the next launch.
npm run sidecaris only needed when the bridge, the protocol or the tool list changes.
Checks before shipping
npm run typecheck
npm run lint
npm test
cargo fmt --manifest-path src-tauri/Cargo.toml -- --check
cargo test --manifest-path src-tauri/Cargo.toml --lib
cargo build --manifest-path src-tauri/Cargo.toml --no-default-featuresnpm test runs with node --experimental-strip-types. Avoid enums, parameter properties and decorators in any file imported by the tests: they are not stripped.
The Node tests cover the workspace, the registry, extensions, the brief, the data tiles, OpenAlex, versions and Store navigation. The Rust tests cover storage, packages (folder, zip, checksum, source), the terminal, agents, the explorer, PDF and migrations.
After an MCP change
If src-tauri/src/bin/spark-mcp.rs, the protocol or the tool list changes, rebuild the bridge so clients get the new binary:
npm run sidecarA client that is already connected keeps its cached tool list and may need a new session to see a new core tool.
Release
npm run sidecar:release
npm run tauri -- build --bundles dmgThe DMG is unsigned and not notarised. macOS will ask you to confirm on first open, and there is no update channel: a new version means a new build.
Formatting
npm run format
cargo fmt --manifest-path src-tauri/Cargo.tomlChanging a contract
The code wins, but a contract change (SDK, manifest, registry index, Tauri command, storage format) updates the matching document in doc/ in the same change. A structural decision gets an entry in doc/decisions/.