Contributing to Speedwave
Speedwave’s core is open. If you want to fix a bug, add a platform, or improve the docs, start with development setup to get Rust, Node.js, and the platform tools running, then check testing before you open a pull request.
The Makefile is the entry point for everything: make setup-dev installs dependencies, make dev starts the desktop app in hot-reload mode, and make check-all runs the full quality gate (check, meaning lint, clippy, type-check, and format, plus tests, coverage, and a dependency audit). Do not call cargo or npm directly. The Makefile keeps working directories and flags consistent across the Rust crates, the Angular frontend, and the MCP servers.
Engineering principles
Section titled “Engineering principles”A short version of the rules that shape the codebase:
- KISS. Speedwave is a thin orchestration layer over Lima, nerdctl, and containerd, not a reimplementation of them. Call the right existing tool rather than building a custom one.
- YAGNI. Build what the implementation plan asks for.
speedwave logs,status, andstopare not CLI subcommands because the Desktop GUI already covers them. - DRY. Duplicated logic moves to
speedwave-runtime(ormcp-servers/shared/for MCP code). Catalogues with a single source of truth, like Anthropic model strings, get edited at that source, not at each call site. - SOLID. Each runtime type has one job (
ContainerRuntimeonly manages containers), platforms add new implementations without touching callers (LimaRuntime,WslRuntime), and callers depend on theLockedRuntimeinterface rather than a specific platform. - Rule of three. Don’t extract an abstraction until a pattern shows up a third time.
Logging follows its own rules: all Rust code goes through the log crate facade, never eprintln!/println! for diagnostics, and every log sink runs through the secret sanitizer in log_sanitizer.rs before anything reaches a file, stderr, or the desktop webview.
The git workflow has a hard line too: never bypass a git hook, never merge with --admin or a weakened branch protection rule, and never mark a failing check as expected. Every commit ships its tests alongside the code, covering happy paths, edge cases, error paths, and state transitions where they apply. Skipped tests are not allowed; a failing test gets fixed or removed. Follow the Boy Scout Rule: fix small bugs, typos, and dead code you encounter along the way, and report anything too large for the current change instead of leaving a TODO comment.