From ceb677c88d81fe4f0b626cfa78468c38fad62be3 Mon Sep 17 00:00:00 2001 From: Michael Costello Date: Tue, 17 Nov 2026 12:36:28 -0500 Subject: [PATCH] feat: Warn when installing or upgrading a deprecated plugin Installing, restoring, or upgrading a deprecated plugin gave no warning, so people found out only when the plugin disappeared from its catalog. install, restore (install with no arguments), and upgrade now print the deprecation notice to stderr after the operation succeeds. The operation itself still proceeds. upgrade prints it even when the plugin is already current, since that is the command people run routinely. The notice follows the catalog the plugin is recorded as installed from, so a plugin that already moved to its replacement gets no notice. Direct GitHub installs and failed upgrades get none. The plugin system design doc describes what users see and how they move to the replacement. Resolves: #369 Co-Authored-By: Claude Opus 5.5 --- docs/developer/plugins.md | 23 ++ internal/cmd/plugin/deprecation_cmd_test.go | 223 ++++++++++++++++++++ internal/cmd/plugin/install.go | 11 +- internal/cmd/plugin/upgrade.go | 25 +++ 4 files changed, 281 insertions(+), 1 deletion(-) create mode 100644 internal/cmd/plugin/deprecation_cmd_test.go diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md index 2a42b6f..ebff3bc 100644 --- a/docs/developer/plugins.md +++ b/docs/developer/plugins.md @@ -163,6 +163,29 @@ A deprecated entry stays in its catalog and keeps receiving releases until its catalog removes it, so installs and upgrades keep working during the deprecation period. +### What users see + +`plugin install`, `plugin install` with no arguments (restore), and +`plugin upgrade` print a notice to stderr for a deprecated plugin. +`plugin upgrade` prints it whether the plugin was upgraded or was already up +to date. For the entry above, a user whose registry doesn't have the +replacement's catalog sees: + +```text +warning: ipam is deprecated: ipam moved to the Milo catalog. + To switch to the replacement: + datumctl plugin index add milo-os milo-os/cli-plugins + datumctl plugin install milo-os/ipam +``` + +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. + +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. + --- ## plugins.json schema diff --git a/internal/cmd/plugin/deprecation_cmd_test.go b/internal/cmd/plugin/deprecation_cmd_test.go new file mode 100644 index 0000000..f0be2b8 --- /dev/null +++ b/internal/cmd/plugin/deprecation_cmd_test.go @@ -0,0 +1,223 @@ +package plugin + +import ( + "bytes" + "os" + "runtime" + "strings" + "testing" + + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + + "go.datum.net/datumctl/internal/pluginstore" +) + +func deprecatedPlugin(name, version string) pluginstore.Plugin { + p := testPlugin(name, version, name) + p.Spec.Deprecated = &pluginstore.Deprecation{ + Message: "use the new one", + Replacement: &pluginstore.PluginReplacement{ + Catalog: "milo-os/cli-plugins", + Name: name, + }, + } + return p +} + +func TestUpgrade_deprecatedUpToDatePrintsNotice(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")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "ipam") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + for _, want := range []string{"ipam is already up to date", "warning: ipam is deprecated: use the new one"} { + if !strings.Contains(out, want) { + t.Fatalf("want %q in output:\n%s", want, out) + } + } +} + +func TestUpgrade_movedPluginNoNotice(t *testing.T) { + dir := t.TempDir() + if err := pluginstore.SaveRegistry(dir, &pluginstore.Registry{Catalogs: []pluginstore.Catalog{ + {Name: "milo-os", Source: "milo-os/cli-plugins", Type: pluginstore.CatalogTypeCustom}, + }}); err != nil { + t.Fatal(err) + } + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": installedEntry("milo-os", "v0.1.0")}) + seedFreshCache(t, dir, "milo-os", testPlugin("ipam", "v0.1.0", "IPAM")) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "ipam") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + if !strings.Contains(out, "ipam is already up to date") || strings.Contains(out, "deprecated") { + t.Fatalf("want up-to-date report and no notice, got:\n%s", out) + } +} + +func TestUpgrade_nonDeprecatedNoNotice(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"dns": installedEntry("datum", "v1.0.0")}) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, testPlugin("dns", "v1.0.0", "DNS")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "dns") + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + if strings.Contains(out, "deprecated") { + t.Fatalf("want no notice, got:\n%s", out) + } +} + +func TestUpgradeAll_failedUpgradeNoNotice(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{ + "ipam": installedEntry("datum", "v0.1.0"), + "dns": installedEntry("datum", "v1.0.0"), + }) + // ipam is deprecated and has a newer version with no platforms, so its + // upgrade fails. + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, + deprecatedPlugin("ipam", "v0.2.0"), deprecatedPlugin("dns", "v1.0.0")) + + out, err := execPluginCmd(t, dir, upgradeCmd(nil), "--all") + if err == nil { + t.Fatalf("want error for failed ipam upgrade, got none:\n%s", out) + } + if strings.Contains(out, "warning: ipam is deprecated") { + t.Fatalf("failed upgrade must not print a notice:\n%s", out) + } + if !strings.Contains(out, "warning: dns is deprecated") { + t.Fatalf("successful plugin should print its notice:\n%s", out) + } +} + +func TestInstallFromCatalog_deprecatedPrintsNotice(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("test builds a unix binary helper; skip on windows") + } + pluginBin := buildHelperBinary(t, ` +package main + +import ( + "fmt" + "os" +) + +func main() { + for _, a := range os.Args[1:] { + if a == "--plugin-manifest" { + fmt.Println(`+"`"+`{"name":"alpha","version":"v0.2.0","description":"Alpha","api_version":1}`+"`"+`) + return + } + } +} +`) + binData, err := os.ReadFile(pluginBin) + if err != nil { + t.Fatal(err) + } + archiveBytes := makeTarGz(t, "alpha", binData) + url := serveArchive(t, archiveBytes) + + alpha := pluginstore.Plugin{ + ObjectMeta: metav1.ObjectMeta{Name: "alpha"}, + Spec: pluginstore.PluginSpec{ + ShortDescription: "Alpha", + Version: "v0.2.0", + Platforms: []pluginstore.Platform{{URI: url + "/alpha.tar.gz", SHA256: sha256HexOf(archiveBytes)}}, + Deprecated: &pluginstore.Deprecation{Message: "use beta"}, + }, + } + dir := t.TempDir() + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, alpha) + + t.Setenv("DATUMCTL_PLUGINS_DIR", dir) + var stdout, stderr bytes.Buffer + cmd := installCmd(nil) + cmd.SetOut(&stdout) + cmd.SetErr(&stderr) + cmd.SetIn(strings.NewReader("")) + cmd.SetArgs([]string{"datum/alpha"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("unexpected error: %v\n%s%s", err, stdout.String(), stderr.String()) + } + if !strings.Contains(stdout.String(), "Installed alpha") { + t.Fatalf("want install report on stdout:\n%s", stdout.String()) + } + const notice = "warning: alpha is deprecated: use beta" + if !strings.Contains(stderr.String(), notice) || strings.Contains(stdout.String(), "deprecated") { + t.Fatalf("notice must be on stderr only; stdout:\n%s\nstderr:\n%s", stdout.String(), stderr.String()) + } + m, err := pluginstore.Load(dir) + if err != nil || m.Plugins["alpha"] == nil { + t.Fatalf("record not saved: %v", err) + } +} + +func TestInstallRestore_deprecatedPrintsNotice(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("test builds a unix binary helper; skip on windows") + } + build := func(name string) pluginstore.Plugin { + bin := buildHelperBinary(t, ` +package main + +import ( + "fmt" + "os" +) + +func main() { + for _, a := range os.Args[1:] { + if a == "--plugin-manifest" { + fmt.Println(`+"`"+`{"name":"`+name+`","version":"v0.2.0","description":"x","api_version":1}`+"`"+`) + return + } + } +} +`) + data, err := os.ReadFile(bin) + if err != nil { + t.Fatal(err) + } + archive := makeTarGz(t, name, data) + url := serveArchive(t, archive) + return pluginstore.Plugin{ + ObjectMeta: metav1.ObjectMeta{Name: name}, + Spec: pluginstore.PluginSpec{ + ShortDescription: name, + Version: "v0.2.0", + Platforms: []pluginstore.Platform{{URI: url + "/" + name + ".tar.gz", SHA256: sha256HexOf(archive)}}, + }, + } + } + alpha := build("alpha") + alpha.Spec.Deprecated = &pluginstore.Deprecation{Message: "use gamma"} + beta := build("beta") + + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{ + "alpha": installedEntry("datum", "v0.2.0"), + "beta": installedEntry("datum", "v0.2.0"), + }) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, alpha, beta) + + out, err := execPluginCmd(t, dir, installCmd(nil)) + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + for _, want := range []string{"Installed alpha", "Installed beta", "warning: alpha is deprecated: use gamma"} { + if !strings.Contains(out, want) { + t.Fatalf("want %q in output:\n%s", want, out) + } + } + if strings.Contains(out, "beta is deprecated") { + t.Fatalf("beta must get no notice:\n%s", out) + } +} diff --git a/internal/cmd/plugin/install.go b/internal/cmd/plugin/install.go index b39f30d..f612beb 100644 --- a/internal/cmd/plugin/install.go +++ b/internal/cmd/plugin/install.go @@ -238,7 +238,13 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore. // Record the catalog's canonical name (cat.Name), so "default/" // is stored as "datum". idxEntry.Catalog = cat.Name - return saveAndReport(cmd, pluginsDir, name, idxEntry, binaryPath) + if err := saveAndReport(cmd, pluginsDir, name, idxEntry, binaryPath); err != nil { + return err + } + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated) + } + return nil } // installBareName resolves a bare plugin name across all catalogs (default @@ -350,6 +356,9 @@ func installAllFromManifest(cmd *cobra.Command, pluginsDir, currentVersion strin newEntry.Catalog = catalogName manifest.Plugins[name] = newEntry fmt.Fprintf(cmd.OutOrStdout(), "Installed %s %s from %s\n", name, newEntry.Version, catalogName) + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, p.Spec.Deprecated) + } } if saveErr := pluginstore.Save(pluginsDir, manifest); saveErr != nil { diff --git a/internal/cmd/plugin/upgrade.go b/internal/cmd/plugin/upgrade.go index 49ddfc0..1f955ca 100644 --- a/internal/cmd/plugin/upgrade.go +++ b/internal/cmd/plugin/upgrade.go @@ -93,6 +93,7 @@ func upgradeOne(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Man return customerrors.NewUserError(fmt.Sprintf("upgrade plugin %s: %v", name, err)) } reportUpgrade(cmd, name, from, to, upgraded) + u.writeNotice(name, entry) return nil } @@ -127,6 +128,7 @@ func upgradeAll(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Man continue } reportUpgrade(cmd, name, from, to, upgraded) + u.writeNotice(name, entry) } if len(errs) > 0 { @@ -152,6 +154,7 @@ type upgrader struct { cmd *cobra.Command pluginsDir string manifest *pluginstore.Manifest + reg *pluginstore.Registry currentVersion string getIndex func(catalogName string) (*pluginstore.CachedIndex, error) } @@ -166,11 +169,33 @@ func newUpgrader(cmd *cobra.Command, pluginsDir string, manifest *pluginstore.Ma cmd: cmd, pluginsDir: pluginsDir, manifest: manifest, + reg: reg, currentVersion: currentVersion, getIndex: catalogIndexLoader(cmd, pluginsDir, reg), }, nil } +// writeNotice prints the deprecation notice, if any, for a plugin that was +// just processed without error. Direct GitHub installs have no catalog entry +// and get none. The catalog is the one the plugin is recorded as installed +// from, so a plugin that moved to another catalog stops getting a notice. +func (u *upgrader) writeNotice(name string, entry *pluginstore.InstalledPlugin) { + if entry.Catalog == "" && strings.Contains(entry.Source, "/") { + return + } + catalogName := pluginstore.CanonicalCatalogName(entry.Catalog) + if catalogName == "" { + catalogName = pluginstore.OfficialCatalogName + } + idx, err := u.getIndex(catalogName) + if err != nil { + return + } + if p := pluginstore.FindInIndex(idx, name); p != nil { + writeDeprecationNotice(u.cmd.ErrOrStderr(), u.reg, name, p.Spec.Deprecated) + } +} + // upgrade brings one installed plugin to the latest version offered by the // source it was installed from and records the result in plugins.json. It // returns the latest version and whether a new version was installed; when the