Skip to content

feat: Prefer the replacement when resolving a bare name - #376

Merged
0xmc merged 2 commits into
mainfrom
feat/370-deprecation-resolution
Nov 17, 2026
Merged

0xmc merged 2 commits into
mainfrom
feat/370-deprecation-resolution

Conversation

@0xmc

@0xmc 0xmc commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Once someone adds a deprecated plugin's replacement catalog, installing the plugin by name finds it twice and stops with an ambiguity error.

A bare-name install now skips a deprecated match when its replacement is available, installs the replacement, and prints a note saying which entry it replaced. Installing a whole catalog skips deprecated plugins the user doesn't have, still upgrades the ones they do, and prints the deprecation notice for those.

Test plan

  • A bare-name install with the replacement's catalog added installs from it and prints the note, and two deprecated entries naming each other keep both matches
  • Installing a whole catalog skips an uninstalled deprecated plugin and prints the notice on stderr for an installed one
  • Build, vet, and the plugin tests pass

Stacked on #375. Fixes #370

🤖 Generated with Claude Code

Once someone adds the replacement's catalog, a bare "plugin install
ipam" finds the plugin in two catalogs and stops with an ambiguity
error, and "install --all-available" pulls in deprecated plugins the
user never had.

Bare-name resolution now drops a deprecated match when its
replacement is also among the matches, recognized by catalog source
and plugin name, so the install goes to the replacement. Because
that can move a plugin from the official catalog to a third-party
one without the user naming a catalog, it prints a note on stderr
saying which deprecated entry it is replacing. If dropping would
leave nothing, as with two deprecated entries naming each other,
every match is kept. A renamed replacement is not matched by the old
name; the docs say to install it by its full name.

install --all-available skips deprecated plugins that are not
installed and reports them as "Skipped <name>: deprecated". Installed
ones still upgrade, and like upgrade it prints the deprecation notice
for them whether or not a newer version was installed.

Resolves: #370

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xmc
0xmc force-pushed the feat/370-deprecation-resolution branch from d035054 to 53a16a9 Compare November 17, 2026 19:08
Base automatically changed from feat/369-deprecation-install-upgrade to main November 17, 2026 19:55
@0xmc
0xmc marked this pull request as ready for review November 17, 2026 20:21
@0xmc
0xmc requested a review from a team as a code owner November 17, 2026 20:21
@0xmc
0xmc enabled auto-merge November 17, 2026 20:21
@0xmc

0xmc commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

pr-adversary: VERDICT merge. No findings. It confirmed the superseded-match filter, the skipping of uninstalled deprecated plugins, the new notices, and the stderr note behave as the body describes. It ran: git log/diff ceb677c..53a16a9; gh pr view body; a targeted diff of catalog_resolve.go, install.go and install_all_available.go; go build/vet/test ./internal/cmd/plugin/; grep of writeDeprecationNotice and resolveBareName call sites.

pr-conventions-reviewer: VERDICT merge. Nits: the commit subject is 54 characters, under the 72 hard limit, not applied; the test plan restated the summary, applied by rewriting the body to two behavior checkboxes plus build. The stack-order warning was handled by landing in order. It ran: gh pr view; git diff ceb677c...53a16a9; gh pr list for overlap; grep of the conventions skills; go build/vet/test.

Review history: a first pass at d035054 had both reviewers agreeing on merge. A final whole-branch review then found that --all-available printed no notice for installed deprecated plugins. Both that notice and a one-line stderr note when a bare-name install switches to a replacement were added and squashed into 53a16a9. A scoped re-review approved them after tamper tests confirmed each new test fails without its change. The reviewed content is 53a16a9; the current head 76ee9e9 adds only GitHub's merge from main.

CI on 76ee9e9: ci / Build and test passed, license/cla passed. Auto-merge is enabled with the merge method (the ruleset allows merge commits only). The ruleset requires one approving review from a code owner and approval of the last push, so a person will review before it lands. #378 and #379 are stacked on this PR.

@ecv ecv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve.

A replacement can only displace a deprecated entry that names it. A third-party catalog cannot reach a trusted plugin through this, and the loop case is covered.

  • Only deprecated matches are ever dropped, and only when another match comes from a catalog whose source equals the deprecated entry's own replacement.catalog (SameCatalogSource) and has the replacement name. The naming comes from the deprecated entry's own catalog, and the match set is built from catalogs the user has already registered. A hostile catalog cannot evict a non-deprecated trusted entry. It can only drop its own deprecated entry.
  • A hostile catalog that is registered and deprecates its own entry in favour of itself changes nothing for other catalogs: the name still collides with the trusted one and the user gets the collision error. The thirdCatalogStillCollides and deprecatedWithoutReplacementPresent tests cover this.
  • Loops: when dropping would empty the list (mutually deprecated entries), all matches are kept and nothing is dropped (mutuallyDeprecatedKeepsAll). A chain A to B where B is itself deprecated and not replaced by a present match still picks B.
  • Installed deprecated plugins are unchanged on upgrade and --all-available. Only uninstalled deprecated plugins are skipped, and the install-time stderr note makes the switch visible. ci / Build and test passes on 76ee9e9, and the body's tamper tests cover the new tests.

Follow-ups:

  • The replacement can itself be deprecated, so a bare-name install can land on a deprecated plugin. Chaining or refusing would be tidier.
  • No test registers an attacker catalog that deprecates itself toward a catalog the user did not add, but the match-set construction makes it structurally impossible.

@0xmc
0xmc merged commit 81e6317 into main Nov 17, 2026
2 checks passed
@0xmc
0xmc deleted the feat/370-deprecation-resolution branch November 17, 2026 21:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Installing a moved plugin by name fails as ambiguous

2 participants