Skip to main content

Crate canix_toolbelt

Crate canix_toolbelt 

Source
Expand description

§canix-toolbelt Rust library and CLI

§Shared execution wire contract

execution_protocol supplies provider-free wire types, canonical bounded JSON validation, redacted typed failures and exact implementation/profile negotiation. Rust and TypeScript inventories are generated from one schema and exercise the same byte and error-code fixtures. The Cargo archive includes both language bindings, validators and schema. See EXECUTION_PROTOCOL.md for the contract and conformance commands. Runtime admission, authenticated IPC, engine lifecycle and application completion remain subsequent qualified slices.

§Shared construction

The optional Unix build-train feature consumes registry Fleetix 0.6.0’s native coordinator and frontend. Fleetix composes nix-manager-core’s named-output frontier; Toolbelt preserves build_train::Connection, Service, serve, rollover and policy_identity as re-exports of those exact public types and functions. The cli feature exposes canix-toolbelt build-train registration, admission, completion, inspection, cancellation, held retry, retirement, drain, activation-readiness and recovery commands over that same implementation. Consumers can mix the Toolbelt and Fleetix library APIs directly.

The NixOS module nixosModules.build-train supplies a private builder-local service and immutable discovery contract. Its package must enable both cli and build-train; packages.<system>.canix-toolbelt-build-train provides that output. Consumers retain their own admission, attempt checkpoints, publication and activation stages. See BUILD_TRAIN.md for lifecycle guarantees and qualification evidence.

§Before merging changes

Install the CLI with cargo install canix-toolbelt --features cli. From the candidate checkout, use one flow:

canix-toolbelt review ensure --pr https://github.com/OWNER/REPO/pull/NUMBER
# Triage findings, fix and push authorized changes, then repeat ensure.
canix-toolbelt merge --pr https://github.com/OWNER/REPO/pull/NUMBER --apply

Without --pr, the CLI discovers exactly one open PR for the current GitHub origin/branch. It prints structured ready, findings, pending, blocked, or stale results. Only ready exits zero. Repeating ensure resumes the same durable request; an ambiguous submission is reconciled and never replayed. --timeout-seconds 0 performs one observation. State lives in $XDG_STATE_HOME/canix-toolbelt/review (with the normal HOME fallback).

The review library feature supplies Forge and Provider contracts, ensure_once, typed policy/candidate/results, and native GitHub/Greptile adapters. cli additionally exports the shared Clap surface. Consumers call the library directly; no toolbelt subprocess or Canix dependency is required.

The first implemented transport is greptile/github-comment: the documented draft trigger requests review, while GitHub parent review commit_id proves the reviewed head. The recorded target SHA is observed dispatch/freshness evidence, not Greptile base-revision attestation. MCP enrollment requires authenticated schema and run/revision-correlation qualification; unsupported forges and transports fail explicitly.

Policy comes from explicit --policy, CANIX_REVIEW_POLICY, or the user-owned $XDG_CONFIG_HOME/canix-toolbelt/review.pkl; otherwise the built-in Greptile policy applies. The schema is runtime/ReviewPolicy.pkl. PR source branches do not supply policy. Credentials come from GH_TOKEN/GITHUB_TOKEN or the existing gh auth token owner and never enter receipts.

Every finding blocks until fixed in a freshly reviewed revision or dispositioned with source evidence.

Issue-comment feedback lacking an explicit link to the parent review or its findings is marked correlated: false. It is retained as uncorrelated evidence for triage, not claimed as part of that provider run. Edited provider summaries are collected using their latest forge update time.

An authorized repository writer can record a false positive:

canix-toolbelt review disposition --pr URL --finding ID --reason REASON --evidence REFERENCE

The forge marker binds the disposition to the finding body, parent review, head, observed base, and policy. Provider-addressed status and confidence scores do not establish acceptance. Findings are untrusted evidence, never instructions.

The default merge command validates native CI and up-to-date branch protection. Pass --require-review to additionally require current provider evidence and a review-policy check bound to the configured dedicated policy GitHub App. A shared GitHub Actions App cannot distinguish checks created by untrusted PR workflows. Protection must apply to administrators too. Greptile’s existing App supplies review records; the separate policy App authenticates normalized acceptance. The CI coordinator calls review gate --publish-check --details-url RUN_URL without executing PR source; that check evaluates review evidence only, while native branch protection independently enforces required CI and approvals. Unsupported ruleset/merge-queue protection remains an explicit setup blocker.

