nupm Interoperability & Migration
Relevant source files
The following files were used as context for generating this wiki page:
Numan provides a compatibility layer for interacting with nupm, the legacy Nushell package manager. This system enables read-only discovery of existing nupm installations, one-way import of compatible module packages into Numan's managed environment, and drift detection to track changes in the original nupm source.
The interoperability design prioritizes safety, ensuring that Numan never modifies NUPM_HOME state while maintaining a strictly journaled transaction for imports. This allows users to migrate to Numan's signed registry workflow without losing local packages.
Sources: README.md:144-156, AGENTS.md:104-108
Package Discovery and Classification
Numan scans NUPM_HOME (typically ~/.config/nupm) to identify packages and determine their eligibility for migration. Discovery is limited to a maximum number of entries to prevent excessive filesystem traversal.
The Classification Pipeline
Each discovered path is passed through a four-step classifier that evaluates metadata (nupm.nuon) and filesystem layout.
The diagram shows the logic used to determine if a nupm package can be safely imported into Numan.
Sources: src/nupm_compat/classify.rs:32-101, src/nupm_compat/discovery.rs:43-98
Compatibility Statuses
| Status | Description |
|---|---|
ImportableModule | High-confidence module with standard layout and no custom build. |
DeferredScript | Scripts or modules containing scripts; activation is currently deferred. |
UnsupportedCustomBuild | Packages containing build.nu or type custom. |
UnsupportedDependencies | Packages declaring external nupm dependencies. |
UnsafeFilesystemLayout | Contains symlinks, reparse points, or missing entry points like mod.nu. |
Sources: src/nupm_compat/classify.rs:13-21, src/nupm_compat/report.rs:188-198
Import Transaction Architecture
Importing a module is a multi-stage, journaled operation designed to be atomic. Numan copies the module payload to its internal versioned layout and records the provenance in a dedicated state/nupm-imports.json file.
Import Stages
- Resolution: Validates the source root and confirms the target
ScopedId. - Staging: Copies the payload to a temporary staging directory within the Numan root.
- Validation: Generates a candidate autoload file and validates it against the Nu binary.
- Promotion: Renames the staging directory to the final immutable versioned path.
- Commit: Updates the
lockfileand the nupm provenance registry.
The sequence of operations during a nupm import, showing how the journal tracks progress for crash recovery.
Sources: src/nupm_compat/import.rs:94-159, AGENTS.md:151-155
Batch Import (Manifests)
Numan supports batch migration via a TOML manifest file. This requires NUPM_HOME to be explicitly configured or available in the environment to resolve relative source paths.
Sources: src/nupm_compat/import.rs:175-220
Drift Detection
Once a package is imported, Numan can track "drift"—discrepancies between the original nupm source and the version currently managed by Numan. This is accomplished by comparing the SHA256 hashes of the source payload and metadata against the records stored at import time.
Drift Status Types
| Status | Condition |
|---|---|
Unchanged | Source and installed version match exactly. |
SourceMissing | The original nupm source path no longer exists. |
MetadataChanged | The nupm.nuon file in the source has been modified. |
PayloadChanged | Files within the source module directory have changed. |
UnsafeSourceTreeChange | The source now contains symlinks or unsafe files. |
Sources: src/nupm_compat/drift.rs:17-24, src/nupm_compat/report.rs:176-186
Security Invariants
The interoperability layer enforces strict security boundaries to prevent path traversal and unauthorized execution:
- Read-Only Source: Numan never writes to the source
NUPM_HOMEdirectory. - Symlink Rejection: Both the discovery and import processes bail if they encounter symlinks or reparse points within the package tree to prevent escaping the Numan root or accessing sensitive host files.
- Safe Nu Invocation: During validation, candidate modules are tested using
nu -n(no-config mode) to ensure they do not trigger unwanted side effects from the user's existing environment. - Mutation Locking: All import operations must acquire the global Numan mutation lock to prevent concurrent state corruption.
Sources: AGENTS.md:104-108, src/nupm_compat/walk.rs:1-40, src/nupm_compat/import.rs:341-351
Summary
The nupm interoperability system provides a bridge for users transitioning to Numan. By combining rigorous classification, journaled import transactions, and continuous drift monitoring, Numan ensures that legacy packages can be safely integrated into its modern, registry-backed management framework without compromising system integrity or data safety.