feat: first-class third-party completion package activation (#15)

Merged
TO
3d ago
+3237-116

Closes #15.

What this does

First-class third-party completion package activation, following the script activation pattern shipped in #14. Design contract: docs/specs/2026-10-29-completion-activation-design.md.

  • Registry spec gains a nu-completion activation kind with declared targets: targets: [{command, path, kind}], where kind is "static" or "command-backed" (declared, never inferred). validate_completion_targets() mirrors script validation: non-empty, command-name grammar, Nu reserved keywords rejected, duplicate commands/paths rejected, safe package-relative .nu paths only.
  • Install persists completion_targets in the lockfile and never executes package code. A nu-completion kind on a non-completion package type is rejected at install.
  • Activation renders each target into the managed numan.nu autoload file as a # numan:completion <owner/name> <command> marker plus use "<abs path>" *, sorted by scoped ID then command, through the existing candidate-validation, journal, drift, and recovery machinery. Ground truth is a per-package completion_activation lockfile record with the same Nu-identity fields as script_activation.
  • Target ownership is exclusive across active completion packages: a command already owned by a different active completion package rejects activation instead of silently shadowing it.
  • numan info shows declared targets and kinds before activation, and for command-backed targets states that the provider can execute code during completion (only when Nushell requests one, never at install or activation).
  • Mirrored everywhere script_activation is consulted: deactivate, init --refresh re-resolution/regeneration, remove, update, doctor (new activation.completion_stale finding), activation switch, autoload recovery/state, and the TUI.
  • README support table now lists completion packages as Supported via numan activate, and the stale post-#14 Script row is fixed in the same pass. CHANGELOG entry distinguishes completion packages from numan completions <shell> (Numan's own generator).

Verification

  • cargo test: 1,034 passed, 0 failed, 31 ignored (full suite, counted from per-binary results)
  • cargo clippy -- -D warnings: clean
  • cargo fmt --check: clean
  • python3 scripts/check_workflows.py: 12 workflow files validated
  • Real-Nu acceptance (ignored test, run explicitly against Nu 0.116.1): a fresh session loading the managed file has the fixture extern defined with its positional bound to the declared completer; after deactivation it is gone; user config untouched. Nu exposes no non-interactive completion querying, so the test proves this honest equivalent and says so in its comments.
  • New fixture suite tests/completion_activation_test.rs: validation, rendering + lockfile record, already-active skip, cross-package conflict rejection, traversal/missing-target rejection, deactivation removing only that package's lines.

Notes

  • Deviations from a blanket mirror of the script rules, both commented in code: numan try keeps completions install-only only when they declare no targets (a completion with declared targets activates normally), and numan list reports completion packages as "installed" like modules/scripts (per-Nu state is on activate --list).
  • Follow-up, separate from this PR: the 15 completion packages in the live registry still declare no activation targets, so they cannot activate until numan-registry adds their declarations.

Summary by CodeRabbit

  • New Features
    • Completion packages with declared targets can now be activated and deactivated alongside other Nushell packages. Activated targets are loaded in Nushell, and deactivation removes only that package’s contribution.
    • numan info shows declared completion targets and notes when a provider may run during completion requests.
  • Safeguards
    • Installation and activation do not run completion providers. Conflicting command ownership and invalid targets are rejected.
    • Active completion packages must be deactivated before they can be updated or removed.
  • Documentation
    • Updated the README and changelog with completion package support and activation details.