nupm Interoperability

nupm Interoperability Overview

Introduction

The nupm interoperability system in Numan provides a safe, read-only mechanism for discovering, inspecting, and importing Nushell packages from an existing nupm installation. This feature facilitates a one-way migration path into Numan's immutable revision store without modifying nupm's state or configuration files. It ensures that Numan and nupm retain separate ownership domains: Numan manages $NUMAN_ROOT, while nupm manages NUPM_HOME.

Core Principles and Constraints

Interoperability is governed by strict architectural boundaries to prevent cross-contamination between package managers.

• Read-Only Discovery: Numan only reads data from NUPM_HOME until an explicit import is triggered by the user.
• Snapshot-Based Import: Imports are immutable snapshots, not live symlinks. Edits in the nupm source path do not automatically affect Numan.
• No Bidirectional Sync: Numan never writes to NUPM_HOME or modifies nupm-managed metadata/overlays.
• Constrained Metadata Parsing: Numan uses a pure-Rust parser for nupm.nuon to avoid executing arbitrary Nushell code during discovery.
• No Execution of nupm Hooks: Numan does not execute build.nu or other custom package hooks.

Coexistence Architecture

The following diagram illustrates the relationship between the two package managers and the one-way flow of data during an import.

graph TD
    subgraph NUPM_DOMAIN [nupm Domain]
        NH[NUPM_HOME] --> NM[nupm.nuon Metadata]
        NH --> NP[Package Payloads]
    end

    subgraph NUMAN_DOMAIN [Numan Domain]
        NR[$NUMAN_ROOT] --> LF[Lockfile v2]
        NR --> RS[Immutable Revision Store]
        NR --> NI[nupm-imports.json]
    end

    NM -.->|Read-Only Inspect| NC[nupm_compat Module]
    NP -.->|One-Way Snapshot| NC
    NC -->|Stage & Hash| RS
    NC -->|Record Provenance| NI
    NC -->|Update Selection| LF

Loading

The diagram shows that Numan's nupm_compat module acts as a bridge, performing read-only inspections and staging snapshots into Numan's store.

Package Classification and Eligibility

Numan performs a multi-step classification process to determine if a nupm package is eligible for import. This logic is primarily implemented in src/nupm_compat/classify.rs.

Compatibility Matrix

Numan supports a narrow profile for "compat-schema-v1" imports.

Feature	Support Status	Criteria for Rejection
Package Type	module	script, plugin, or custom types
Metadata	nupm.nuon (subset)	Unknown/malformed NUON or missing fields
Build Hook	Absent	Presence of build.nu
Dependencies	None	External dependencies declared in metadata
Entry Point	mod.nu	Missing mod.nu or entry outside package root
FS Layout	Safe directories	Symlink escapes, path traversals, or pipes

Classification Logic

The classification process involves checking both the metadata and the physical filesystem layout of the nupm package.

flowchart TD
    Start[classify_source_root] --> PathCheck{Path Safe?}
    PathCheck -- No --> Unsafe[UnsafeFilesystemLayout]
    PathCheck -- Yes --> MetaCheck{Metadata Valid?}
    MetaCheck -- No --> Invalid[InvalidMetadata]
    MetaCheck -- Yes --> BuildCheck{build.nu Present?}
    BuildCheck -- Yes --> Unsupp[UnsupportedCustomBuild]
    BuildCheck -- No --> TypeCheck{Type == module?}
    TypeCheck -- No --> Deferred[Deferred/Unknown]
    TypeCheck -- Yes --> EntryCheck{mod.nu Exists?}
    EntryCheck -- No --> Unsafe
    EntryCheck -- Yes --> Importable[ImportableModule]

Loading

The flow ensures that only standard module packages with no external side effects or complex dependencies are accepted.

The Import Process

The numan nupm import command facilitates the migration of a package into Numan's revision store.

1. Discovery: Resolves NUPM_HOME via the --nupm-home flag or the NUPM_HOME environment variable.
2. Validation: Parses metadata and runs the classifier to ensure the package meets the compatibility contract.
3. Staging: Copies the approved payload files into a temporary staging area within $NUMAN_ROOT.
4. Identity: Requires an explicit scoped identity (e.g., owner/name) via the --as flag.
5. Promotion: Calculates a deterministic payload hash and moves the staging directory into Numan's immutable package storage.
6. Persistence: Records provenance in state/nupm-imports.json and updates the Numan lockfile.

Import Lifecycle and Journaling

To handle potential crashes during the transition from nupm to Numan, the system uses a lifecycle journal.

sequenceDiagram
    participant User
    participant Cmd as "numan nupm import"
    participant Journal as "Lifecycle Journal"
    participant RS as "Revision Store"
    participant LF as "Lockfile"

    User->>Cmd: run import --as owner/pkg
    Cmd->>Journal: Write Stage: Prepared
    Cmd->>RS: Copy to Staging
    Cmd->>Journal: Update Stage: PayloadsStaged
    Cmd->>RS: Promote to Immutable Path
    Cmd->>Journal: Update Stage: PayloadsPromoted
    Cmd->>LF: Commit Selection
    Cmd->>Journal: Clear Journal

Loading

This sequence ensures that interrupted imports can be reconciled on the next Numan execution.

Provenance Tracking and Drift Detection

Numan stores specific metadata to track the relationship between an imported package and its nupm source. This is stored in state/nupm-imports.json.

Provenance Data Model

The provenance file tracks the original source path and metadata hashes to detect changes.

// Descriptive JSON structure for nupm-imports.json
{
  "version": 1,
  "imports": {
    "owner/name": {
      "trust_level": "local_foreign_import",
      "nupm_source_path": "...",
      "nupm_metadata_sha256": "...",
      "imported_payload_sha256": "...",
      "imported_at": "..."
    }
  }
}

Drift Detection (numan nupm diff)

The diff command allows users to compare the current state of the nupm source tree with the version snapshot in Numan. It identifies several states:

• Unchanged: The source matches the import.
• Metadata Changed: nupm.nuon has been modified.
• Payload Changed: Files within the nupm package directory have changed.
• Source Missing: The original nupm path no longer exists.

Conclusion

The nupm interoperability system provides a secure bridge for users to migrate local packages into Numan's managed environment. By enforcing a read-only contract with the nupm home and using immutable snapshots for imports, Numan maintains its core design principles of inert installation and explicit activation while supporting the existing Nushell ecosystem. The system is designed for safety, utilizing a constrained metadata parser and a strict classification engine to avoid executing untrusted local code during the migration process.

See also

• Canonical matrix: docs/nupm-compatibility.md
• nupm Inspect and Import
• nupm Drift Detection