Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions docs/developer/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -201,6 +202,17 @@ To move, run `datumctl plugin install <catalog>/<name>`. 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
Expand Down
20 changes: 15 additions & 5 deletions internal/cmd/plugin/browse.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"fmt"
"os"
"strconv"
"strings"

"charm.land/huh/v2"
"github.com/spf13/cobra"
Expand Down Expand Up @@ -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
}
Expand All @@ -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
Expand Down Expand Up @@ -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),
Expand All @@ -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
Expand All @@ -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
}

Expand Down
20 changes: 19 additions & 1 deletion internal/cmd/plugin/browse_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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")
}
}
80 changes: 80 additions & 0 deletions internal/cmd/plugin/install_all_available_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
}
54 changes: 45 additions & 9 deletions internal/cmd/plugin/list.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package plugin
import (
"fmt"
"os"
"sort"
"text/tabwriter"

"github.com/spf13/cobra"
Expand All @@ -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.`),
Expand Down Expand Up @@ -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
Expand All @@ -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
}
}
}
Expand All @@ -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.")
Expand All @@ -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
}
Loading
Loading