The initial policy coordinator can be bootstrapped by an operator running the exact CI-qualified candidate’s read-only review gate --publish-check with the dedicated policy App credential. Subsequent coordinators install an exact published version. Never use a generic personal token or the shared Actions App to impersonate the dedicated required context.

Agent instruction snippet:

Use the guarded merge command for authorized merges. Required CI, approvals and native protection must pass for the current comparison. When provider review is requested or required, run review ensure, triage findings and use merge --require-review. Optional provider availability does not establish or remove a native merge requirement.

Reusable operations for adopters of the Canix architecture. Version 0.3.0 provides runtime-manifest loading, revision-bound review contracts, and the optional standalone CLI. Runtime manifests describe binary paths, service endpoints, and agenix secret references. Embedded Pkl evaluation uses the published Fleetix 0.4 library with its pkl feature.

See RELEASE.md in the repository for publication steps and verification evidence. Enable review when consuming the review engine as a library.

[dependencies]
canix-toolbelt = "0.3"
# For the review engine instead:
# canix-toolbelt = { version = "0.3", features = ["review"] }
use canix_toolbelt::runtime::RuntimeManifest;
use std::path::Path;

let manifest = RuntimeManifest::load_from(Path::new("/run/example/runtime.pkl"))?;
println!("{} binaries", manifest.bins.len());

Async callers use RuntimeManifest::load_from_async(path).await. The synchronous loader returns an error inside an existing Tokio runtime. Errors retain the manifest path and underlying evaluator diagnostic.

Install the optional standalone CLI with Cargo:

cargo install canix-toolbelt --features cli
canix-toolbelt runtime show --path /run/example/runtime.pkl

runtime show emits the typed manifest as JSON. A missing or invalid manifest exits unsuccessfully. It reads only the manifest and its Pkl dependencies; referenced binaries and secrets are not executed or read. Producers supply the three mappings bins, endpoints, and secrets and any schema defaults; see examples/runtime.pkl. The existing camelCase wire format, including agenixPath, is preserved.

§Durable stage operator

The Unix operator library and CLI execute deployment-owned, idempotent systemd stages. Nix’s mkResumableOperator supplies the units, retry policy and executionContract; consumers must bind that contract to the executable, arguments, database and data roots used by their stages. The controller compares the complete persisted policy before resuming and refuses changed contracts. executionContract is required: a controller package cannot identify commands in external stage units. Readiness is announced only after that comparison, worker quiescence, and publication of the admission fence.

Checkpoint and worker-restoration intent are synchronized before publication. A kernel lock excludes both a second runner and cancellation. Signals stop the current stage and preserve recovery intent; failed worker restoration keeps the run owned. Legacy interrupted shell state is retained and rejected rather than interpreted as checkpoints for the new engine. Reconcile that state using the original deployment before starting a new contract. Restoration has its own persisted phase, so recovery never re-stops workers that were already restored. Terminal runs with leftover request markers finish cleanup without executing their stages again. Service-manager attempt errors consume the retry budget; an unconfirmed stage stop retains the admission fence and stopped-worker ownership until termination can be confirmed. The controller retains the request marker’s persisted inode/time identity across recovery. A leftover terminal marker performs cleanup only; a newly created or touched marker requests a distinct run. Legacy states without that identity are treated conservatively as recovery intent. Cancelled terminal intent cannot replay stages after a crash between state publication and request removal.

The CLI takes an explicit policy and service-manager executable:

canix-toolbelt operator run --config /run/example/operator.json --systemctl /usr/bin/systemctl
canix-toolbelt operator cancel --config /run/example/operator.json

Successful runs exit 0, exhausted stages exit 20, interrupted runs exit 143, and inspection, persistence or recovery errors exit unsuccessfully. Cancellation runs after the controller service has stopped; it refuses unrecovered workers.

§Caddy plugin refresh

