hopeless/labs

Blog

Three repos become one: the Ruso unification

jeagercoder4 min read
ecosystemannouncementinfrastructure

The Ruso project started as three separate repositories: ruso-runtime, ruso-cli, and ruso-registry. Each had its own release cycle, its own CI pipeline, and its own issue tracker. That separation made sense when they were evolving independently. It stopped making sense when a security fix needed coordinated releases across all three.

Starting today, Ruso ships as one.

What changed

The repositories merged into a single monorepo. The runtime, CLI, and registry are still distinct packages (this is a packaging change, not an architectural one), but they share one version number, one test suite, and one release pipeline.

If you install ruso 1.3.0, you get:

  • CLI 1.3.0
  • Runtime 1.3.0
  • Registry client 1.3.0

No compatibility matrices. No wondering which CLI works with which runtime. One artifact, tested together, shipped together.

Why we did it

The split repos created friction:

Breaking changes required coordination. A new bytecode instruction meant updating the runtime, the CLI, and the registry client. Three PRs, three CI runs, three release tags. If one failed, the others sat idle.

Security fixes shipped slowly. A CVE in the runtime meant patching it, waiting for the CLI to update its dependency, and testing again. The safer path: shipping all three at once. That was the slow path.

Contributors onboarded three times. Clone three repos. Understand three build systems. Navigate three issue trackers. Every new person hit that wall.

Version pinning was fragile. Deployment scripts pinned ruso-cli@1.2.0 and ruso-runtime@1.2.1. That worked until 1.2.2 shipped with a breaking protocol change. The pin broke silently.

Unifying them removes those problems. A breaking change ships atomically. A CVE fix goes out in one release. Contributors clone once.

What stayed the same

Nothing user-facing changed.

# Install
curl -fsSL https://docs.ruso.hopeless-labs.com/install.sh | sh

# Compile
ruso compile check.rsl -o check.rbc

# Run
ruso scan --target host --script check.rbc

# Registry
ruso registry search sql
ruso registry install exposed-redis

Existing .rbc files still work. The bytecode format did not change. The registry API is unchanged. If you pinned a specific CLI or runtime version, those packages still exist. We did not delete history.

What got better

One version to track. ruso --version prints one number. That number applies to every component. Upgrade scripts no longer juggle three package names.

Faster security fixes. When a CVE lands, we patch it, test the entire stack, and ship. No waiting for downstream repos to catch up.

Simpler CI. The test matrix covers every combination of CLI, runtime, and registry in one pipeline. If it passes, the whole release works. No post-ship integration bugs.

Easier contribution. One repo to clone. One make test to run. One issue tracker to search. The onboarding friction dropped hard.

Better caching. Shared dependencies between CLI and runtime now dedupe in CI. Build times dropped by ~30% because we stopped compiling the same bytecode library twice.

Migration: there isn't one

If you run ruso today, keep running it. The next release you pull will be the unified version. No config changes, no breaking updates, no manual steps.

If you pinned specific component versions in a deployment manifest, those pins still resolve. The old packages remain published. We recommend moving to the unified release to stay current with security patches, but the migration is a one-line version bump, not a rewrite.

What we're building next

With the toolchain unified, the roadmap clears up:

Persistent bytecode cache. The CLI will cache compiled .rbc files locally, keyed by source hash. Re-running the same check against a new target becomes instant. No recompilation.

Parallel probe execution. The runtime will fire independent probes concurrently instead of serially. A check that opens five TCP connections will open all five at once, cutting scan time by the round-trip count.

Registry search from the CLI. ruso search <keyword> will query the registry without leaving the terminal. Filter by tag, author, or severity. Install directly from search results.

Better compile-time errors. The compiler will catch more mistakes earlier and explain the fix in plain language. "Unknown verb send_http" becomes "Unknown verb send_http. Did you mean send? The http probe is declared but not used."

Structured finding output. ruso scan --format json will emit findings as JSON, one per line. Pipe it to jq, ship it to a SIEM, or import it into a tracker without parsing text.

Why this matters

Ruso is built for people who read the source. That includes the build system. Unifying the repos makes the project easier to audit, easier to contribute to, and easier to trust. One codebase, one test suite, one release artifact.

The separate repos worked when Ruso was a prototype. The unified repo works now that people run it in production.

If you filed an issue, sent a PR, or reported a bug that nudged us toward this. Thank you. The unification is a direct result of watching how teams actually use the tools.


The unified release ships this week. Existing users: nothing breaks. New users: simpler install. Everyone: clearer versioning, faster fixes, and a roadmap that moves faster now that the tooling is out of the way.