First-class script package activation and lifecycle

[tonythethompson]

Problem

PackageKind::Script can currently be installed as a verified artifact but has no supported activation contract. A package manager should not represent a script as installable while leaving users to discover a path, manually edit configuration, or guess how it is invoked.

Goal

Define and implement a safe, reversible way for a script package to expose explicitly declared Nushell entry points after numan activate, without executing package code during install or activation.

Proposed contract

• A script package manifest declares one or more entry points, each with a stable public command name and a package-relative .nu target.
• Validation rejects missing targets, duplicate entry-point names, traversal outside the package root, and collisions with another active Numan-owned entry point.
• Activation creates only Numan-owned generated state; it must not edit arbitrary user config files.
• A declared entry point is callable from a fresh interactive Nushell session after activation.
• Invocation forwards arguments, stdin, stdout, stderr, and exit status faithfully to the package script.
• Package script code is not evaluated at install, inspection, lock, update, or activation time. It runs only when the user invokes its declared command.
• Deactivation, update, recovery, and drift handling follow the existing owned-file / journal model used for module activation.

Security and UX requirements

• numan inspect shows every public script command before activation.
• Activation output identifies the generated command names and collision outcome.
• No implicit PATH takeover, shell-profile rewrite, or auto-run behavior.
• The implementation must define deterministic precedence when a module, plugin, and script claim the same public command name; the default should be rejection rather than shadowing.

Acceptance criteria

• Fixture coverage for single and multi-entry packages, missing entries, traversal attempts, collisions, interruption recovery, deactivate/re-activate, and update.
• Real-Nu acceptance tests prove a script is callable in a clean session on Linux, macOS, and Windows.
• The generated activation file is syntax-validated before replacement and remains ownership-marked.
• Documentation includes the manifest schema, invocation model, conflict behavior, and non-goals.

Non-goals

• Arbitrary shell scripts or binaries.
• Auto-executing scripts on install/activate.
• Hook behavior; that needs a separate explicit capability model.

[tonythethompson]

Context note (2026-07-22)

Official registry already lists install-only script/completion/hook-style packages (e.g. nu_script_wttr, custom/git completions, nu-hooks). Install works; first-class activation for scripts remains this issue’s scope (still open).