Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The Numan Official Registry is a data-only repository providing the signed index of packages for the Numan Nushell package manager. It manages a curated list of plugins, modules, scripts, and completions, serving them as a signed index.json through GitHub Pages.
The project encompasses the registry data itself, JSON schemas for validation, and a Python-based toolchain for package intake, signature verification, and maintenance. There is no long-running server; the "application" consists of command-line scripts and CI workflows that enforce trust invariants and metadata integrity.
Sources: README.md:1-6, AGENTS.md:6-10
Environment Setup
Prerequisites and Dependencies
The toolchain is designed to run on Python 3.12, matching the project's CI environment. Development requires two primary third-party libraries:
cryptography: Used for Ed25519 signing and verification.jsonschema: Used for validating the registry index against defined schemas.
These dependencies are typically installed via python3 -m pip install --user cryptography jsonschema.
Sources: AGENTS.md:12-16, scripts/provision-production-key.sh:66-70
Repository Structure
The repository is organized into distinct areas for data, keys, schemas, and automation:
| Directory | Purpose |
|---|---|
docs/ | Maintainer runbooks, key provisioning, and compatibility tables. |
keys/ | Public keys used for production and official artifact verification. |
registry/ | The live data, including index.json, its detached signature, and a landing page. |
schemas/ | JSON schemas (v1) defining the structure of the registry index. |
scripts/ | Toolchain for validation, signing, and package intake management. |
tools/ | External parsers (e.g., Rust-based numan-parser-check) for parity testing. |
Sources: README.md:21-49
Core Architecture and Trust Model
The registry operates on a cryptographic trust model where clients verify the index.json using Ed25519 signatures. Artifact integrity is ensured via SHA-256 digests recorded in the index.
Signing Workflow
The production signing key is never stored in the repository. It is managed as a GitHub Environment Secret (NUMAN_REGISTRY_PRIVATE_KEY) within a protected production environment.
This diagram illustrates the progression from local contribution to production publication, emphasizing the air-gapped nature of the production private key.
Sources: README.md:55-66, README.md:82-96, SECURITY.md:46-59
Package Intake and Lifecycle
Adding a package involves a multi-stage process to ensure metadata accuracy and functional compatibility with specific Nushell versions.
The Intake Pipeline
- Discovery: Identifying candidates (e.g., in
numan-plugins). - Spec Generation: Creating a package specification (scaffolded by scripts).
- Digest Computation: Using
add-package.pyto download artifacts and compute SHA-256 hashes. Hand-typing hashes is strictly forbidden. - Staging: Adding to the index with a
provisionalstatus. - Lifecycle Proof: Running
scripts/lifecycle-prove.pyagainst a real Nushell instance to verify the package installs and activates correctly. - Promotion: Recording successful Nu versions in
verified_withand removing the provisional flag.
Sources: README.md:105-120, REVIEW.md:40-45
Registry Index Schema
The index.json follows a strict schema where each package must define its type and versions.
The schema supports four package types: plugin, module, script, and completion.
Sources: schemas/index-v1.json:11-92
Common Developer Commands
Validation and Checks
Developers should run the following suite before submitting changes:
# Scan for secrets/private keys
python scripts/scan_for_secrets.py
# Perform schema and logic consistency checks
python scripts/preflight.py
# Validate index against schema (skipping signature locally)
python scripts/validate.py --index registry/index.json --schema schemas/index-v1.json --skip-signature
# Run Rust-based parser parity check
cargo run --locked --manifest-path tools/numan-parser-check/Cargo.toml -- registry/index.json
Sources: AGENTS.md:18-28, REVIEW.md:8-15
Maintainer Tasks
For key management and documentation updates:
- Key Provisioning: Use
scripts/provision-production-key.shto generate Ed25519 pairs. It ensures the private key is never printed to the terminal. - Documentation Refresh: Run
scripts/render_catalog_compat.pyafter index changes to update the human-readabledocs/catalog-compat.md.
Sources: scripts/provision-production-key.sh:14-23, scripts/render_catalog_compat.py:10-15
Security Invariants
- No Private Keys: Never commit
*.key,*.pem, or raw private material. CI will fail if detected. - Signature Placeholder: The
registry/index.json.sigfile in the source tree is often aPLACEHOLDER. Real signatures are generated during deployment. - Immutable Artifacts: Once published, artifact URLs and digests are immutable. Remediation for issues is handled via a new index revision (yanking or versioning).
Sources: REVIEW.md:28-40, SECURITY.md:54-57
The Numan Registry system provides a robust, verifiable pathway for Nushell users to access curated tools while maintaining high standards of security through cryptographic signatures and automated validation gates.