Version Resolution

Version Resolution & Nu Constraints

Version resolution in Numan is the process of selecting compatible package versions based on registry metadata, environment constraints, and inter-package dependencies. Unlike general package managers, Numan enforces strict Nu version matching, ensuring that plugins and modules are only resolved and activated if they satisfy the compatibility requirements of the host Nushell environment.

The resolution logic ensures that artifacts are platform-safe, reproducible via lockfiles, and verified against registry signatures. This system prevents "broken" installations where a package might be successfully downloaded but fail to load due to breaking changes in Nushell's plugin API or module syntax.

Nu Version Detection & Constraint Matching

The core of Numan's resolution system is the NuVersion struct, which handles the detection of the local Nushell version and evaluates if a package's constraints are satisfied.

Version Detection

Numan detects the current Nushell version by executing nu --version. The output is parsed into a structured format containing major, minor, and patch components. This detection is critical for ensuring that resolved packages will actually function in the user's environment.

flowchart TD
    Start[Detect Nu Version] --> Exec[Invoke 'nu --version']
    Exec --> Parse{Parse Output}
    Parse -->|Success| Struct[Create NuVersion Struct]
    Parse -->|Failure| Error[Bail with Context]
    Struct --> Match[Evaluate Package Constraints]

Loading

Constraint Syntax

Numan supports several types of version constraints in registry metadata. These allow package authors to pin their artifacts to specific Nushell releases or ranges.

Constraint Type	Example Syntax	Description
Wildcard	*	Matches any Nushell version.
Minimum	>=0.113.0	Matches versions equal to or greater than the specified version.
Range	>=0.113.0 <0.114.0	Matches versions within a specific major/minor boundary.
Exact Minor	=0.113.x	Legacy format for matching a specific minor release regardless of patch.
Comparison	>, <=, <	Standard semver-like comparison operators.

Package Resolution Logic

Resolution occurs when a user requests an installation (e.g., numan install owner/name). The resolver must navigate the registry index to find the best candidate.

Resolution Steps

1. Fetch Registry Metadata: Retrieve the VersionEntry for the requested package.
2. Platform Verification: Ensure the package provides artifacts compatible with the host OS and architecture (e.g., x86_64-unknown-linux-gnu).
3. Nu Compatibility Check: Compare the detected NuVersion against the nu_version field in the package's metadata.
4. Dependency Resolution: Identify any mandatory dependencies. In current phases, packages with external dependencies are installable but may have restricted activation.

sequenceDiagram
    participant CLI as "numan install"
    participant Resolver as "src/core/resolve.rs"
    participant Registry as "Registry Index"
    participant Nu as "Local Nu binary"

    CLI->>Nu: nu --version
    Nu-->>CLI: 0.113.1
    CLI->>Resolver: Resolve owner/pkg
    Resolver->>Registry: Fetch VersionEntries
    Registry-->>Resolver: [v1.0.0, v1.1.0]
    Note right of Resolver: Check nu_version constraints
    Resolver->>Resolver: Filter by Platform & NuVersion
    Resolver-->>CLI: Selected Version + Artifact URL

Loading

Lockfile Pinning (Reproducibility)

Once a version is resolved, Numan generates or updates a Lockfile v2. This file serves as the ground truth for the environment, pinning the exact version, payload hash, and installation origin.

Lockfile Entry Data

A resolved entry in the lockfile includes the following metadata to ensure reproducibility:

• revision_id: A unique identifier computed from the payload directory.
• payload_sha256: The hash of the artifact to prevent tampering.
• nu_version: The version of Nushell the package was resolved against.
• origin: Indicates if the package came from a registry or a nupm import.

Activation Constraints & Drift Detection

Activation is a separate step from installation. Even if a package is successfully resolved and installed, it cannot be activated if the environment has drifted.

Activation Identity

A package is considered "active" only when its activation record matches the current environment. Numan checks:

1. Nu Executable Hash: Ensures the nu binary hasn't been replaced by a different version.
2. Nu Version: Matches the version recorded during resolution.
3. Vendor Autoload Path: (For modules) Ensures the managed numan.nu file is still in the correct system location.

graph TD
    A[numan activate] --> B{Nu Version Changed?}
    B -->|Yes| C[Block: Require numan init --refresh]
    B -->|No| D{Hash Changed?}
    D -->|Yes| C
    D -->|No| E[Proceed with Activation]
    E --> F[Update Managed Files/Plugins]

Loading

Summary

The "Version Resolution & Nu Constraints" system provides a safety layer for Nushell's extensible architecture. By strictly enforcing Nu version matching during the resolution phase and verifying binary identity during activation, Numan ensures that the package ecosystem remains stable across Nushell upgrades. This logic is codified in src/core/resolve.rs and src/core/nu_version.rs, with the Lockfile serving as the authoritative record of these resolutions.