Package Types & Constraints

Relevant source files

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

• src/core/package.rs
• src/core/platform.rs
• src/core/nu_version.rs
• src/cmd/search.rs
• src/cmd/info.rs
• src/nupm_compat/classify.rs
• README.md

Numan categorizes Nushell ecosystem artifacts into distinct Package Types, each governed by specific environmental and versioning Constraints. These constraints ensure that packages are only installed and activated when the host platform (OS, Architecture, Libc) and the local Nushell version meet the requirements defined by the package maintainer.

The system is designed to keep installs inert until activation, using a resolver to validate compatibility before any mutation occurs. This approach prevents "broken" environments where a package is installed but cannot run due to ABI mismatches or missing platform support.

Package Type Taxonomy

Numan supports four primary package types, each with a different level of integration and activation support.

Package Type	Description	Activation Support
Plugin	Compiled binaries that extend Nushell via its plugin ABI.	Yes (via Nu plugin registry)
Module	Nushell source files (.nu) providing commands and constants.	Yes (via managed vendor autoload)
Script	Individual Nushell scripts intended for direct execution.	No (Install-only; deferred)
Completion	Shell completion definitions for Nushell or other shells.	No (Install-only; deferred)

Sources: src/core/package.rs:24-33, README.md:95-104

Data Structure: PackageType

The PackageType enum defines the supported categories. It is serializable and used throughout the registry and CLI to determine how a package should be displayed and handled during activation.

pub enum PackageType {
    Plugin,
    Module,
    Script,
    Completion,
}

Sources: src/core/package.rs:24-33

Environmental Constraints

Environmental constraints are defined by the platform triple, which consists of the Operating System, Architecture, and C Library (Env).

Platform Detection

Numan detects the host platform at compile-time using #[cfg(target_env)] rather than runtime environment variables to ensure consistency.

Artifact Targeting

For Plugins, the TargetArtifact structure maps a specific platform triple to a unique download URL and SHA256 hash. A plugin package version is considered incompatible if it does not contain a target entry matching the host's triple.

Sources: src/core/package.rs:136-146, src/cmd/info.rs:44-54

Versioning & Compatibility Constraints

Numan employs a strict resolution logic to match packages against the host's Nushell version.

Nushell Version Constraints

Every VersionEntry in a package manifest includes a nu_version field, which is a semver range string (e.g., ">=0.113.0 <0.114.0"). This is critical for plugins, which are locked to specific Nushell ABI versions.

Resolution Logic

The Resolver component classifies version compatibility into several states:

• Compatible: Matches both Nu version and platform.
• NuTooOld / NuTooNew: The local Nushell version falls outside the package's required range.
• MissingPlatform: The package version does not provide a binary for the current OS/Arch.

Sources: src/core/resolve.rs, src/cmd/search.rs:135-147

nupm Compatibility Constraints

Numan provides interoperability with nupm packages but enforces strict layout constraints during the classification phase to ensure safety.

Classification Criteria

A nupm package is classified using a four-step process to determine if it is an ImportableModule or an unsupported type.

Status	Reason
ImportableModule	Valid metadata, safe layout, no custom build, no dependencies.
UnsupportedCustomBuild	Contains a build.nu script or type is set to custom.
UnsupportedDependencies	Manifest lists external dependencies (unsupported in Phase 6).
UnsafeFilesystemLayout	Contains symlinks, reparse points, or invalid file names.
DeferredScript	Package type is script (activation deferred).

Sources: src/nupm_compat/classify.rs:12-22, src/nupm_compat/classify.rs:88-120

Security Constraints in Imports

Numan refuses to import packages that violate filesystem safety rules:

1. No Symlinks: The metadata file and module entry points must not be symlinks.
2. Safe Names: Package names must not contain special characters or path traversal sequences.
3. Containment: All files must reside within the package root.

Sources: src/nupm_compat/classify.rs:35-85, src/nupm_compat/walk.rs

Summary of Constraints by Component

Component	Responsibility	Relevant Files
Platform	OS/Arch/Triple detection	src/core/platform.rs
NuVersion	Nu binary detection and range parsing	src/core/nu_version.rs
Package	Defining Type and Artifact mappings	src/core/package.rs
Resolver	Intersection of Nu version and Package constraints	src/core/resolve.rs
Classify	nupm structural and behavioral validation	src/nupm_compat/classify.rs

These constraints ensure that Numan remains a reliable package manager by strictly validating the environment before attempting to modify the user's Nushell configuration. Incompatibility is surfaced early in search and info commands to guide the user toward compatible versions or managed Nushell upgrades.

Sources: src/cmd/search.rs, src/cmd/info.rs, src/cmd/try_cmd.rs