Spaces:
Sleeping
Sleeping
| # 0005 Prebuilt Rust Harness CLI | |
| Date: 2026-05-23 | |
| ## Status | |
| Accepted, amended 2026-05-31, amended 2026-06-09 | |
| ## Context | |
| The durable layer started as a thin shell wrapper around SQLite. That wrapper | |
| is now large enough to carry meaningful architecture risk: it mixes command | |
| parsing, SQL construction, migrations, import behavior, query rendering, and | |
| help text in one script. | |
| The previous installer copied a shell wrapper into target repositories. That | |
| kept Harness easy to install, but it also meant a Rust rewrite was not only an | |
| implementation change. It changed the distribution contract for every project | |
| that receives Harness. | |
| ## Decision | |
| The future Rust implementation of the Harness CLI should be shipped as a | |
| prebuilt binary downloaded by the installer. | |
| The command path for users and agents is the installed Rust binary: | |
| ```bash | |
| scripts/bin/harness-cli <command> | |
| ``` | |
| On Windows, the repository-local binary is installed as: | |
| ```powershell | |
| .\scripts\bin\harness-cli.exe <command> | |
| ``` | |
| The installer should download, verify, and install the platform-specific Rust | |
| binary directly at that path. There should be no shell wrapper command contract. | |
| The Rust CLI should follow the existing architecture rules: | |
| - Domain: harness records, statuses, lanes, and value types. | |
| - Application: use cases for intake, stories, decisions, backlog, traces, and | |
| queries. | |
| - Infrastructure: SQLite repositories and schema migrations. | |
| - Interface: command-line parsing, terminal output, and installer integration. | |
| Release automation now follows the same distribution contract. After a PR is | |
| merged to `main`, the post-merge maintenance workflow updates `CHANGELOG.md`. | |
| When the merged PR changed the Rust CLI source, schema, Cargo metadata, or CLI | |
| release packaging, it also bumps the CLI patch version, updates the installer | |
| release tag pin, creates a `harness-cli-v*` tag, and invokes the reusable | |
| Harness CLI release workflow for that tag. | |
| ## Alternatives Considered | |
| 1. Keep the shell CLI permanently. Rejected because the script has crossed from | |
| a thin wrapper into a growing application surface with weak testability. | |
| 2. Copy Rust source into every target project and build locally. Rejected | |
| because it makes Harness installation depend on a local Rust toolchain and | |
| increases setup friction for projects that only need the harness. | |
| 3. Require users to install a global `harness` binary separately. Rejected | |
| because Harness should remain repository-local for agents. | |
| 4. Download a prebuilt binary through the installer. Accepted because it keeps | |
| target repos simple while allowing the CLI internals to become typed, | |
| testable, and platform-aware. | |
| ## Consequences | |
| Positive: | |
| - The durable-layer CLI can move to typed command parsing and tested use cases. | |
| - Target projects do not need a Rust toolchain just to use Harness. | |
| - The `scripts/bin/harness-cli` command is the stable entrypoint for agents on | |
| macOS/Linux; Windows uses the same repo-local path with the `.exe` suffix. | |
| - Prebuilt releases can include a known SQLite linkage strategy. | |
| Tradeoffs: | |
| - The installer must learn platform detection and binary download behavior. | |
| - Release artifacts need checksums or another integrity check. | |
| - Unsupported platforms need a clear error path. | |
| - The project needs a repeatable release process for supported platforms. | |
| ## Follow-Up | |
| - Implement the migration through `US-002 Rust Harness CLI`. | |
| - Remove the old shell wrapper from installed project payloads. | |
| - Add checksum verification for downloaded binaries. | |
| - Treat the Rust CLI as the primary durable-layer implementation. | |