Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• REVIEW.md
• SECURITY.md
• AGENTS.md
• schemas/index-v1.json
• registry/index.json
• scripts/validate_candidate.py
• scripts/discover.py

The Numan Official Registry is a data-only repository providing a curated, signed index of packages for the Numan Nushell package manager. It functions as a secure Content Delivery Network (CDN) endpoint where Numan clients sync the index.json catalog and verify its Ed25519 detached signature. The architecture prioritizes cryptographic trust, automated validation, and a multi-stage intake pipeline to ensure the integrity of Nushell plugins, modules, scripts, and completions.

Sources: README.md:1-12, SECURITY.md:83-93, AGENTS.md:6-9

Core Components and Data Flow

The system is composed of the signed registry index, a suite of Python-based CI tooling, and a GitHub Pages deployment target. Unlike traditional web applications, the "application" logic resides in the command-line toolchain under scripts/ and the Numan client's verification logic.

System Architecture Diagram

The following diagram illustrates the relationship between the maintainer's toolchain, the GitHub repository, and the production CDN.

The Registry Index (index.json)

The central data structure is registry/index.json, which follows a strict schema defined in schemas/index-v1.json. It maps package identifiers to their metadata, version history, and cryptographically hashed artifacts.

Key Data Structures

Component	Type	Description
schema_version	integer	Must be 1.
updated_at	string (ISO 8601)	Timestamp of the last index update.
packages	array	List of package objects including id, description, repo, type, and versions.
artifact	object	Contains the kind (binary, archive, source), url, and sha256 digest.
trust	object	Declarations for successor public keys.

Sources: schemas/index-v1.json:7-46, README.md:56-62

Package Types

The registry supports four distinct package types, which determine how Numan handles activation and installation:

1. plugin: Rust-based Nushell plugins (e.g., nu_plugin_semver). Requires target-specific binaries.
2. module: Nushell modules (e.g., nutest). Often includes an activation section for nu-module imports.
3. script: Individual Nushell scripts (e.g., nufetch).
4. completion: Custom completions for CLI tools (e.g., git-completions).

Sources: schemas/index-v1.json:52-55, registry/index.json:10-153

Trust and Security Model

Security is enforced through Ed25519 signatures and SHA-256 artifact digests. The architecture ensures that no private keys are ever committed to the repository.

Signing Workflow

The production signing process is isolated in a protected GitHub Actions environment:

1. Canonicalization: The index.json is converted to a canonical form (sorted keys, no whitespace).
2. Signing: An Ed25519 signature is generated over the canonical bytes using NUMAN_REGISTRY_PRIVATE_KEY.
3. Envelope: The signature is stored in registry/index.json.sig, specifying the key_id and algorithm.

Sources: README.md:64-73, SECURITY.md:83-88, REVIEW.md:37-43

Validation Sequence

The following sequence diagram shows the validation steps performed by scripts/validate.py during CI gates.

Intake Pipeline

The intake process is a multi-stage workflow designed to move a package from discovery to production promotion.

Intake Stages

Stage	Tool	Purpose
Stage 3: Discovery	scripts/discover.py	Read-only inspection of a repo to produce a structured report.
Stage 4: Generation	scripts/gen_candidate.py	Transforms discovery report into a draft registry spec.
Stage 5: Validation	scripts/validate_candidate.py	Downloads artifacts, computes hashes, and runs lints.
Stage 1: Prove	scripts/lifecycle-prove.py	Real-world acceptance: installs and activates package with a real Nu binary.

Sources: scripts/discover.py:1-12, scripts/gen_candidate.py:1-12, scripts/validate_candidate.py:1-11, README.md:95-108

Lifecycle Evidence Requirement

Activatable packages (all plugins and modules with an activation block) MUST carry lifecycle evidence. This is recorded in the version entry's verified_with list, documenting the exact MAJOR.MINOR.PATCH Nushell versions that successfully passed the lifecycle-prove.py test.

Sources: README.md:104-108, REVIEW.md:44-46, schemas/index-v1.json:71-78

Infrastructure and Deployment

The registry is deployed to GitHub Pages, which serves as the public CDN.

• Staging: Triggered on the default branch; uses an ephemeral CI key to sign the index. Does not assert production trust.
• Production: Requires manual dispatch and reviewer approval. Accesses the protected production environment secrets containing the master private key.
• Maintenance Tools: Scripts like render_catalog_compat.py and sync-intake-candidates.py ensure that documentation files like docs/catalog-compat.md and docs/intake-candidates.md remain in sync with the registry state.

Sources: README.md:75-82, AGENTS.md:26-30, scripts/render_catalog_compat.py:1-15