nupm Inspect and Import

nupm Inspect & Import

Numan provides a compatibility layer for interoperating with nupm, the existing Nushell package manager. The "nupm Inspect & Import" system allows users to discover, classify, and migrate compatible Nushell modules from a NUPM_HOME directory into Numan's immutable revision store. This system is designed for one-way migration, ensuring Numan retains separate ownership of its payloads while providing drift detection against the original nupm source.

The core philosophy of this module is safe coexistence. Numan treats nupm home as read-only, never modifying nupm's internal state or metadata. Imports are treated as snapshots; once a package is imported, Numan uses its own content-addressed copy, and subsequent changes to the nupm source require an explicit re-import.

Architecture and Data Flow

The nupm compatibility system is structured as a subcommand group within the Numan CLI. It follows a multi-stage process: discovery, classification, and journaled import.

flowchart TD
    subgraph Discovery
        A[NUPM_HOME] --> B{Scan Home}
        B --> C[Source Roots]
        B --> D[Installed Only]
    end

    subgraph Classification
        C --> E[Classify Root]
        E --> F{Compatibility?}
        F -- Eligible --> G[ImportableModule]
        F -- Ineligible --> H[Rejection Reason]
    end

    subgraph Import_Transaction
        G --> I[Acquire Lock]
        I --> J[Stage Payload]
        J --> K[Hash & Verify]
        K --> L[Promote to Root]
        L --> M[Update Lockfile]
    end

Loading

The diagram shows the transition from raw nupm source files through the classification engine into the Numan immutable store.

Classification Engine

The classification logic determines if a nupm package is eligible for import. Numan primarily supports module types that contain a mod.nu entry point and no external dependencies or custom build scripts.

Compatibility Statuses

The system categorizes packages into several NupmCompatibility variants:

Status	Description
ImportableModule	Fully compatible; eligible for Numan import.
DeferredScript	Script-type packages (unsupported in Phase 6).
UnsupportedCustomBuild	Packages containing a build.nu file.
UnsupportedDependencies	Packages declaring external Numan dependencies.
InvalidMetadata	Malformed or missing nupm.nuon file.
UnsafeFilesystemLayout	Detected symlink escapes or unsafe path traversal.
UnknownType	Package types not recognized by the classifier.

Security Constraints

Numan enforces strict filesystem safety during classification. It rejects any package where the metadata, entry point, or module tree involves symlinks or reparse points that might lead to path traversal escapes.

Import Lifecycle

The import process is a journaled transaction that ensures atomicity. When a user runs numan nupm import, the system performs the following steps:

1. Provenance Tracking: Records the source path, metadata SHA256, and original Git information in state/nupm-imports.json.
2. Staging: approved files are copied into a temporary staging directory under $NUMAN_ROOT.
3. Promotion: Upon successful validation, the staged payload is moved to a versioned, immutable directory: packages/<type>/<owner>/<name>/<version>-<hash>/.
4. Lockfile Integration: The package is added to the Numan lockfile with an origin set to nupm_import.

sequenceDiagram
    participant CLI as Numan CLI
    participant CL as Classifier
    participant JL as Lifecycle Journal
    participant FS as Numan Root

    CLI->>CL: inspect_path(source)
    CL-->>CLI: ImportableModule
    CLI->>FS: acquire_mutation_lock()
    CLI->>JL: Write Prepared Stage
    CLI->>FS: Stage Payload (Copy)
    CLI->>JL: Write PayloadsStaged
    CLI->>FS: Promote to Immutable Path
    CLI->>JL: Write SelectionCommitted
    CLI->>FS: Update Lockfile & nupm-imports.json
    CLI->>JL: Clear Journal

Loading

This sequence ensures that interrupted imports can be recovered or cleaned up via the numan doctor command.

Command Reference

The numan nupm subcommand group provides the primary interface for migration.

Command	Arguments	Description
status	[--nupm-home PATH]	Summarizes nupm home and import eligibility.
inspect	<PATH> | --all	Classifies packages and shows eligibility reports.
import	<PATH> --as ID	Performs a one-way import of a specific module.
import	--manifest <FILE>	Performs a batch import from a TOML mapping file.
diff	<ID>	Compares Numan's revision against the nupm source.

Drift Detection

Since Numan creates a disconnected snapshot of the nupm source, the diff command is used to detect "drift." Numan compares the current SHA256 of the files in the nupm source directory against the manifest recorded during the last import.

// Drift detection statuses from src/nupm_compat/drift.rs
pub enum DriftStatus {
    Unchanged,
    SourceMissing,
    MetadataChanged,
    PayloadChanged,
    UnsafeSourceChange,
    CannotCompare { reason: String },
}

If drift is detected, the user must explicitly run a re-import to adopt the changes. Numan retains the previous revision until a numan gc is performed.

Conclusion

The nupm Inspect & Import system provides a bridge for users transitioning to Numan's registry-based and lockfile-oriented workflow. By leveraging a strict classification engine and journaled transactions, it ensures that local nupm modules are migrated safely without compromising the integrity of the Numan environment or the original nupm installation.