From fcf0088e645935e99dd687a2b886e2ba12e9fe77 Mon Sep 17 00:00:00 2001 From: Michael Costello Date: Tue, 17 Nov 2026 14:08:30 -0500 Subject: [PATCH] feat: Show deprecated plugins in list, search, and browse The plugin list, search, and browser showed a deprecated plugin like any other, so people could not see which of their plugins need to move. plugin list marks a deprecated plugin with a "deprecated" STATUS, which takes precedence over "update" but not over an API mismatch or missing version info, and prints each deprecated plugin's notice to stderr after the table whatever its STATUS. A deprecated plugin with a newer version still counts as an available update, so the upgrade hint keeps printing. list reads only the cached catalog indexes, so it stays offline; a catalog not fetched yet shows nothing. plugin search prefixes the description with "[deprecated]" and, in table mode, prints each notice to stderr after the table. -o json adds the catalog's deprecation as an optional "deprecated" field and prints no notices; -o name is unchanged, so script output stays parseable. plugin browse tags the entry and shows the notice in the details pane. Resolves: #371 Co-Authored-By: Claude Opus 5.5 --- docs/developer/plugins.md | 16 ++- internal/cmd/plugin/browse.go | 20 ++- internal/cmd/plugin/browse_test.go | 20 ++- .../cmd/plugin/install_all_available_test.go | 80 ++++++++++++ internal/cmd/plugin/list.go | 54 ++++++-- internal/cmd/plugin/list_test.go | 122 +++++++++++++++++- internal/cmd/plugin/search.go | 39 +++++- 7 files changed, 331 insertions(+), 20 deletions(-) diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md index 5e797e7..a7cb15c 100644 --- a/docs/developer/plugins.md +++ b/docs/developer/plugins.md @@ -96,8 +96,9 @@ to confirm; pass `--yes` to skip the prompt. Without a terminal and without `--yes`, it exits with an error rather than install anything. `plugin search -o json` prints an array of `{name, index, version, trust, -description}` objects, and `-o name` prints one plugin name per line, for -scripts and agents. +description}` objects, plus a `deprecated` object when the catalog marks the +plugin deprecated, and `-o name` prints one plugin name per line, for scripts +and agents. `plugin upgrade` reinstalls a plugin from the catalog or GitHub repository it was installed from, skipping any plugin already at its latest version. With @@ -201,6 +202,17 @@ 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. +Listings show deprecation too. `plugin list` reads only cached catalog indexes, +shows `deprecated` in the STATUS column (it replaces `update` but not `!` or +`?`; the upgrade hint still prints when a newer version exists), and prints the +notice for each deprecated plugin to stderr after the table, whatever its +STATUS. `plugin search` prefixes the description with `[deprecated]` and, in +table output, prints the notice for each deprecated result to stderr after the +table. With `-o json`, the result carries the catalog's `deprecated` object; +`-o json` and `-o name` print no notice. `plugin browse` +adds `(deprecated)` after the plugin name and appends the notice to the details +pane. + --- ## plugins.json schema diff --git a/internal/cmd/plugin/browse.go b/internal/cmd/plugin/browse.go index 97df830..b3e79bb 100644 --- a/internal/cmd/plugin/browse.go +++ b/internal/cmd/plugin/browse.go @@ -4,6 +4,7 @@ import ( "fmt" "os" "strconv" + "strings" "charm.land/huh/v2" "github.com/spf13/cobra" @@ -89,7 +90,7 @@ func browseCmd() *cobra.Command { return nil } - selected, ok, err := runBrowser(entries) + selected, ok, err := runBrowser(entries, reg) if err != nil { return err } @@ -110,7 +111,7 @@ func browseCmd() *cobra.Command { // runBrowser presents the filterable plugin picker followed by an install // confirmation. It returns the chosen entry and whether the user confirmed the // install. -func runBrowser(entries []browseEntry) (browseEntry, bool, error) { +func runBrowser(entries []browseEntry, reg *pluginstore.Registry) (browseEntry, bool, error) { options := browseOptions(entries) var picked string @@ -139,7 +140,7 @@ func runBrowser(entries []browseEntry) (browseEntry, bool, error) { huh.NewGroup( huh.NewConfirm(). Title(fmt.Sprintf("Install %s from %s?", entry.plugin.Name, entry.catalog.Name)). - Description(browseDetails(entry)). + Description(browseDetails(entry, reg)). Affirmative("Install"). Negative("Cancel"). Value(&confirm), @@ -157,15 +158,19 @@ func runBrowser(entries []browseEntry) (browseEntry, bool, error) { func browseOptions(entries []browseEntry) []huh.Option[string] { options := make([]huh.Option[string], len(entries)) for i, e := range entries { + name := e.plugin.Name + if e.plugin.Spec.Deprecated != nil { + name += " (deprecated)" + } label := fmt.Sprintf("%s [%s] %s — %s", - e.plugin.Name, e.catalog.Trust(), e.catalog.Name, e.plugin.Spec.ShortDescription) + name, e.catalog.Trust(), e.catalog.Name, e.plugin.Spec.ShortDescription) options[i] = huh.NewOption(label, strconv.Itoa(i)) } return options } // browseDetails renders the inspect panel shown on the confirmation step. -func browseDetails(e browseEntry) string { +func browseDetails(e browseEntry, reg *pluginstore.Registry) string { desc := e.plugin.Spec.ShortDescription if e.plugin.Spec.Description != "" { desc = e.plugin.Spec.Description @@ -180,6 +185,11 @@ func browseDetails(e browseEntry) string { if desc != "" { out += "\n\n" + desc } + if e.plugin.Spec.Deprecated != nil { + var b strings.Builder + writeDeprecationNotice(&b, reg, e.plugin.Name, e.plugin.Spec.Deprecated) + out += "\n\n" + strings.TrimRight(b.String(), "\n") + } return out } diff --git a/internal/cmd/plugin/browse_test.go b/internal/cmd/plugin/browse_test.go index de53ff6..c3a5f70 100644 --- a/internal/cmd/plugin/browse_test.go +++ b/internal/cmd/plugin/browse_test.go @@ -47,7 +47,7 @@ func TestBrowseDetails_prefersLongDescriptionAndShowsHomepage(t *testing.T) { e := browseEntryFor( pluginstore.Catalog{Name: "acme", Type: pluginstore.CatalogTypeCustom}, "deploy", "v2.1.0", "short", "the long description", "https://plugins.acme.example/deploy") - got := browseDetails(e) + got := browseDetails(e, nil) for _, want := range []string{"acme", "v2.1.0", "third-party", "https://plugins.acme.example/deploy", "the long description"} { if !strings.Contains(got, want) { t.Fatalf("details missing %q:\n%s", want, got) @@ -71,3 +71,21 @@ func TestBrowse_requiresTerminal(t *testing.T) { t.Fatalf("unexpected error: %v", err) } } + +func TestBrowseOptionsAndDetails_deprecated(t *testing.T) { + p := deprecatedPlugin("ipam", "v0.1.0") + e := browseEntry{catalog: pluginstore.OfficialCatalog(), plugin: p} + opts := browseOptions([]browseEntry{e}) + if !strings.Contains(opts[0].Key, "ipam (deprecated)") { + t.Fatalf("label missing tag: %q", opts[0].Key) + } + got := browseDetails(e, &pluginstore.Registry{}) + if !strings.Contains(got, "is deprecated") || !strings.Contains(got, "datumctl plugin install milo-os/ipam") { + t.Fatalf("details missing notice:\n%s", got) + } + plain := browseEntry{catalog: pluginstore.OfficialCatalog(), plugin: testPlugin("dns", "v1", "DNS")} + if strings.Contains(browseOptions([]browseEntry{plain})[0].Key, "deprecated") || + strings.Contains(browseDetails(plain, nil), "deprecated") { + t.Fatal("non-deprecated entry must not be tagged") + } +} diff --git a/internal/cmd/plugin/install_all_available_test.go b/internal/cmd/plugin/install_all_available_test.go index 80ef43d..7ef2beb 100644 --- a/internal/cmd/plugin/install_all_available_test.go +++ b/internal/cmd/plugin/install_all_available_test.go @@ -346,3 +346,83 @@ func TestInstallAllAvailable_skipsDeprecatedNotInstalled(t *testing.T) { t.Fatalf("ipam must not be installed: %+v", m.Plugins) } } + +func TestSearch_deprecatedTagAndJSON(t *testing.T) { + pluginsDir := t.TempDir() + seedFreshCache(t, pluginsDir, "datum", + deprecatedPlugin("ipam", "v0.1.0"), + testPlugin("dns", "v1.2.3", "Manage DNS"), + ) + + table, err := execPluginCmd(t, pluginsDir, searchCmd(), "--index", "datum") + if err != nil { + t.Fatal(err) + } + if !strings.Contains(table, "[deprecated] ipam") || strings.Count(table, "[deprecated]") != 1 { + t.Fatalf("want one [deprecated] tag on ipam:\n%s", table) + } + + jsonOut, err := execPluginCmd(t, pluginsDir, searchCmd(), "--index", "datum", "-o", "json") + if err != nil { + t.Fatal(err) + } + if strings.Contains(jsonOut, "warning:") { + t.Fatalf("json output has warning text:\n%s", jsonOut) + } + var results []searchResult + if err := json.Unmarshal([]byte(jsonOut), &results); err != nil { + t.Fatalf("not valid JSON: %v\n%s", err, jsonOut) + } + if len(results) != 2 || results[0].Deprecated == nil || + results[0].Deprecated.Replacement == nil || + results[0].Deprecated.Replacement.Catalog != "milo-os/cli-plugins" { + t.Fatalf("unexpected results: %+v", results) + } + if results[1].Deprecated != nil || strings.Count(jsonOut, `"deprecated"`) != 1 { + t.Fatalf("non-deprecated result must omit the field:\n%s", jsonOut) + } + + nameOut, err := execPluginCmd(t, pluginsDir, searchCmd(), "--index", "datum", "-o", "name") + if err != nil { + t.Fatal(err) + } + if nameOut != "ipam\ndns\n" { + t.Fatalf("search -o name = %q", nameOut) + } +} + +func TestSearch_tableNoticeOnStderrOnly(t *testing.T) { + pluginsDir := t.TempDir() + seedFreshCache(t, pluginsDir, "datum", + deprecatedPlugin("ipam", "v0.1.0"), + testPlugin("dns", "v1.2.3", "Manage DNS"), + ) + + stdout, stderr, err := execCmdSplitStreams(t, pluginsDir, searchCmd(), "--index", "datum") + if err != nil { + t.Fatal(err) + } + if strings.Contains(stdout, "warning:") { + t.Fatalf("notice must not be on stdout:\n%s", stdout) + } + if !strings.Contains(stderr, "warning: ipam is deprecated: use the new one") || + !strings.Contains(stderr, "datumctl plugin install milo-os/ipam") || + strings.Contains(stderr, "dns") { + t.Fatalf("want one notice for ipam on stderr:\n%s", stderr) + } +} + +func TestSearch_jsonAndNameNoNotices(t *testing.T) { + pluginsDir := t.TempDir() + seedFreshCache(t, pluginsDir, "datum", deprecatedPlugin("ipam", "v0.1.0")) + + for _, o := range []string{"json", "name"} { + stdout, stderr, err := execCmdSplitStreams(t, pluginsDir, searchCmd(), "--index", "datum", "-o", o) + if err != nil { + t.Fatal(err) + } + if strings.Contains(stdout, "warning:") || strings.Contains(stderr, "warning:") { + t.Fatalf("-o %s must print no notices:\nstdout:\n%s\nstderr:\n%s", o, stdout, stderr) + } + } +} diff --git a/internal/cmd/plugin/list.go b/internal/cmd/plugin/list.go index 905a2bd..b223d7c 100644 --- a/internal/cmd/plugin/list.go +++ b/internal/cmd/plugin/list.go @@ -3,6 +3,7 @@ package plugin import ( "fmt" "os" + "sort" "text/tabwriter" "github.com/spf13/cobra" @@ -21,10 +22,11 @@ func listCmd() *cobra.Command { List the plugins you have installed, without running any of them. Status column indicators: - ok Plugin is installed and compatible with this datumctl. - update A newer version is available in its catalog. - ! Built for a different datumctl version. - ? Version info unavailable. + ok Plugin is installed and compatible with this datumctl. + update A newer version is available in its catalog. + deprecated Its catalog marks the plugin deprecated. + ! Built for a different datumctl version. + ? Version info unavailable. Run 'datumctl plugin search' to refresh available plugins from your catalogs.`), @@ -59,6 +61,11 @@ func listCmd() *cobra.Command { return idx } + // Cached indexes only; the registry is a local file. A plugin whose + // catalog index isn't cached is simply not marked deprecated. + reg, _ := pluginstore.LoadRegistry(pluginsDir) + deprecations := map[string]*pluginstore.Deprecation{} + w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 3, ' ', 0) fmt.Fprintln(w, "NAME\tINDEX\tVERSION\tTRUST\tDESCRIPTION\tSTATUS") var anyUpdates bool @@ -74,13 +81,19 @@ func listCmd() *cobra.Command { } } indexLabel, trust := installedCatalogLabel(entry) - // Update detection only applies to catalog-sourced plugins (the + // Catalog lookup only applies to catalog-sourced plugins (the // "(direct)" label marks a direct GitHub install with no catalog). - if status == "ok" && indexLabel != "(direct)" { + // The deprecation notice is recorded whatever the status; the + // STATUS column keeps "!" and "?" ahead of "deprecated". + if indexLabel != "(direct)" { if indexEntry := pluginstore.FindInIndex(catalogIndex(indexLabel), name); indexEntry != nil { - if isUpdateAvailable(entry.Version, indexEntry.Spec.Version) { - status = "update" - anyUpdates = true + if indexEntry.Spec.Deprecated != nil { + deprecations[name] = indexEntry.Spec.Deprecated + } + if status == "ok" { + var update bool + status, update = listStatus(entry.Version, indexEntry) + anyUpdates = anyUpdates || update } } } @@ -89,6 +102,14 @@ func listCmd() *cobra.Command { if err := w.Flush(); err != nil { return err } + names := make([]string, 0, len(deprecations)) + for name := range deprecations { + names = append(names, name) + } + sort.Strings(names) + for _, name := range names { + writeDeprecationNotice(cmd.ErrOrStderr(), reg, name, deprecations[name]) + } if anyUpdates && term.IsTerminal(int(os.Stdout.Fd())) { fmt.Fprintln(cmd.ErrOrStderr(), "\nRun 'datumctl plugin upgrade' to update plugins with available upgrades.") @@ -98,3 +119,18 @@ func listCmd() *cobra.Command { } return cmd } + +// listStatus returns the STATUS column value for a compatible, catalog-sourced +// plugin, and whether a newer catalog version exists. Deprecated takes +// precedence in the column, but the update flag is still reported because +// 'plugin upgrade' upgrades installed deprecated plugins. +func listStatus(installedVersion string, indexEntry *pluginstore.Plugin) (status string, updateAvailable bool) { + updateAvailable = isUpdateAvailable(installedVersion, indexEntry.Spec.Version) + switch { + case indexEntry.Spec.Deprecated != nil: + return "deprecated", updateAvailable + case updateAvailable: + return "update", true + } + return "ok", false +} diff --git a/internal/cmd/plugin/list_test.go b/internal/cmd/plugin/list_test.go index f94dd0c..713244e 100644 --- a/internal/cmd/plugin/list_test.go +++ b/internal/cmd/plugin/list_test.go @@ -6,10 +6,25 @@ import ( "testing" "time" + "github.com/spf13/cobra" + "go.datum.net/datumctl/internal/plugindispatch" "go.datum.net/datumctl/internal/pluginstore" ) +// execCmdSplitStreams runs cmd with separate stdout and stderr buffers. +func execCmdSplitStreams(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 +} + // executeListCmd runs the list subcommand with the given plugins.json content // and returns the captured stdout. func executeListCmd(t *testing.T, manifest *pluginstore.Manifest) string { @@ -20,7 +35,7 @@ func executeListCmd(t *testing.T, manifest *pluginstore.Manifest) string { t.Fatalf("Save manifest for test: %v", err) } - cmd := Command(nil) // factory is not used by listCmd + cmd := Command(nil) // factory is not used by listCmd cmd.PersistentFlags().Set("plugins-dir", dir) //nolint:errcheck var out bytes.Buffer @@ -108,3 +123,108 @@ func TestListCmd_showsAPIVersionMismatch(t *testing.T) { t.Errorf("list output %q does not contain '!' for API version mismatch", output) } } + +func listEntryWithManifest(catalog, version string) *pluginstore.InstalledPlugin { + e := installedEntry(catalog, version) + e.Manifest = &pluginstore.PluginManifest{ + Name: "datumctl-ipam", + Version: version, + Description: "IPAM", + APIVersion: plugindispatch.PluginAPIVersion, + } + return e +} + +func TestListCmd_deprecatedStatusAndNotice(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": listEntryWithManifest("datum", "v0.1.0")}) + // A newer version is available too; deprecated must win over update. + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.2.0")) + + out, stderr, err := execCmdSplitStreams(t, dir, listCmd()) + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, stderr) + } + var row string + for _, l := range strings.Split(out, "\n") { + if strings.HasPrefix(l, "ipam") { + row = l + } + } + if !strings.HasSuffix(strings.TrimSpace(row), "deprecated") { + t.Fatalf("want STATUS deprecated in row %q\n%s", row, out) + } + if !strings.Contains(stderr, "datumctl plugin install milo-os/ipam") { + t.Fatalf("want notice with replacement command on stderr:\n%s", stderr) + } + if strings.Contains(out, "warning:") || strings.Contains(out, "datumctl plugin install") { + t.Fatalf("notice must not be on stdout:\n%s", out) + } +} + +func TestListCmd_deprecatedWithAPIMismatchKeepsBangAndNotice(t *testing.T) { + dir := t.TempDir() + e := listEntryWithManifest("datum", "v0.1.0") + e.Manifest.APIVersion = plugindispatch.PluginAPIVersion + 999 + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": e}) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, deprecatedPlugin("ipam", "v0.1.0")) + + out, stderr, err := execCmdSplitStreams(t, dir, listCmd()) + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, stderr) + } + var row string + for _, l := range strings.Split(out, "\n") { + if strings.HasPrefix(l, "ipam") { + row = l + } + } + if !strings.HasSuffix(strings.TrimSpace(row), "!") { + t.Fatalf("want STATUS ! in row %q\n%s", row, out) + } + if !strings.Contains(stderr, "warning: ipam is deprecated: use the new one") { + t.Fatalf("want notice on stderr:\n%s", stderr) + } +} + +func TestListCmd_notDeprecatedNoNotice(t *testing.T) { + dir := t.TempDir() + seedManifest(t, dir, map[string]*pluginstore.InstalledPlugin{"ipam": listEntryWithManifest("datum", "v0.1.0")}) + seedFreshCache(t, dir, pluginstore.OfficialCatalogName, testPlugin("ipam", "v0.1.0", "IPAM")) + + out, err := execPluginCmd(t, dir, listCmd()) + if err != nil { + t.Fatalf("unexpected error: %v\n%s", err, out) + } + if strings.Contains(out, "deprecated") || strings.Contains(out, "is deprecated") { + t.Fatalf("want no deprecation output:\n%s", out) + } +} + +// TestListStatus_deprecatedWithUpdate verifies a deprecated plugin with a newer +// catalog version shows "deprecated" yet still reports an available update, so +// the upgrade hint prints. +func TestListStatus_deprecatedWithUpdate(t *testing.T) { + t.Parallel() + + newer := &pluginstore.Plugin{Spec: pluginstore.PluginSpec{ + Version: "v1.2.0", + Deprecated: &pluginstore.Deprecation{}, + }} + if st, up := listStatus("v1.0.0", newer); st != "deprecated" || !up { + t.Errorf("listStatus = (%q, %v), want (deprecated, true)", st, up) + } + + same := &pluginstore.Plugin{Spec: pluginstore.PluginSpec{ + Version: "v1.0.0", + Deprecated: &pluginstore.Deprecation{}, + }} + if st, up := listStatus("v1.0.0", same); st != "deprecated" || up { + t.Errorf("listStatus = (%q, %v), want (deprecated, false)", st, up) + } + + plain := &pluginstore.Plugin{Spec: pluginstore.PluginSpec{Version: "v1.2.0"}} + if st, up := listStatus("v1.0.0", plain); st != "update" || !up { + t.Errorf("listStatus = (%q, %v), want (update, true)", st, up) + } +} diff --git a/internal/cmd/plugin/search.go b/internal/cmd/plugin/search.go index 3276636..1900072 100644 --- a/internal/cmd/plugin/search.go +++ b/internal/cmd/plugin/search.go @@ -4,6 +4,7 @@ import ( "encoding/json" "fmt" "io" + "sort" "strings" "text/tabwriter" @@ -22,6 +23,9 @@ type searchResult struct { Version string `json:"version"` Trust string `json:"trust"` Description string `json:"description"` + // Deprecated is the catalog's deprecation block; omitted when the plugin + // isn't deprecated. + Deprecated *pluginstore.Deprecation `json:"deprecated,omitempty"` } const ( @@ -118,10 +122,17 @@ func searchCmd() *cobra.Command { Version: p.Spec.Version, Trust: cat.Trust(), Description: p.Spec.ShortDescription, + Deprecated: p.Spec.Deprecated, }) } } - return printSearchResults(cmd.OutOrStdout(), output, results) + if err := printSearchResults(cmd.OutOrStdout(), output, results); err != nil { + return err + } + if output == searchOutputTable { + writeSearchNotices(cmd.ErrOrStderr(), reg, results) + } + return nil }, } cmd.Flags().StringVar(&indexName, "index", "", "Scope the search to a single catalog") @@ -129,6 +140,26 @@ func searchCmd() *cobra.Command { return cmd } +// writeSearchNotices writes one deprecation notice per deprecated result, +// sorted by plugin name then catalog. +func writeSearchNotices(w io.Writer, reg *pluginstore.Registry, results []searchResult) { + var deprecated []searchResult + for _, r := range results { + if r.Deprecated != nil { + deprecated = append(deprecated, r) + } + } + sort.Slice(deprecated, func(i, j int) bool { + if deprecated[i].Name != deprecated[j].Name { + return deprecated[i].Name < deprecated[j].Name + } + return deprecated[i].Index < deprecated[j].Index + }) + for _, r := range deprecated { + writeDeprecationNotice(w, reg, r.Name, r.Deprecated) + } +} + // printSearchResults writes search results in the requested format. JSON // output is always an array, empty when nothing matched. func printSearchResults(w io.Writer, output string, results []searchResult) error { @@ -151,7 +182,11 @@ func printSearchResults(w io.Writer, output string, results []searchResult) erro tw := tabwriter.NewWriter(w, 0, 0, 3, ' ', 0) fmt.Fprintln(tw, "NAME\tINDEX\tVERSION\tTRUST\tDESCRIPTION") for _, r := range results { - fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", r.Name, r.Index, r.Version, r.Trust, r.Description) + desc := r.Description + if r.Deprecated != nil { + desc = "[deprecated] " + desc + } + fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n", r.Name, r.Index, r.Version, r.Trust, desc) } return tw.Flush() }