Nu Paths Cache

Nu Paths Cache

The Nu Paths Cache is a core architectural component of Numan used to store probed information about the local Nushell environment. Because Numan follows an "inert install" model, it must strictly separate package installation from activation. The cache provides the necessary metadata—such as executable hashes, version constraints, and vendor directory locations—to ensure that Activation only occurs when the environment matches the state recorded during the initial configuration.

This system ensures that Numan can detect "drift" (changes in the Nu binary or environment) and prevent broken registrations or autoloads. The cache is primarily populated and updated via the numan init and numan init --refresh commands.

Architecture and Data Structure

The cache is encapsulated in the NuPaths struct. It stores critical identity markers that link a Numan installation to a specific Nushell instance.

The NuPaths Struct

The structure contains platform-specific paths and identity hashes:

Field	Type	Description
nu_executable	String	Absolute path to the Nushell binary.
nu_version	String	The semver version of the detected Nushell.
plugin_registry_path	String	Path to Nushell's internal plugin registry file.
nu_executable_hash	String	SHA-256 hash of the Nushell binary to detect upgrades/changes.
platform	String	Target triple (OS/Arch) detected at compile time.
data_dir	Option<String>	The $nu.data-dir location.
vendor_autoload_dirs	Vec<String>	List of all directories Nushell searches for autoload files.
vendor_autoload_dir	Option<String>	The specific Numan-safe target for module autoloads.

Identity Mapping

The following diagram illustrates how NuPaths acts as the bridge between the Nushell environment and Numan's internal state.

graph TD
    subgraph Nushell_Environment
        EXE[nu executable]
        VER[$nu.version]
        VENDORS[$nu.vendor-autoload-dirs]
    end

    subgraph Nu_Paths_Cache
        NP_EXE[nu_executable_hash]
        NP_VER[nu_version]
        NP_TARGET[vendor_autoload_dir]
    end

    subgraph Numan_State
        LOCK[Lockfile Activation Records]
        AUTOLOAD[numan.nu Managed File]
    end

    EXE -->|Hashed| NP_EXE
    VER --> NP_VER
    VENDORS -->|Selected| NP_TARGET

    NP_EXE -.->|Validation| LOCK
    NP_VER -.->|Validation| LOCK
    NP_TARGET -.->|Containment| AUTOLOAD

Loading

The Nu Paths Cache ensures that the current Nushell binary and environment match the parameters used when a package was originally activated.

Environment Probing and Selection

The cache is populated by a "Nu probe"—a static Nushell program executed by Numan to emit machine-readable JSON. This approach avoids ad-hoc line parsing and ensures accuracy across different Nushell versions.

Safe Target Selection Policy

Numan does not use just any writable directory for autoloading. It implements a strict safety policy for the vendor_autoload_dir:

1. It probes Nushell for $nu.data-dir and $nu.vendor-autoload-dirs.
2. it identifies a Numan-safe target, typically <$nu.data-dir>/vendor/autoload.
3. It selects this target only if it exists within the reported vendor-autoload list.
4. If the target is absent, Numan refuses to cache a target, preventing it from writing to system-level or foreign directories.

Probing Sequence

The following sequence diagram shows the interaction during a numan init operation.

sequenceDiagram
    participant CLI as Numan CLI
    participant Probe as Nu Probe Script
    participant NU as Nushell Binary
    participant FS as Filesystem

    CLI->>FS: Locate Nu on PATH
    CLI->>Probe: Execute via 'nu -c'
    Probe->>NU: Query $nu.version, $nu.data-dir
    NU-->>Probe: Environment Data
    Probe-->>CLI: JSON Object
    CLI->>FS: Hash Nu Binary (SHA-256)
    CLI->>CLI: Select safe vendor target
    CLI->>FS: Write nu_state/paths.json

Loading

The probing process creates a frozen snapshot of the Nushell environment to be used for future drift detection.

Drift Detection and Validation

Drift detection is the process of comparing the current Nushell environment against the stored NuPaths cache. Drift prevents Numan from performing mutations (like activate or deactivate) when the environment has changed in a way that might break the installation.

Drift Triggers

A "drift" state is triggered if any of the following change:

• Nu Binary Change: The SHA-256 hash of the nu executable has changed (typically after a Nushell upgrade).
• Version Mismatch: The version string reported by Nu differs from the cache.
• Path Migration: The Nushell data directory or vendor autoload paths have moved.

Validation Logic

Before any mutation, Numan performs the following checks:

1. Load NuPaths from $NUMAN_ROOT/nu_state/paths.json.
2. Re-probe the current Nushell environment.
3. Compare hashes and paths.
4. If drift is detected, the user is prompted to run numan init --refresh.

Integration with Activation

The Nu Paths Cache is essential for the activation of both plugins and modules.

• Plugins: A plugin is considered active only if the nu_executable_sha256, nu_version, and plugin_registry_path in the PluginActivation record match the current NuPaths.
• Modules: Module activation is tied to the nu_executable_sha256, nu_version, and the specific vendor_autoload_dir stored in the cache.

Code Context: Nu Path Cache Usage

The cache is stored as a JSON file. Below is the logical layout of the state file:

{
  "nu_executable": "/usr/bin/nu",
  "nu_version": "0.113.0",
  "plugin_registry_path": "/home/user/.config/nushell/plugin.msgpackz",
  "nu_executable_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "platform": "x86_64-unknown-linux-gnu",
  "vendor_autoload_dir": "/home/user/.local/share/nushell/vendor/autoload"
}

Summary

The Nu Paths Cache provides the stability required for Numan to manage Nushell's ecosystem. By caching hashes and environment paths, Numan ensures that its managed files (like numan.nu) and plugin registrations remain valid even as the underlying Nushell installation evolves. When the binary or configuration drifts, the cache acts as a safety gate, requiring an explicit init --refresh to re-validate the environment before any further changes are made.