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 -- dev is 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 sidecar is 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-features

npm 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 sidecar

A 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 dmg

The 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.toml

Changing 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/.