From 53a16a986b117aeb33f40a13f1c8ee06c9343f51 Mon Sep 17 00:00:00 2001 From: Michael Costello Date: Tue, 17 Nov 2026 14:08:07 -0500 Subject: [PATCH] feat: Prefer the replacement when resolving a bare name 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 : 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 --- docs/developer/plugins.md | 17 +++- internal/cmd/plugin/catalog_resolve.go | 44 ++++++++- internal/cmd/plugin/deprecation_cmd_test.go | 53 +++++++++++ internal/cmd/plugin/install.go | 6 +- internal/cmd/plugin/install_all_available.go | 17 +++- .../cmd/plugin/install_all_available_test.go | 56 +++++++++++ internal/cmd/plugin/install_catalog_test.go | 95 ++++++++++++++++++- 7 files changed, 279 insertions(+), 9 deletions(-) diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md index ebff3bc..5e797e7 100644 --- a/docs/developer/plugins.md +++ b/docs/developer/plugins.md @@ -89,7 +89,8 @@ datumctl plugin remove compute catalog, or in the catalog named by `--index`. It upgrades plugins that are behind the catalog, leaves up-to-date ones alone, and skips a plugin whose name is already installed from another catalog or from GitHub rather than replace -it. A plugin that fails is reported at the end without stopping the rest. +it. It also skips deprecated plugins that aren't installed. A plugin that +fails is reported at the end without stopping the rest. With a third-party catalog it first lists the plugins it would install and asks to confirm; pass `--yes` to skip the prompt. Without a terminal and without `--yes`, it exits with an error rather than install anything. @@ -182,6 +183,20 @@ If the replacement's catalog is already registered, the notice shows only the `plugin install` line. Installs and upgrades still proceed. Plugins installed directly from GitHub have no catalog entry and get no notice. +When both a deprecated plugin and a replacement with the same name are +available, a bare-name install such as `datumctl plugin install ipam` picks the +replacement instead of reporting that the name exists in multiple catalogs. If +other catalogs also have a plugin with that name, the collision error lists +only those and the replacement. A replacement with a new name isn't picked +this way; install it with `datumctl plugin install /`. +When the install proceeds from the replacement, it first prints +`note: in is deprecated; installing its replacement from ` +to stderr, once per deprecated match it dropped. + +`plugin install --all-available` skips a deprecated plugin that isn't +installed and prints `Skipped : deprecated`. It still upgrades a +deprecated plugin that is already installed and prints the notice. + To move, run `datumctl plugin install /`. The plugin is then recorded as installed from the new catalog, so `plugin upgrade` uses that catalog and the notice stops. diff --git a/internal/cmd/plugin/catalog_resolve.go b/internal/cmd/plugin/catalog_resolve.go index 38856dd..4d14b6d 100644 --- a/internal/cmd/plugin/catalog_resolve.go +++ b/internal/cmd/plugin/catalog_resolve.go @@ -102,8 +102,9 @@ func catalogIndexLoader(cmd *cobra.Command, pluginsDir string, reg *pluginstore. // resolveBareName finds every catalog that contains a plugin with the given // name. The default catalog is checked first. A catalog that cannot be reached -// is skipped with a warning rather than failing the whole resolution. -func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name string) []catalogMatch { +// is skipped with a warning rather than failing the whole resolution. It also +// returns the deprecated matches dropped because their replacement is present. +func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name string) ([]catalogMatch, []supersededMatch) { var matches []catalogMatch active := reg.Active() for i := range active { @@ -117,7 +118,44 @@ func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Reg matches = append(matches, catalogMatch{catalog: cat, plugin: p}) } } - return matches + return dropSupersededMatches(matches) +} + +// supersededMatch is a deprecated match dropped because replacement, another +// match, supersedes it. +type supersededMatch struct { + deprecated catalogMatch + replacement catalogMatch +} + +// dropSupersededMatches removes a match whose plugin is deprecated when +// another match is its replacement: same catalog source and name. Order is +// preserved. When every match would be dropped (deprecated entries naming +// each other), the matches are returned unchanged and nothing is dropped. The +// dropped matches are returned with the match that replaces each. +func dropSupersededMatches(matches []catalogMatch) (kept []catalogMatch, dropped []supersededMatch) { + for i, m := range matches { + if d := m.plugin.Spec.Deprecated; d != nil && d.Replacement != nil { + var replacement *catalogMatch + for j, other := range matches { + if i != j && + pluginstore.SameCatalogSource(d.Replacement.Catalog, other.catalog.Source) && + other.plugin.Name == d.Replacement.PluginName(m.plugin.Name) { + replacement = &matches[j] + break + } + } + if replacement != nil { + dropped = append(dropped, supersededMatch{deprecated: m, replacement: *replacement}) + continue + } + } + kept = append(kept, m) + } + if len(kept) == 0 { + return matches, nil + } + return kept, dropped } // collisionError renders the "available from multiple catalogs" message that diff --git a/internal/cmd/plugin/deprecation_cmd_test.go b/internal/cmd/plugin/deprecation_cmd_test.go index f0be2b8..6bf3f64 100644 --- a/internal/cmd/plugin/deprecation_cmd_test.go +++ b/internal/cmd/plugin/deprecation_cmd_test.go @@ -7,6 +7,7 @@ import ( "strings" "testing" + "github.com/spf13/cobra" metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" "go.datum.net/datumctl/internal/pluginstore" @@ -221,3 +222,55 @@ func main() { t.Fatalf("beta must get no notice:\n%s", out) } } + +// execPluginCmdSplit runs cmd with separate stdout and stderr buffers. +func execPluginCmdSplit(t *testing.T, pluginsDir string, cmd *cobra.Command, args ...string) (stdout, stderr string, err error) { + t.Helper() + t.Setenv("DATUMCTL_PLUGINS_DIR", pluginsDir) + var outBuf, errBuf bytes.Buffer + cmd.SetOut(&outBuf) + cmd.SetErr(&errBuf) + cmd.SetIn(strings.NewReader("")) + cmd.SetArgs(args) + err = cmd.Execute() + return outBuf.String(), errBuf.String(), err +} + +func TestInstallAllAvailable_deprecatedUpToDatePrintsNoticeOnStderr(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": installedEntry("datum", "v0.1.0")}) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0")) + + stdout, stderr, err := execPluginCmdSplit(t, dir, installCmd(nil), "--all-available") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, stderr) + } + if !strings.Contains(stdout, "ipam v0.1.0 is up to date") { + t.Fatalf("want up-to-date line on stdout:\n%s", stdout) + } + if strings.Contains(stdout, "deprecated") { + t.Fatalf("notice must not be on stdout:\n%s", stdout) + } + if !strings.Contains(stderr, "warning: ipam is deprecated: use the new one") { + t.Fatalf("want notice on stderr:\n%s", stderr) + } +} + +func TestInstallBareName_noteWhenReplacementSupersedes(t *testing.T) { + dir := t.TempDir() + if err := pluginstore.SaveRegistry(dir, &pluginstore.Registry{Catalogs: []pluginstore.Catalog{ + {Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}, + }}); err != nil { + t.Fatal(err) + } + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0")) + // The replacement has no platform builds, so the install fails after the + // note is printed, before any download. + seedFreshCache(t, dir, "acme-milo", testPlugin("ipam", "v1.0.0", "IPAM")) + + _, stderr, _ := execPluginCmdSplit(t, dir, installCmd(nil), "ipam") + want := "note: ipam in datum is deprecated; installing its replacement from acme-milo\n" + if strings.Count(stderr, want) != 1 { + t.Fatalf("want exactly one %q in stderr:\n%s", want, stderr) + } +} diff --git a/internal/cmd/plugin/install.go b/internal/cmd/plugin/install.go index f612beb..c4bd4b9 100644 --- a/internal/cmd/plugin/install.go +++ b/internal/cmd/plugin/install.go @@ -251,11 +251,15 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore. // first) and installs the unique match, or surfaces the options on a collision. // version pins a specific release, or "" installs the recommended version. func installBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name, version, currentVersion string) error { - matches := resolveBareName(cmd, pluginsDir, reg, name) + matches, dropped := resolveBareName(cmd, pluginsDir, reg, name) switch len(matches) { case 0: return customerrors.NewUserError(fmt.Sprintf("plugin %q not found in any registered catalog; run 'datumctl plugin search %s' to look for it", name, name)) case 1: + for _, d := range dropped { + fmt.Fprintf(cmd.ErrOrStderr(), "note: %s in %s is deprecated; installing its replacement from %s\n", + name, d.deprecated.catalog.Name, d.replacement.catalog.Name) + } return installFromCatalog(cmd, pluginsDir, reg, matches[0].catalog.Name, name, version, currentVersion) default: return customerrors.NewUserError(collisionError(name, matches).Error()) diff --git a/internal/cmd/plugin/install_all_available.go b/internal/cmd/plugin/install_all_available.go index cbb979e..ad32e76 100644 --- a/internal/cmd/plugin/install_all_available.go +++ b/internal/cmd/plugin/install_all_available.go @@ -19,7 +19,8 @@ type catalogInstallPlan struct { // upToDate lists plugins already installed from this catalog at its version. upToDate []string // skipped lists plugins installed from another catalog or from GitHub, - // which --all-available leaves alone rather than replace. + // which --all-available leaves alone rather than replace, and deprecated + // plugins that are not installed. skipped []skippedPlugin } @@ -37,6 +38,10 @@ func planCatalogInstall(catalogName string, idx *pluginstore.CachedIndex, manife p := &idx.Plugins[i] entry := manifest.Plugins[p.Name] if entry == nil { + if p.Spec.Deprecated != nil { + plan.skipped = append(plan.skipped, skippedPlugin{name: p.Name, reason: "deprecated"}) + continue + } plan.install = append(plan.install, p.Name) continue } @@ -101,6 +106,7 @@ func installAllAvailable(cmd *cobra.Command, pluginsDir, catalogName, currentVer } for _, name := range plan.upToDate { fmt.Fprintf(out, "%s %s is up to date\n", name, manifest.Plugins[name].Version) + warnIfDeprecated(cmd, reg, idx, name) } for _, s := range plan.skipped { fmt.Fprintf(out, "Skipped %s: %s\n", s.name, s.reason) @@ -134,6 +140,7 @@ func installAllAvailable(cmd *cobra.Command, pluginsDir, catalogName, currentVer manifest.Plugins[name] = entry installed++ fmt.Fprintf(out, "Installed %s %s from %s [%s]\n", name, entry.Version, cat.Name, installBadge(cat.Name)) + warnIfDeprecated(cmd, reg, idx, name) } if installed > 0 { @@ -147,6 +154,14 @@ func installAllAvailable(cmd *cobra.Command, pluginsDir, catalogName, currentVer return nil } +// warnIfDeprecated prints the deprecation notice for name to stderr when its +// entry in idx is deprecated. +func warnIfDeprecated(cmd *cobra.Command, reg *pluginstore.Registry, idx *pluginstore.CachedIndex, name string) { + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated) + } +} + // confirmThirdPartyInstallAll lists the plugins a third-party --all-available // would install and reads a y/N answer from stdin. answered is false when no // one responds (EOF, non-interactive), so the caller can tell that apart from diff --git a/internal/cmd/plugin/install_all_available_test.go b/internal/cmd/plugin/install_all_available_test.go index 9902a11..80ef43d 100644 --- a/internal/cmd/plugin/install_all_available_test.go +++ b/internal/cmd/plugin/install_all_available_test.go @@ -290,3 +290,59 @@ func TestInstall_yesNeedsAllAvailable(t *testing.T) { t.Fatalf("error = %v, want the --yes/--all-available error", err) } } + +func deprecatedIpam(version string) pluginstore.Plugin { + p := testPlugin("ipam", version, "IPAM") + p.Spec.Deprecated = &pluginstore.Deprecation{ + Message: "ipam moved.", + Replacement: &pluginstore.PluginReplacement{Catalog: "milo-os/cli-plugins"}, + } + return p +} + +func TestPlanCatalogInstall_skipsDeprecatedNotInstalled(t *testing.T) { + t.Parallel() + idx := &pluginstore.CachedIndex{Plugins: []pluginstore.Plugin{ + deprecatedIpam("v0.1.0"), + testPlugin("dns", "v1.0.0", "DNS"), + }} + got := planCatalogInstall("datum", idx, &pluginstore.Manifest{}) + if want := []string{"dns"}; !reflect.DeepEqual(got.install, want) { + t.Errorf("install = %v, want %v", got.install, want) + } + if want := []skippedPlugin{{name: "ipam", reason: "deprecated"}}; !reflect.DeepEqual(got.skipped, want) { + t.Errorf("skipped = %+v, want %+v", got.skipped, want) + } +} + +func TestPlanCatalogInstall_upgradesDeprecatedInstalled(t *testing.T) { + t.Parallel() + idx := &pluginstore.CachedIndex{Plugins: []pluginstore.Plugin{deprecatedIpam("v0.2.0")}} + manifest := &pluginstore.Manifest{Plugins: map[string]*pluginstore.InstalledPlugin{ + "ipam": {Source: "ipam", Catalog: "datum", Version: "v0.1.0"}, + }} + got := planCatalogInstall("datum", idx, manifest) + if want := []string{"ipam"}; !reflect.DeepEqual(got.install, want) { + t.Errorf("install = %v, want %v", got.install, want) + } +} + +func TestInstallAllAvailable_skipsDeprecatedNotInstalled(t *testing.T) { + pluginsDir := t.TempDir() + seedFreshCache(t, pluginsDir, "datum", deprecatedIpam("v0.1.0")) + + out, err := execPluginCmd(t, pluginsDir, installCmd(nil), "--all-available") + if err != nil { + t.Fatalf("install --all-available failed: %v\n%s", err, out) + } + if !strings.Contains(out, "Skipped ipam: deprecated") { + t.Fatalf("expected skip line, got:\n%s", out) + } + m, err := pluginstore.Load(pluginsDir) + if err != nil { + t.Fatal(err) + } + if _, ok := m.Plugins["ipam"]; ok { + t.Fatalf("ipam must not be installed: %+v", m.Plugins) + } +} diff --git a/internal/cmd/plugin/install_catalog_test.go b/internal/cmd/plugin/install_catalog_test.go index aeec428..5865662 100644 --- a/internal/cmd/plugin/install_catalog_test.go +++ b/internal/cmd/plugin/install_catalog_test.go @@ -102,7 +102,7 @@ func TestResolveBareName_uniqueAndCollision(t *testing.T) { cmd.SetErr(&errOut) // Collision: deploy is in datum and acme; the official datum catalog is first. - matches := resolveBareName(cmd, pluginsDir, reg, "deploy") + matches, _ := resolveBareName(cmd, pluginsDir, reg, "deploy") if len(matches) != 2 { t.Fatalf("expected 2 matches for deploy, got %d", len(matches)) } @@ -119,13 +119,13 @@ func TestResolveBareName_uniqueAndCollision(t *testing.T) { } // Unique: solo is only in beta. - solo := resolveBareName(cmd, pluginsDir, reg, "solo") + solo, _ := resolveBareName(cmd, pluginsDir, reg, "solo") if len(solo) != 1 || solo[0].catalog.Name != "beta" { t.Fatalf("expected unique beta match for solo, got %+v", solo) } // Missing: nothing matches. - if got := resolveBareName(cmd, pluginsDir, reg, "ghost"); len(got) != 0 { + if got, _ := resolveBareName(cmd, pluginsDir, reg, "ghost"); len(got) != 0 { t.Fatalf("expected no matches for ghost, got %+v", got) } } @@ -176,3 +176,92 @@ func TestSearch_unknownIndexErrors(t *testing.T) { t.Fatal("expected error for unknown --index") } } + +func resolveWithCatalogs(t *testing.T, name string, extra []pluginstore.Catalog, seed map[string]pluginstore.Plugin) []catalogMatch { + t.Helper() + pluginsDir := t.TempDir() + if err := pluginstore.SaveRegistry(pluginsDir, &pluginstore.Registry{Catalogs: extra}); err != nil { + t.Fatal(err) + } + for cat, p := range seed { + seedFreshCache(t, pluginsDir, cat, p) + } + reg, err := pluginstore.LoadRegistry(pluginsDir) + if err != nil { + t.Fatal(err) + } + cmd := &cobra.Command{} + cmd.SetContext(context.Background()) + cmd.SetErr(&bytes.Buffer{}) + matches, _ := resolveBareName(cmd, pluginsDir, reg, name) + return matches +} + +func TestResolveBareName_prefersReplacement(t *testing.T) { + got := resolveWithCatalogs(t, "ipam", + []pluginstore.Catalog{{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}}, + map[string]pluginstore.Plugin{ + "datum": deprecatedPlugin("ipam", "v0.1.0"), + "acme-milo": testPlugin("ipam", "v1.0.0", "IPAM"), + }) + if len(got) != 1 || got[0].catalog.Name != "acme-milo" { + t.Fatalf("want one match from acme-milo, got %+v", got) + } +} + +func TestResolveBareName_deprecatedWithoutReplacementPresent(t *testing.T) { + got := resolveWithCatalogs(t, "ipam", + []pluginstore.Catalog{{Name: "other", Source: "https://github.com/other/repo", Type: pluginstore.CatalogTypeCustom}}, + map[string]pluginstore.Plugin{ + "datum": deprecatedPlugin("ipam", "v0.1.0"), + "other": testPlugin("ipam", "v1.0.0", "IPAM"), + }) + if len(got) != 2 { + t.Fatalf("want 2 matches, got %+v", got) + } +} + +func TestResolveBareName_thirdCatalogStillCollides(t *testing.T) { + got := resolveWithCatalogs(t, "ipam", + []pluginstore.Catalog{ + {Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}, + {Name: "other", Source: "https://github.com/other/repo", Type: pluginstore.CatalogTypeCustom}, + }, + map[string]pluginstore.Plugin{ + "datum": deprecatedPlugin("ipam", "v0.1.0"), + "acme-milo": testPlugin("ipam", "v1.0.0", "IPAM"), + "other": testPlugin("ipam", "v2.0.0", "IPAM"), + }) + if len(got) != 2 || got[0].catalog.Name != "acme-milo" || got[1].catalog.Name != "other" { + t.Fatalf("want acme-milo and other, got %+v", got) + } +} + +func TestResolveBareName_mutuallyDeprecatedKeepsAll(t *testing.T) { + a := deprecatedPlugin("ipam", "v0.1.0") // replacement: milo-os/cli-plugins + b := deprecatedPlugin("ipam", "v0.2.0") + b.Spec.Deprecated.Replacement.Catalog = "datum-cloud/datumctl-plugins" + got := resolveWithCatalogs(t, "ipam", + []pluginstore.Catalog{{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}}, + map[string]pluginstore.Plugin{"datum": a, "acme-milo": b}) + if len(got) != 2 { + t.Fatalf("want both matches, got %+v", got) + } +} + +func TestDropSupersededMatches_reportsDropped(t *testing.T) { + dep := catalogMatch{catalog: pluginstore.Catalog{Name: "datum", Source: "datum"}, plugin: func() *pluginstore.Plugin { p := deprecatedPlugin("ipam", "v0.1.0"); return &p }()} + repl := catalogMatch{catalog: pluginstore.Catalog{Name: "acme-milo", Source: "https://github.com/milo-os/cli-plugins"}, plugin: func() *pluginstore.Plugin { p := testPlugin("ipam", "v1.0.0", "IPAM"); return &p }()} + kept, dropped := dropSupersededMatches([]catalogMatch{dep, repl}) + if len(kept) != 1 || kept[0].catalog.Name != "acme-milo" { + t.Fatalf("kept = %+v", kept) + } + if len(dropped) != 1 || dropped[0].deprecated.catalog.Name != "datum" || dropped[0].replacement.catalog.Name != "acme-milo" { + t.Fatalf("dropped = %+v", dropped) + } + // Mutually deprecated: nothing dropped. + kept, dropped = dropSupersededMatches([]catalogMatch{dep}) + if len(kept) != 1 || len(dropped) != 0 { + t.Fatalf("kept=%+v dropped=%+v", kept, dropped) + } +}