onevcs
Version control and its remote host behind one host-neutral vocabulary, for agent workflows.
The review unit is a change request — GitHub maps it to a pull request, and a
later host maps it to whatever it calls the same thing. Vcs owns the repository
side (identities, sessions over an isolated worktree, preserved work);
RemoteHost owns the host side (opening a change, reading its checks, merging
it); a rules file decides, per repository, how a change publishes and what
verifies it. Everything a run does is emitted as an NDJSON event stream.
The public surface is the approved contract — docs/contract.md
— compiled, and it is implemented: the registry with its lazy migration, the rules
engine, sessions over borrowing clones, bounded git, the FIFO merge queue, both
publication strategies, recovery and provenance, the merge train, and the event
stream.
What one change looks like
onevcs register ~/projects/widgets # once per checkout
onevcs rules check widgets # which policy, and why
token=$(onevcs session open widgets --branch feature/thing | jq -r .token)
# …work in the worktree the session printed…
onevcs publish "$token" # verify, then land it
onevcs events "$token" # everything it did, as NDJSON
A branch that outlived the session that cut it is landed by name instead, under
that same rules-resolved policy: onevcs publish-branch feature/thing --repo ~/projects/widgets for work that finished, and onevcs recover for a step that
stopped half way, which publishes it with the attestation that a green gate
cleared it. Whichever of the three refuses a branch names the one that takes it.
Everything durable lives under one state root — ONEVCS_HOME, otherwise
~/.onevcs.
GitHub is reached through gh, so whatever gh auth status reports is the
credential. A fine-grained personal access token needs Actions: Read on the
repository beside its contents and pull-requests access: GitHub will not let that
credential class resolve a check run at all — there is no Checks permission to
grant one — so a change request's checks are read from its workflow runs, and
change_checks says so in the sources it answers with. Anything a third-party
integration posted as a check run or a commit status is invisible to such a token,
and a credential that can read neither source is refused rather than reported as
having no checks.
Install
cargo install onevcs # crates.io
pip install onevcs-cli # a prebuilt wheel, no Rust toolchain
npm install -g onevcs-cli # a prebuilt binary, no Rust toolchain
All three install the same onevcs binary. Prebuilt binaries exist for Linux
(x64, arm64), macOS (x64, arm64), and Windows (x64); every release also attaches
the archives and their .sha256 checksums for a direct download.
Use
onevcs --help
--help is the command surface, and publish reserves its own exit codes for a
gate that failed, a request that was invalid, and a base that moved under it.
Embed it
A command answers a process: an exit code and a line of prose. A caller embedding the crate wants the decision, so the same operations answer values.
let published = onevcs::publish(&providers, &token, &PublishRequest::default())?;
match published.outcome {
PublishOutcome::Merged(sha) => journal.landed(sha),
PublishOutcome::ChangeOpen(url) | PublishOutcome::Queued(url) => journal.awaiting(url),
PublishOutcome::NothingToPublish => journal.nothing(),
PublishOutcome::Failed { kind, reason, retained } => journal.failed(kind, reason, retained),
}
close_session and session are the same for the rest of a session's life, and
EventStream::open(&token) reads its events as Envelopes, each attributed to
the session that wrote it — so a caller following several publications at once can
tell them apart. The command line is a rendering of these rather than a second
path through them.
A consumer that wants some of what a session writes reads it through the filter
grammar the three producing libraries share — EventStream::open_filtered(&token, filter), or onevcs events TOKEN --filter SPEC with the spec inline as JSON or in
a file. An envelope passes when it matches any include matcher (or include is
absent) and no exclude matcher, matching source by family, kind by glob
(change-*), and the reserved label keys exactly:
include:
- {source: vcs, kind: "gate-*"}
exclude:
- {kind: lock-wait}
Before a caller has a token, session_holders(repo) answers who is in a
repository: one SessionHolder per recorded session, carrying the token the calls
above take, the branch and worktree it holds, and whether its owner is still
running (Liveness::Live) or the session is the remains of a run that stopped.
Test against it, without a real GitHub
Embedding the crate, run_with(&cli, providers) takes the two implementations a
run reaches Vcs and RemoteHost through; run is that with Git and GitHub,
and every entry point above goes through the same seam.
onevcs-testing ships in-memory and file-backed
implementations of both, so a consumer's suite drives a real onevcs through a
real journey against a host it seeded:
cargo add --dev onevcs-testing
They emit the events the real implementations emit — a claim this repository's own suite checks by running one publication journey on both backends and holding the two event streams to each other.
Develop
just bootstrap # from a clean clone
just check # the deterministic gate: format, clippy, tests, coverage, docs
just gate # check, plus the diff-scoped LLM-judge tier — the pre-push bar
just --list is the full index.
License
MIT. See LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file onevcs_cli-0.4.2-py3-none-win_amd64.whl.
File metadata
- Download URL: onevcs_cli-0.4.2-py3-none-win_amd64.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6cdeba19ba16a685457a5605492f3677213099a481e1de2e24ac28a92f21d676
|
|
| MD5 |
035224e427ad7d38aa6c3e925a44ff5b
|
|
| BLAKE2b-256 |
741bb33103a04d22cbe4e5e8824731c514e64e673de700a27426efea1d1d0d13
|
File details
Details for the file onevcs_cli-0.4.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: onevcs_cli-0.4.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c2b4440643e385482f34fc82fc23462528d45ba8583f370f5afb554225199fae
|
|
| MD5 |
7acd01a52b46850e25437d215004587d
|
|
| BLAKE2b-256 |
359f70537916905c78ed4f35b9ce23dd78d5110b603deaf9e19c03ad58a1b3d8
|
File details
Details for the file onevcs_cli-0.4.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: onevcs_cli-0.4.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 1.0 MB
- Tags: Python 3, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a0c821317280a05dc6ff5c8b6afcfe9143e2991cc4618505ef7f146da617fc7e
|
|
| MD5 |
f20bff285c52ae80ca18a74771af66d2
|
|
| BLAKE2b-256 |
2549a94514726739f6a43b3f82be0441da1cd0ce4acdbca9b6db6c8339b48c1b
|
File details
Details for the file onevcs_cli-0.4.2-py3-none-macosx_11_0_arm64.whl.
File metadata
- Download URL: onevcs_cli-0.4.2-py3-none-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.0 MB
- Tags: Python 3, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6cbc277416956783b33788643a1b539cb87729f2de48644a142c1b24154c0c6b
|
|
| MD5 |
144ff9481fea97b4af73a570d75d0d5e
|
|
| BLAKE2b-256 |
6f1eebef62fc20ec1d051ef65bb97c358f55e42df31672bb9edca4d788dc31f8
|
File details
Details for the file onevcs_cli-0.4.2-py3-none-macosx_10_12_x86_64.whl.
File metadata
- Download URL: onevcs_cli-0.4.2-py3-none-macosx_10_12_x86_64.whl
- Upload date:
- Size: 1.1 MB
- Tags: Python 3, macOS 10.12+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
12b149527f0f4db1cc24b90858b7740cebc6115c23f4cb1be9dbb02b81ce8dad
|
|
| MD5 |
604e749dcd3a76b02fef9d5601c8dc14
|
|
| BLAKE2b-256 |
e0e17eeb85cfb97992c6f3ac57b589c90906f1c3d0265bbb8f28cbb2a6b09db8
|
