Numan Overview
Relevant source files
The following files were used as context for generating this wiki page:
Numan is a cross-platform, production-grade package manager specifically designed for Nushell. Written in Rust, it provides a robust system for managing registry-backed plugins, modules, scripts, and completion payloads. Its primary design goal is to solve the pain of managing Nushell packages across different machines, platforms, and Nushell versions by ensuring verified artifacts, reproducible lockfiles, and safe activation workflows.
The system distinguishes strictly between "installation" (which is inert and only affects Numan's internal storage) and "activation" (which integrates the package with the Nushell environment). This isolation ensures that Nushell upgrades or configuration changes do not silently break existing package installations.
Sources: README.md:1-25, AGENTS.md:3-8
Core Architecture and Design Principles
The Numan architecture is built on several non-negotiable invariants that ensure system stability and safety.
Key Architectural Invariants
- Install is Inert: The
numan installcommand only writes to the$NUMAN_ROOT. It never invokes Nushell or modifies global/shell configuration. - Activate is Separate: Modifications to Nushell integration state (like plugin registration or autoload writes) are strictly limited to
activateanddeactivatecommands. - Lockfile as Ground Truth: The lockfile (v2) is the authoritative source for installed states. Derived states, such as module autoload projections, are not authoritative.
- Immutable Payloads: Package payloads are stored in content-addressed, versioned paths. Updates do not overwrite in place; they land in new directories until garbage collection (
gc) is run. - Mutation Serialization: Concurrent destructive operations are prevented via an advisory mutation lock (
acquire_mutation_lock).
Sources: CONTRIBUTING.md:76-90, AGENTS.md:144-156, REVIEW.md:23-33
Package Management Flow
The following diagram illustrates the typical lifecycle of a package within Numan, from discovery to activation.
The flow ensures that every package is verified before it ever touches the Nushell environment.
Sources: README.md:154-180, AGENTS.md:144-152
System Components
Numan is divided into several logical modules that handle specific aspects of package and environment management.
Registry and Resolution
Numan utilizes signed registries to provide verified artifacts. The "official" registry has a built-in trust root in the client.
- Trust Root: Ed25519 signatures verify registry indexes.
- Resolver: Respects per-package Nushell version constraints and platform triples (OS/Arch/Libc).
Sources: README.md:27-42, AGENTS.md:126-128, src/cmd/info.rs:34-55
Managed Activation
Activation behaves differently depending on the package type:
- Plugins: Registered via Nushell's plugin registry. Activation records include the Nushell executable hash and version to ensure compatibility.
- Modules: Managed through a vendor autoload file (
numan.nu) controlled by Numan.
Module Autoload Logic
Numan owns exactly one external file in the Nushell vendor autoload directory: numan.nu. The generation of this file is deterministic and follows a strict validation process.
Validation ensures that a broken module entry does not prevent Nushell from starting.
Sources: src/nu/autoload.rs:1-35, AGENTS.md:136-140
Data Layout and State Management
Numan stores all state and payloads within a platform-specific root directory, which can be overridden using the NUMAN_ROOT environment variable.
Directory Structure
| Path | Purpose |
|---|---|
config.toml | Registry configurations and user defaults. |
lockfile | Pinned installs (authoritative source of truth). |
packages/ | Immutable versioned payloads (content-addressed). |
registries/ | Local cache of synced registry indexes. |
state/ | Journals (activation, lifecycle) and import provenance. |
nu_state/ | Cached Nushell paths and activation identity checks. |
tools/ | Managed Nushell installations (e.g., tools/nushell/<version>/). |
Sources: README.md:243-260, AGENTS.md:46-77, CHANGELOG.md:38-44
Journaling and Recovery
To prevent corruption during crashes or interruptions, Numan uses atomic JSON writes and specialized journals located in the state/ directory:
pending-activation.json: Tracks plugin registration progress.pending-plugin-deactivate.json: Manages unregistration during removal/update.pending-lifecycle.json: Coordinates complex operations likeupdateandnupm import.migration-journal.json: Handles transitions between Nushell version layouts.
Sources: AGENTS.md:158-180, REVIEW.md:34-36
Command Summary
| Command | Category | Description |
|---|---|---|
init | Setup | Probes Nushell and caches paths for activation. |
try | Setup | Installs and activates a curated starter package. |
install | Package | Downloads, verifies, and locks a package. |
activate | Activation | Integrates installed packages with Nushell. |
setup nu | Environment | Manages versioned Nushell binaries under the Numan root. |
nupm import | Migration | One-way import of packages from an existing nupm setup. |
doctor | Health | Diagnoses root health and applies automated repairs. |
snapshot | Safety | Manages immutable activation snapshots for rollback. |
Sources: README.md:264-310, CHANGELOG.md:15-32, AGENTS.md:17-45
Summary
Numan provides a safe, reproducible environment for Nushell package management. By strictly separating payload installation from shell activation and employing rigorous validation (SHA256, Ed25519, and nu -n syntax checks), it ensures that the Nushell ecosystem remains stable even across multiple versions and platforms. Its use of journaling and atomic state updates makes it resilient to interruptions, while features like numan doctor and snapshots provide high maintainability for end-users.