PlumbAlpha

Proof that a story is done — verified, not asserted.

This is alpha software. It is pre-1.0 and published for trusted testers. Interfaces, the manifest format and the command line may all change between versions without notice, and there is no support commitment. Pin a version if you depend on one.

What it does

A green test suite tells you your tests pass. It does not tell you that the requirement you wrote down is actually implemented, or that the code you tested is reachable from the running system. Plumb checks the link that everyone assumes and nobody verifies.

A story counts as proven only when two things hold:

A test citing it ran and passed — not skipped, not aborted, in this run.
That test's execution reached the wired system — it went through a production entry point you declared, rather than calling an isolated function.

The second check is the one that finds things. Code no entry point reaches cannot prove a story however green its tests are, so a passing test over orphaned code stops reading as done. Status is derived from each run and never stored, so a proof that later breaks un-proves its story and nothing can go stale.

Optionally, and off by default, Plumb will also mutate the code a story's tests drove and report how many of those mutants the tests noticed — which is the only thing here that looks at whether your tests check anything, rather than merely running it.

Install

curl -fsSL https://plumb.64bitspace.com/install.sh | sh

One file, both language adapters inside it. No package index, no account, and nothing added to your project's dependencies. Then, in a project with a plumb.toml:

plumb board

Python and Java are supported today, by the same command and the same config file. Plumb itself needs Python 3.11+ somewhere on the machine — including when your project is Java, where nothing about your build changes. Ubuntu 22.04 and RHEL 9 ship older versions as python3; apt install python3.11 or dnf install python3.11 is the whole fix, and the installer tells you if it applies.

Getting started

In your project, run:

plumb init

It works out what it can from the layout — your packages, where compiled tests land, what the classpath file should be called — writes plumb.toml, and tells you what is left. It never overwrites: run it again on a half-configured project and it fills the gaps and says which files it kept.

Two things it cannot guess. Where your wired system begins:

# plumb.toml
entry_points = ["com.myapp.Api#handleRequest"]

Name the handful of places a real request enters. Without at least one, a story can still pass but nothing checks that its test reached the running system — which is the check worth having.

And which story a test proves. In Java, plumb init writes the annotation jar to .plumb/plumb-java.jar — depend on it so your citations compile (testImplementation files('.plumb/plumb-java.jar') in Gradle, a system-scoped dependency in Maven; plumb init prints both):

import plumb.Proves;

@Test
@Proves(value = "APP-1", depth = "wiring")
void ordersAreRouted() { ... }

The id is yours. Plumb keeps no catalog and never parses it, so APP-1, JIRA-4412 or a spreadsheet row all work.

Java needs its test classpath in a file, which your build tool already produces:

mvn dependency:build-classpath -Dmdep.outputFile=target/plumb-classpath.txt
plumb board

In Python it is @pytest.mark.proves("APP-1", depth="wiring") and there is no classpath step. Everything else is the same command and the same file.

Verifying what you install

Releases are signed. The installer always checks the artifact's checksum, checks the signature when gpg is present, and tells you which of the two it did. To refuse installing without a verified signature, or to pin a version:

curl -fsSL https://plumb.64bitspace.com/install.sh | PLUMB_REQUIRE_SIGNATURE=1 sh
curl -fsSL https://plumb.64bitspace.com/install.sh | PLUMB_VERSION=0.1.0 sh

The signing key is Flattop5377 <Flattop5377@proton.me>:

57C4 5ECD E870 35DB 5D6B 2AA9 675D DD55 F917 F71F

It is published on keys.openpgp.org and keyserver.ubuntu.com, so the key reaches you by a route that is not this website. That matters: the checksum protects against a corrupted download, but not against this host — whoever served you a bad artifact served you the installer that checks it. Only the signature closes that, and only if you did not take the fingerprint from here alone.

Releases and their checksums are browsable at /latest/, and every published version stays reachable at its own path.

Licence

Apache License 2.0. The full text ships in the artifact and with the source.