Update Remove and GC

Update, Remove, and GC

Numan provides a robust set of lifecycle management commands—update, remove, and gc—designed to maintain the health and currency of installed Nushell packages. These commands operate under strict architectural invariants, ensuring that mutations to the system state are journaled, atomic, and safe. While installation is inert, these commands manage the transition of packages through their lifecycle stages, from upgrading to new registry versions to the final pruning of orphaned artifacts.

These lifecycle operations are part of "Phase 5" of the Numan roadmap, introducing Lockfile v2 and a pending-lifecycle.json journal to handle crash recovery during complex mutations.

Shared Mutation Architecture

All lifecycle commands that modify the Numan root (including update, remove, and gc) must follow the project's mutation serialization rules. This involves acquiring an advisory filesystem lock to prevent concurrent destructive operations and utilizing a journal for crash recovery.

Mutation Serialization

To prevent race conditions, Numan uses acquire_mutation_lock(root). This returns an RAII guard; if a second process attempts to acquire the lock on the same root, it fails immediately.

The Lifecycle Journal

Mutations are tracked via the pending-lifecycle.json journal. This allows Numan to reconcile the state if a process is interrupted. The journal tracks operations through stages such as Prepared, PayloadsStaged, PayloadsPromoted, and SelectionCommitted.

flowchart TD
    Start[Command Invoked] --> Lock[Acquire Mutation Lock]
    Lock --> Snapshot[Create Lockfile Snapshot]
    Snapshot --> Journal[Write Pending Lifecycle Journal]
    Journal --> Execute[Execute Mutation]
    Execute --> Commit[Update Lockfile & State]
    Commit --> Cleanup[Clear Journal & Release Lock]

Loading

The diagram shows the standard sequence for any command modifying the Numan state.

Package Update

The update command allows users to detect and apply registry version upgrades for installed packages. It distinguishes between checking for updates and applying them.

Update Workflow

1. Check Mode (--check): Numan queries the synced registry indexes to find newer versions that satisfy the package's nu_version constraints.
2. Application: If updates are found and the user applies them, Numan performs a standard install transaction for the new version.
3. Immutable Payloads: Because Numan uses content-addressed, versioned paths, the update process does not overwrite the old version in place. Instead, it installs the new version to a new directory, updating the lockfile to point to the new revision.

Package Removal

The remove command excises a package from the Numan system. By default, it removes the entry from the lockfile and marks the payload for eventual garbage collection.

Safety and Constraints

• Active Packages: Numan typically prevents the removal of packages that are currently active in Nushell (plugins registered or modules in the autoload file).
• Force Removal: The --force flag allows the removal of a package even if it is currently active.
• Payload Deletion: While the lockfile entry is removed immediately, the physical payload directory is often left for the gc command to clean up, unless the lifecycle journal specifically handles the deletion.

Garbage Collection (GC)

Garbage collection is the process of deleting orphaned payload directories—those that are no longer referenced by any entry in the current lockfile or any valid activation snapshot.

GC Logic

Numan's gc command treats the following as "live roots":

• Every package version entry in the current lockfile.
• Every payload referenced in an immutable activation snapshot.

Any directory under <root>/packages/ that does not correspond to a live root is considered orphaned and is eligible for deletion.

GC Operations Table

Flag	Description	Safety Level
--dry-run	Previews which orphaned payload directories would be deleted without performing the actual deletion.	High
(default)	Deletes all unreferenced payloads and can optionally prune old snapshot directories.	Moderate

graph TD
    Identify[Scan /packages/ directory] --> Filter[Compare against Lockfile & Snapshots]
    Filter --> Orphans[Identify Unreferenced Dirs]
    Orphans --> DryRun{Dry Run?}
    DryRun -- Yes --> Report[Print paths to be deleted]
    DryRun -- No --> Delete[Delete orphaned directories]

Loading

The GC process ensures that immutable payloads are only removed when they are no longer required for potential rollbacks or current usage.

Command Reference Summary

Command	Action	Key Configuration/Flags
numan update	Upgrades installed packages	--check (report only), -v (verbose)
numan remove	Removes package from lockfile	--force (remove despite active status)
numan gc	Deletes orphaned directories	--dry-run (preview only)

Conclusion

The Update, Remove, and GC suite provides a complete management lifecycle that prioritizes system stability. By utilizing immutable payloads and a centralized lockfile as the ground truth, Numan ensures that even failed updates or accidental removals can be managed through snapshots or journaled recovery, while the GC command keeps the filesystem clean of obsolete artifacts.