Documentation

Contributing

Contributing

This page is for people who change the Cumaru CLI or its domains. To use Cumaru, start with Set up your project instead.

1. Get the source

git clone https://github.com/rntgspr/cumaru.git
cd cumaru

You need a stable Rust toolchain with Cargo and rustfmt, plus Git, cURL, and Bash.

2. Build and run

bash src/build.sh

The binary is target/release/cumaru. A local build does not make install or update read your local domains; they still read GitHub main.

For a development link, point ~/.local/bin/cumaru at the build. Rebuild to refresh it; never run cumaru upgrade to refresh a development build.

3. Know the layout

  • src/main.rs parses and dispatches; src/commands/ holds one module per command.
  • domains/__base/ holds the kernel, universal skills, launchers, and disciplines.
  • domains/<name>/ holds each self-contained domain.
  • schemas/config.schema.json is the embedded config contract.
  • models/catalog.json lists supported models; weights download separately.

4. Verify your change

cargo fmt --manifest-path Cargo.toml --check
cargo test --manifest-path Cargo.toml --locked
bash src/build.sh
./target/release/cumaru --version
./target/release/cumaru help
git diff --check
scripts/sync-domain-kernel.sh --check
bash tests/run.sh
  • Universal artifacts must be byte-identical across domains; the sync script checks this in CI.
  • Use disposable projects and cache roots for write tests. Never use a real global install or uninstall as routine verification.
  • Process tests use ShellSpec and replace network access with a pinned source stub.

Release boundaries

  • A plain numeric tag push runs the release workflow. It checks the tag against Cargo.toml and builds four targets before publishing.
  • src/install.sh downloads release assets; it never compiles source.
  • The Homebrew formula lives in packaging/homebrew/ and publishes to rntgspr/homebrew-tap.

Sources: HOW_TO_DEV.md, docs/rust.md, Homebrew packaging, architecture.