Manifest Configuration (manifest.json)

Relevant source files

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

• manifest.json
• scripts/validate_manifest.py
• scripts/gen_spec.py
• README.md
• REVIEW.md
• scripts/test_workflow_safety.py

The manifest.json file serves as the central build matrix and configuration authority for the numan-plugins CI pipeline. Its primary purpose is to define the set of active plugins to be cross-compiled, their immutable upstream source references, and the target platforms they support. This manifest acts as a "feeder" for the binary-delivery portion of the Numan plugin ecosystem, ensuring that plugins can be installed from signed, hash-pinned artifacts without requiring users to have a local Rust toolchain.

Sources: README.md:1-12, manifest.json:2-3

The manifest establishes a trust boundary by pinning plugins to specific, immutable source_commit values rather than mutable tags alone. During the build process, automation verifies that the human-facing tag resolves to the specified source_commit to ensure provenance and prevent supply chain tampering.

Sources: REVIEW.md:27-35, scripts/validate_manifest.py:108-115

Data Schema and Structure

The manifest follows the numan-plugin-build-manifest-v0 schema. It is structured into three primary top-level components: global build defaults, a list of active plugin entries, and a mapping of target platforms to GitHub Action runners.

Sources: manifest.json:2-6, 178-184

Global Configuration

Field	Type	Description
schema	String	The versioned identifier for the manifest format.
default_targets	List	A unique list of Rust target triples that plugins should be built for by default.
target_runner_map	Object	Maps Rust target triples to specific GitHub Actions runner labels (e.g., macos-15-intel).

Sources: manifest.json:2-10, 178-184, scripts/validate_manifest.py:53-56

Active Plugin Entries

Each object within the active array defines the metadata and build constraints for a specific plugin.

Field	Type	Description
repo	String	The upstream GitHub repository in owner/name format.
name	String	The unique name of the plugin within the registry.
owner	String	The maintainer/owner of the plugin.
plugin_bin	String	The name of the resulting executable binary.
tag	String	Human-facing Git tag used for provenance.
source_commit	String	The immutable 40-character hex SHA of the upstream source.
version	String	The plugin version string.
nu_version	String	Semantic version range of compatible Nushell versions.
verified_with	List	Specific Nushell versions the plugin has been tested against.
exclude_targets	List	(Optional) Targets from default_targets to skip for this plugin.
exclude_reason	String	(Optional) Documentation explaining why specific targets are excluded.

Sources: manifest.json:11-30, scripts/validate_manifest.py:14-26

Build Matrix Logic

The manifest determines the actual build matrix for the CI pipeline by combining the default_targets with individual plugin exclusions. This logic is implemented in the validation scripts to ensure that no plugin is left without any valid targets.

Sources: scripts/validate_manifest.py:46-73

The following diagram illustrates how the build matrix is resolved for a given plugin entry:

A flowchart showing the logical progression from manifest loading to the resolution of the final build targets.

Sources: scripts/validate_manifest.py:46-73, manifest.json:4-10

Validation and Safety Invariants

The project enforces strict safety invariants through scripts/validate_manifest.py and unit tests. These checks are mandatory CI gates that must pass before any publication can occur.

Sources: REVIEW.md:7-13, scripts/test_workflow_safety.py:35-115

Mandatory Checks

1. Field Completeness: Every entry in the active list must contain all 11 required fields.
2. Unique Naming: Plugin names must be unique across the manifest to prevent collision in the registry.
3. Commit Integrity: The source_commit must be a 40-character lowercase hex string.
4. Upstream Verification: If requested (via --verify-upstream), the script uses git ls-remote to ensure the upstream tag points exactly to the source_commit.
5. Target Consistency: All exclude_targets must exist within the default_targets list.

Sources: scripts/validate_manifest.py:14-26, 78-106, 118-135

A sequence diagram depicting the verification process between the local manifest and upstream repository tags.

Sources: scripts/validate_manifest.py:108-135, REVIEW.md:27-35

Integration with Spec Generation

The information stored in manifest.json is consumed by scripts/gen_spec.py to generate the final numan-registry package specification. The manifest provides the "Source Provenance" block, which includes the Git URL, the specific revision (source_commit), and the cargo_name (plugin_bin). This ensures that the signed registry index maintains a clear link back to the original source code.

Sources: scripts/gen_spec.py:30-47, 105-135

# snippet from scripts/gen_spec.py showing manifest usage
return {
    "owner": entry["owner"],
    "name": entry["name"],
    "description": entry["description"] + " CI-built...",
    "source": {
        "git": f"https://github.com/%7Bentry%5B%27repo%27%5D%7D%22%2C
        "rev": entry["source_commit"],
        "cargo_name": entry["plugin_bin"],
    },
    # ... artifact targets mapped from packaged rows
}

Sources: scripts/gen_spec.py:118-130

Summary

The manifest.json is the configuration backbone of the numan-plugins repository. It defines the "what" and "where" of the build process, enforcing immutable references to upstream source code. By combining plugin metadata with target-specific runner mappings and strict validation scripts, it ensures that the resulting binary artifacts are reproducible, traceable, and compatible with the target Nushell versions specified in the nu_version field.

Sources: README.md:14-26, manifest.json:2-6