Numan Registry Handoff
Relevant source files
The following files were used as context for generating this wiki page:
The Numan Registry Handoff is the critical process of transferring build artifacts, metadata, and provenance information from the numan-plugins repository to the official numan-registry. This repo acts as a CI build and sign pipeline feeder, closing the gap for plugins that only ship source code by providing signed, hash-pinned binary artifacts.
Sources: README.md:1-12
The handoff ensures that binaries cross-compiled from immutable upstream commits are properly packaged and described in a format that the registry's intake scripts can consume. The process maintains a strict trust boundary where this repository builds and hosts binaries but never holds signing keys, which remain in the numan-registry environment.
Sources: README.md:16-25, REVIEW.md:27-28
Handoff Architecture and Data Flow
The handoff relies on three primary artifacts produced during the CI workflow: generated spec-*.json files, release URLs hosted on GitHub, and immutable provenance data (tags and commit SHAs). The flow moves from manifest validation to build/package phases, ending with a release transaction that prepares data for the registry.
Sources: README.md:37-43, REVIEW.md:46-53
The diagram shows the transition of data from the build environment to the trust-gated registry environment.
Sources: README.md:16-30, REVIEW.md:46-53
Key Handoff Components
1. Generated Registry Specifications
The scripts/gen_spec.py utility creates a kind: binary specification required by the registry's add-package.py script. Crucially, these specs intentionally omit SHA-256 hashes; the registry re-downloads and computes hashes during intake to prevent hand-typed errors or trust-boundary breaches.
Sources: scripts/gen_spec.py:1-18, REVIEW.md:34-35
2. Manifest and Provenance
The manifest.json file serves as the source of truth for the handoff, containing immutable upstream source_commit values and human-facing tags. The handoff preserves this provenance to ensure users can verify the origin of the binaries.
Sources: manifest.json:4-10, REVIEW.md:35-36
3. Release Transactions
The scripts/release_transaction.py script manages the assembly of releases as run-owned drafts. Only after the complete asset set is verified is the release made public for registry intake.
Sources: scripts/release_transaction.py:1-10, README.md:23-25
Handoff Data Elements
The following table summarizes the specific data points handed off to the numan-registry:
| Element | Source | Description |
|---|---|---|
spec-*.json | gen_spec.py | Metadata describing the plugin, version, and architecture mapping. |
| Release URLs | build.yml | Immutable URLs where the .tar.gz or .zip archives are hosted. |
source.rev | manifest.json | The exact git commit SHA from the upstream repository. |
nu_version | manifest.json | Compatibility range for the Nushell binary. |
plugin_bin | manifest.json | The filename of the binary inside the archive. |
Sources: REVIEW.md:46-53, scripts/gen_spec.py:133-156
Registry Intake Logic
During the handoff, the numan-registry performs the following sequence to finalize the plugin for end-users:
Sources: README.md:52-59
The sequence illustrates the independent verification performed by the registry during intake.
Sources: README.md:61-64, REVIEW.md:27-30
Spec Generation Implementation
The specification generated for handoff includes a source block to maintain the trust link to the original Rust source code.
# From scripts/gen_spec.py
return {
"owner": entry["owner"],
"name": entry["name"],
"description": entry["description"] + " CI-built...",
"repo": f"https://github.com/%7Bentry%5B%27repo%27%5D%7D%22%2C
"type": "plugin",
"version": entry["version"],
"source": {
"git": f"https://github.com/%7Bentry%5B%27repo%27%5D%7D%22%2C
"rev": entry["source_commit"],
"cargo_name": entry["plugin_bin"],
},
"artifact": {
"kind": "binary",
"targets": targets,
},
}
Sources: scripts/gen_spec.py:133-156
Summary of Handoff Invariants
- No Private Keys: Signing material never enters the handoff path from
numan-plugins. Sources: REVIEW.md:28 - Hash Computation: Hashes are not authored in this repo; they are computed by the registry at intake. Sources: README.md:20-22
- Draft-then-Finalize: No half-published releases; assets are verified as a set before the handoff becomes public. Sources: REVIEW.md:33
- Immutable Assets: Release assets cannot be overwritten; changes require new versions or build revisions. Sources: REVIEW.md:31-32
Successful completion of this handoff allows the numan CLI to perform install and activate operations against verified, cross-compiled binaries.
Sources: README.md:55-57