Nu Version Constraints
Relevant source files
The following files were used as context for generating this wiki page:
Nu Version Constraints define the compatibility requirements between packages (plugins, modules, scripts, and completions) and specific versions of the Nushell (Nu) engine. These constraints ensure that a package is only installed or activated in environments where the underlying Nushell version meets the package's operational requirements. Sources: README.md:1-5, registry/index.json:1-10
Within the Numan registry, every package version entry includes a mandatory nu_version field. This field uses a comparison syntax to specify compatible ranges, which is vital for maintaining stability across the rapidly evolving Nushell ecosystem. The registry tooling also uses these constraints to generate compatibility matrices for human review. Sources: schemas/index-v1.json:75-80, scripts/render_catalog_compat.py:1-10
Constraint Syntax and Schema
The nu_version field is a required string in the registry index for every package version. It follows a semantic-versioning-based comparison grammar that supports wildcards and range comparators. Sources: schemas/index-v1.json:76, registry/index.json:20
Comparison Logic
The registry supports standard comparison operators and wildcards. The implementation in the registry's landing page and tooling handles the following:
- Wildcard (
*): Matches any Nushell version. - Minor Wildcards: Supports formats like
0.113.x,0.113.X, or0.113.*. - Comparators: Supports
>=,<=,>,<, and=. - Ranges: Multiple tokens separated by spaces (e.g.,
>=0.113.0 <0.114.0) are evaluated as a logical AND.
Sources: registry/index.html:470-495, scripts/render_catalog_compat.py:27-30
Schema Definition
The JSON schema enforces the presence and format of these constraints within the versions array of a package object. Sources: schemas/index-v1.json:75-80
| Field | Type | Description |
|---|---|---|
nu_version | string | The version requirement for the Nushell engine. |
verified_with | array | A list of exact MAJOR.MINOR.PATCH versions where the package has been proven to work. |
Sources: schemas/index-v1.json:76-85
Compatibility Categorization (Banding)
To make large catalogs human-readable, the Numan registry uses a "banding" system to group packages by their Nushell compatibility. This is primarily handled by the render_catalog_compat.py script and visualized in the catalog-compat.md documentation. Sources: scripts/render_catalog_compat.py:20-25, README.md:15-20
The Banding Process
Bands are derived from the lower bound of the constraint. For example, a constraint of >=0.114.0 or >0.113.0 results in a band of 0.114. Sources: scripts/render_catalog_compat.py:46-60
The diagram shows the logic used to categorize constraints into coarse "bands" for documentation. Sources: scripts/render_catalog_compat.py:46-64
Validation and Evidence
Numan requires technical evidence that a package actually functions within its claimed nu_version range before it can be promoted to the official registry. Sources: README.md:95-105
Lifecycle Proving
The verified_with field stores a list of exact Nushell versions (e.g., 0.113.1) that have passed a lifecycle-prove.py check. This check involves installing the package into a clean root with a real Nushell binary and confirming it can be registered and activated. Sources: README.md:106-115, scripts/validate_candidate.py:165-175
Validation Workflow
The validate_candidate.py script orchestrates the verification of new package specifications. Sources: scripts/validate_candidate.py:1-15
Sequence of events during candidate validation including the mandatory lifecycle proof for activatable packages. Sources: scripts/validate_candidate.py:80-150
Automated Generation and Updates
Registry candidates are often bootstrapped by analyzing upstream Cargo.toml files to find nu-plugin dependency versions, which serve as a nu_constraint_hint. Sources: scripts/gen_candidate.py:90-100
Update Procedures
When the Nushell project releases a new version, the registry must be updated:
- Discovery: Identify packages needing updates or new Nushell version support. Sources: scripts/gen_candidate.py:120-130
- Linting: Ensure the
nu_versionin the index agrees with CI-built plugin manifests. Sources: README.md:40-45 - Rendering: Regenerate
docs/catalog-compat.mdto reflect the new compatibility matrix. Sources: scripts/render_catalog_compat.py:140-150
Summary
Nu Version Constraints are the mechanism by which Numan manages compatibility in a version-sensitive environment. By combining strict JSON schema enforcement, automated banding for documentation, and mandatory "lifecycle-prove" evidence, the registry ensures that users receive functional plugins and modules tailored to their specific version of Nushell. Sources: README.md:115-120, scripts/render_catalog_compat.py:115-120