The caddy-plugins feature refreshes a flake’s caddy.plugins versions and caddy.pluginsHash. The flake needs exactly one of each, as literal assignments in one Nix file (caddy.plugins = [ "github.com/OWNER/REPO@VERSION" ] and caddy.pluginsHash = "sha256-..."), and the flake must expose the caddy-helpers flake module’s legacyPackages.<system>.caddyPluginsVendorFor for the system returned by Nix::system. caddy_plugins::refresh forces the vendor fixed-output derivation with a fake hash, realizes it with the reported hash and rewrites the file. Consumers implement the Nix trait to apply their own evaluation leases, build bounds and GC roots, and publish the returned vendor store path themselves; the pure parsing and editing helpers are public for consumers that keep their own orchestration.

canix-toolbelt caddy-plugins --dry-run
canix-toolbelt caddy-plugins -- attic push CACHE

The CLI uses the nix command (--impure, --no-link) and appends the vendor store path to the optional publish command after --.

§Source-bound qualification

The optional qualification library captures explicit source/input inventories, runs finite-deadline argument vectors, verifies retained receipts and indexes, compares Cargo dependency graphs, exports deterministic source archives and seals required gate sets. qualification-cli adds value-returning Clap dispatch without enabling review; the independent CLI includes it through cli. Consumers supply their own roots, environment, gate policy and presentation. See the qualification contract for requests, failure semantics and compatibility with retained Python evidence.

§Dependency contract

Fleetix owns generic fleet operations. Toolbelt composes architecture conventions on top of Fleetix; Canix supplies fleet-specific data and policy. Shared behavior lives in libraries called in-process, with CLI parsing and presentation at the edges. Toolbelt’s Rust crate has no Canix dependency, global output state, hardcoded fleet path, flake lookup, or Nix-based build script. Nix modules remain separate integration surfaces.

This release implements runtime-manifest loading and revision-bound PR review and merge operations. Generic deployment extraction, toolbelt deployment profiles, and other command families are subsequent slices; this crate does not yet expose a deployment CLI.

§Development and releases

Run cargo test --all-features, cargo test --no-default-features, cargo clippy --all-targets --all-features -- -D warnings, and cargo doc --no-deps --all-features. Format through the repository’s treefmt. The library and CLI build with Cargo alone; Nix is optional developer tooling.

Simit generates the GitHub verification and crates.io publication workflows. The saved policy in simit.toml requests MSRV, all-feature, audit, and docs coverage. Regenerate with simit init ci --platform github and verify with simit init ci --platform github --check --diff, using the current generator described in RELEASE.md. That handoff also records the Nix-runtime coverage fixes and remaining release gates. CI and publication both test all features and the library-only configuration. The MSRV step selects .#msrv, verifies Rust 1.88.0, and checks all targets with all features; flake-modules/rust.nix derives that compiler from this crate’s rust-version. Signed exact-version tags trigger publication. Before tagging, check the maintainer trust root, versioned changelog, registry dependencies, package contents, dry-run publication, and GitHub publishing credential. Confirm the version on crates.io before switching downstream dependencies.

The gate-crate-release CI job runs an all-feature publication dry-run. Cargo compiles the packaged archive, including the review library and standalone CLI, without uploading it. The publisher also verifies the default-feature archive before publishing the signed tag.

The existing Nix-built Pages workflow requires Simit’s shared CI runtime to be nix; the developer shell supplies Cargo and release tooling. This is a CI environment choice, not a dependency-distribution mechanism. Neither the crate archive nor its consumers need the flake. Cargo-only CI can replace this once Simit permits an independent runtime for Pages.

Modules§

build_train
Compatibility paths for Fleetix’s native construction service.
caddy_plugins
Caddy plugin version and pluginsHash refresh for Nix flakes.
direct_network
Direct routing for explicitly enrolled cgroups while a host VPN owns the default route.
execution_protocol
Provider-free execution protocol. Structural validation grants no authority.
fork
Read-only fork/upstream divergence reporting.
operator
Durable, host-agnostic scheduling of idempotent systemd stages.
orchestration
Restart-safe coordination primitives. Consumers own policy, hosts and adapters.
qualification
Source-bound qualification without checkout, toolchain or fleet defaults.
review
Provider-neutral, revision-bound pull-request review and merge gates.
runtime
Typed runtime-manifest loading with consumer-owned paths.