Package Installation
Relevant source files
The following files were used as context for generating this wiki page:
Package installation in Numan is designed to be an inert operation, meaning it strictly handles the downloading, verification, and extraction of artifacts to the local filesystem without automatically modifying the Nushell configuration or registering plugins. This isolation ensures that the environment remains stable until an explicit Activation command is issued.
The installation system manages multiple package types, including plugins, modules, scripts, and completion payloads. It relies on a signed registry for artifact discovery and uses a Lockfile (v2) to pin immutable artifacts, ensuring reproducibility and integrity via SHA256 verification.
Sources: AGENTS.md:144-144, README.md:13-18
Installation Lifecycle
The installation process follows a strict transactional flow to ensure system consistency. This flow includes identity resolution, compatibility checks, artifact retrieval, and state persistence.
High-Level Transaction Flow
The following diagram illustrates the sequence of operations performed during a standard package installation.
The installation transaction ensures that if any step (like verification or extraction) fails, the Numan root remains in a consistent state.
Sources: src/install/transaction.rs:49-247
Core Installation Logic
The install_package function is the primary entry point for the installation transaction. It utilizes several key components:
| Component | Responsibility |
|---|---|
RegistryManager | Loads and verifies the integrity of the registry index using Ed25519 signatures. |
Resolver | Matches requested packages against the current Nushell version and platform triple. |
Download Manager | Handles HTTP retrieval of artifacts with support for resume/caching via .part files. |
Extractor | Supports .zip, .tar.gz, .tar.xz, and .tar formats; extracts to immutable, content-addressed paths. |
Lockfile | Acts as the ground truth for all installed packages and their provenance. |
Sources: src/install/transaction.rs:18-47, README.md:112-118, AGENTS.md:104-106
Compatibility and Resolution
Numan enforces strict compatibility checks during installation to prevent broken environments. The Resolver component evaluates package constraints against the detected environment.
Platform and Version Matching
Installation requires a match for the "Platform Triple" (OS/Arch/Libc), which is determined at compile-time for the Numan binary. Additionally, the resolver respects per-package Nushell version constraints (e.g., >=0.113.0 <0.114.0).
Curated Starters (numan try)
The numan try command simplifies onboarding by selecting a "starter" package tailored to the user's current environment. It searches a list of preferred packages (like idanarye/nu_plugin_skim for Nu 0.114) and offers to install a managed Nushell version if no compatible starter is found for the system's default Nu.
Sources: src/cmd/try_cmd.rs:40-75, src/cmd/try_cmd.rs:168-212
Data Layout and Immutability
Numan utilizes a content-addressed, immutable directory structure for package payloads. This prevents "in-place" overwrites and allows for safe rollbacks and garbage collection.
Payload Paths
Packages are installed into subdirectories based on their type, owner, name, and a version-hash suffix:
<root>/packages/<type>/<owner>/<name>/<version>-<sha8prefix>/
Sources: src/install/transaction.rs:163-172, AGENTS.md:113-113
Lockfile Persistence
The Lockfile v2 stores comprehensive metadata about every installed package, including:
- Provenance: Registry URL, index SHA256, and signing key fingerprint.
- Integrity: Artifact SHA256 and a recomputed
revision_idfor the extracted payload. - Activation Metadata: Captures module import modes (e.g.,
nu-module) at install time so activation can remain independent of the registry.
Sources: src/install/transaction.rs:253-305, AGENTS.md:38-40
Mutation Safety and Recovery
To prevent data corruption during installation, Numan implements several safety mechanisms:
- Mutation Lock: All mutating commands (install, remove, update) must acquire an advisory filesystem lock (
acquire_mutation_lock) to prevent concurrent modifications to the same root. - Snapshots: A pre-mutation snapshot of the lockfile is created before the directory is modified, allowing for recovery if the transaction is interrupted.
- Atomic Writes: Lockfiles and journals are updated using atomic renames (temporary file write followed by a move) to prevent partial write corruption.
- Journals: Lifecycle journals (under
state/) track pending operations to facilitate crash recovery.
Sources: src/cmd/remove.rs:40-40, src/install/transaction.rs:230-240, AGENTS.md:148-152, REVIEW.md:25-30
Conclusion
The package installation system in Numan prioritizes safety and reproducibility by maintaining a strict separation between installation and activation. By combining cryptographic verification, environment-aware resolution, and immutable storage, Numan provides a robust foundation for managing Nushell's expanding ecosystem across Linux, macOS, and Windows.