First-class third-party completion package activation

[tonythethompson]

Problem

Numan recognizes completion packages but does not yet activate third-party completion definitions. numan completions currently generates shell completions for Numan itself, which is useful but is a separate capability.

Goal

Let a package safely contribute Nushell command completions, with explicit target ownership and exact reversible activation.

Proposed contract

• A completion package manifest declares each completion target explicitly: the command or external-command surface it augments, the package-relative source, and its completion kind.
• Activation composes package contributions into a Numan-owned generated Nu file/profile rather than editing arbitrary user modules or config.
• The generated representation must preserve Nushell-native completion behavior, including command-backed completion providers where supported.
• Completion providers are not invoked during install, inspect, lock, update, or activation. They run only when Nushell requests completion.
• The system rejects ambiguous target ownership and incompatible duplicate bindings by default; it must not silently replace another active package's completion.
• Deactivation removes only the package's contribution and leaves user-authored completion configuration untouched.

Security and UX requirements

• numan inspect shows the exact commands a package will augment and whether the provider can execute code during completion.
• Activation requires explicit user intent and prints the resulting bindings.
• Completion package metadata cannot use path traversal or refer outside the immutable package root.
• The generated file uses the same syntax-validation, journal, recovery, and ownership-marker discipline as module activation.

Acceptance criteria

• Fixture coverage for static and command-backed providers, multi-command packages, target conflicts, malformed sources, traversal attempts, deactivation, interrupted activation, and updates.
• Real-Nu acceptance proves a clean interactive session receives and removes a contributed completion without modifying user config files.
• Documentation distinguishes Numan's own shell-completion generator from installable Nushell completion packages.
• The final schema documents extension points and explicitly unsupported completion forms.

Non-goals

• Managing Bash/Fish/Zsh/PowerShell completion packages for arbitrary tools.
• Executing completions at package install or activation time.
• Merging arbitrary user-authored completion files.

[tonythethompson]

Context note (2026-07-22)

Official registry includes completion packages as install-only today. Activation/lifecycle for third-party completions remains open here.