fix(plugin): catalog version pinning and command UX cleanup

Route an install argument by stripping any @Version suffix first, then
deciding catalog/name vs owner/repo on the remainder, so catalog/name@ver
installs the pinned version from the catalog instead of being misrouted to
GitHub, and a bare name@version resolves across catalogs at that version.
The version is now threaded through to the install instead of dropped.

A third-party 'index add' in a non-interactive shell without --yes now
fails loudly instead of silently succeeding without adding the catalog, so
a CI script that forgot --yes is not misled; an explicit "no" still aborts
cleanly. The trust prompt's wording matches the actual hard block.

Wrap command help in the shared templates helpers, align the search and
list columns, keep empty-result listings on stdout, render the collision
hint as aligned columns, and drop internal artifacts (plugins.json,
--plugin-manifest, api_version) from user-facing help text.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: scotwells

internal/cmd/plugin/browse.go

@@ -9,6 +9,7 @@ import (
 	"github.com/spf13/cobra"
 	"golang.org/x/term"
 	componentversion "k8s.io/component-base/version"
+	"k8s.io/kubectl/pkg/util/templates"
 
 	customerrors "go.datum.net/datumctl/internal/errors"
 	"go.datum.net/datumctl/internal/pluginstore"
@@ -26,17 +27,19 @@ func browseCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "browse",
 		Short: "Browse and install plugins interactively",
-		Long: `Open an interactive browser over every registered plugin catalog.
-
-Type to filter, inspect a plugin's description, version, source catalog, and
-trust badge ("official" for Datum's curated datum catalog, "third-party" for
-catalogs you added), and install the selected plugin in place. Use --index to
-scope the browser to a single catalog.`,
-		Example: `  # Browse all catalogs
-  datumctl plugin browse
-
-  # Browse a single catalog
-  datumctl plugin browse --index acme`,
+		Long: templates.LongDesc(`
+			Open an interactive browser over every registered plugin catalog.
+
+			Type to filter, inspect a plugin's description, version, source catalog, and
+			trust badge ("official" for Datum's curated datum catalog, "third-party" for
+			catalogs you added), and install the selected plugin in place. Use --index to
+			scope the browser to a single catalog.`),
+		Example: templates.Examples(`
+			# Browse all catalogs
+			datumctl plugin browse
+
+			# Browse a single catalog
+			datumctl plugin browse --index acme`),
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if !browseIsTerminal() {
@@ -92,7 +95,8 @@ scope the browser to a single catalog.`,
 			}
 
 			currentVersion := componentversion.Get().GitVersion
-			return installFromCatalog(cmd, pluginsDir, reg, selected.catalog.Name, selected.plugin.Name, currentVersion)
+			// Empty version installs the catalog's recommended release.
+			return installFromCatalog(cmd, pluginsDir, reg, selected.catalog.Name, selected.plugin.Name, "", currentVersion)
 		},
 	}
 	cmd.Flags().StringVar(&indexName, "index", "", "Scope the browser to a single catalog")

internal/cmd/plugin/catalog_resolve.go

@@ -79,13 +79,28 @@ func resolveBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Reg
 
 // collisionError renders the "available from multiple catalogs" message that
 // asks the user to qualify a bare name. Matches are listed default-first.
+// Columns are padded to a common width so they align when the message is
+// rendered as a plain string (UserError does not run it through a tabwriter).
 func collisionError(name string, matches []catalogMatch) error {
+	cmds := make([]string, len(matches))
+	descs := make([]string, len(matches))
+	cmdWidth, descWidth := 0, 0
+	for i, m := range matches {
+		cmds[i] = fmt.Sprintf("datumctl plugin install %s/%s", m.catalog.Name, name)
+		descs[i] = m.plugin.Spec.ShortDescription
+		if len(cmds[i]) > cmdWidth {
+			cmdWidth = len(cmds[i])
+		}
+		if len(descs[i]) > descWidth {
+			descWidth = len(descs[i])
+		}
+	}
+
 	var b strings.Builder
 	fmt.Fprintf(&b, "%q is available from multiple catalogs. Choose one:", name)
-	for _, m := range matches {
-		desc := m.plugin.Spec.ShortDescription
-		fmt.Fprintf(&b, "\n  datumctl plugin install %s/%s\t%s\t(%s)",
-			m.catalog.Name, name, desc, m.catalog.Trust())
+	for i, m := range matches {
+		fmt.Fprintf(&b, "\n  %-*s  %-*s  (%s)",
+			cmdWidth, cmds[i], descWidth, descs[i], m.catalog.Trust())
 	}
 	return fmt.Errorf("%s", b.String())
 }

internal/cmd/plugin/index.go

@@ -130,10 +130,19 @@ func indexAddCmd() *cobra.Command {
 
 			// One-time trust decision for third-party catalogs.
 			if !assumeYes {
-				ok, promptErr := confirmCatalogTrust(cmd, name)
+				answered, ok, promptErr := confirmCatalogTrust(cmd, name)
 				if promptErr != nil {
 					return promptErr
 				}
+				if !answered {
+					// No one answered the prompt (e.g. non-interactive shell, EOF).
+					// Fail loudly (non-zero) rather than silently succeeding without
+					// adding the catalog, so a CI script that forgot --yes is not misled.
+					return customerrors.NewUserErrorWithHint(
+						fmt.Sprintf("adding third-party catalog %q requires confirmation", name),
+						"Re-run with --yes to confirm without a prompt (for scripts/CI).",
+					)
+				}
 				if !ok {
 					fmt.Fprintln(cmd.OutOrStdout(), "Aborted. No catalog was added.")
 					return nil
@@ -389,23 +398,27 @@ func indexValidateCmd() *cobra.Command {
 }
 
 // confirmCatalogTrust shows the one-time third-party trust explanation and reads
-// a y/N answer from stdin.
-func confirmCatalogTrust(cmd *cobra.Command, name string) (bool, error) {
-	out := cmd.OutOrStdout()
+// a y/N answer from stdin. answered reports whether the user actually responded;
+// it is false when the prompt receives no input (EOF / non-interactive), letting
+// the caller distinguish an unanswered prompt from an explicit "no".
+func confirmCatalogTrust(cmd *cobra.Command, name string) (answered, confirmed bool, err error) {
+	// Interactive prompts go to stderr so stdout stays clean for redirection.
+	out := cmd.ErrOrStderr()
 	fmt.Fprintf(out, "\n  You're adding a third-party plugin catalog: %q\n\n", name)
 	fmt.Fprintln(out, "  Datum does not review, verify, or endorse plugins from this catalog.")
 	fmt.Fprintln(out, "  Plugins are programs that run on your machine with your Datum credentials.")
 	fmt.Fprintln(out, "  Only add catalogs you trust.")
 	fmt.Fprint(out, "\n  Add this catalog? [y/N] ")
 
 	reader := bufio.NewReader(cmd.InOrStdin())
-	line, err := reader.ReadString('\n')
-	if err != nil && line == "" {
-		// EOF with no input (e.g. non-interactive) is treated as "no".
-		return false, nil
+	line, readErr := reader.ReadString('\n')
+	if readErr != nil && line == "" {
+		// EOF with no input (e.g. non-interactive shell): the prompt went
+		// unanswered. Leave the decision to the caller.
+		return false, false, nil
 	}
 	answer := strings.ToLower(strings.TrimSpace(line))
-	return answer == "y" || answer == "yes", nil
+	return true, answer == "y" || answer == "yes", nil
 }
 
 // updateCatalogHeader copies the freshly fetched catalog header into the

internal/cmd/plugin/index_test.go

@@ -110,14 +110,19 @@ func TestIndexAdd_trustPromptDecline(t *testing.T) {
 	}
 }
 
-func TestIndexAdd_emptyStdinDeclines(t *testing.T) {
+func TestIndexAdd_emptyStdinErrors(t *testing.T) {
 	pluginsDir := t.TempDir()
 	src := writeLocalCatalog(t, testCatalogManifest)
 
-	// No stdin -> EOF -> treated as "no".
+	// No stdin -> the prompt goes unanswered. Rather than silently succeeding
+	// (or silently aborting) we fail loudly so a CI script that forgot --yes is
+	// not misled into thinking the catalog was added.
 	_, err := runIndex(t, pluginsDir, "", "add", "acme", src)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
+	if err == nil {
+		t.Fatal("expected an error when the trust prompt gets no confirmation")
+	}
+	if !strings.Contains(err.Error(), "requires confirmation") {
+		t.Fatalf("expected a 'requires confirmation' error, got: %v", err)
 	}
 	if reg, _ := pluginstore.LoadRegistry(pluginsDir); reg.Find("acme") != nil {
 		t.Fatal("acme must NOT be registered when prompt gets no confirmation")

internal/cmd/plugin/install.go

@@ -23,14 +23,16 @@ func installCmd(_ *client.DatumCloudFactory) *cobra.Command {
 		Short: "Install a datumctl plugin",
 		Long: `Install a datumctl plugin from a plugin catalog or a GitHub Release.
 
-With no arguments, restores all plugins recorded in plugins.json to their
-recorded versions. Use this to reproduce a plugin set on a new machine.
+With no arguments, restores all previously installed plugins to their recorded
+versions. Use this to reproduce a plugin set on a new machine.
 
 With a plugin name argument, installs from a registered catalog:
-  - name             resolves against the official datum catalog first, then any
-                     other registered catalog; a name found in more than one
-                     catalog prints the options instead of guessing
-  - catalog/name     installs from a specific registered catalog (e.g. datum/dns)
+  - name                 resolves against the official datum catalog first, then
+                         any other registered catalog; a name found in more than
+                         one catalog prints the options instead of guessing
+  - name@version         installs a specific version of a catalog plugin
+  - catalog/name         installs from a specific registered catalog (e.g. datum/dns)
+  - catalog/name@version installs a specific version from a specific catalog
 
 With an owner/repo argument, installs directly from a GitHub Release:
   - owner/repo         installs the latest release
@@ -50,7 +52,11 @@ The plugin binary is written to the managed plugins directory
   # Install a specific version from GitHub
   datumctl plugin install datum-cloud/datumctl-dns@v1.2.0
 
-  # Restore all plugins from plugins.json
+  # Install a specific version of a catalog plugin
+  datumctl plugin install dns@v1.2.0
+  datumctl plugin install acme/deploy@v2.0.0
+
+  # Restore all previously installed plugins
   datumctl plugin install`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			pluginsDir, err := resolvePluginsDir(cmd)
@@ -87,31 +93,77 @@ The plugin binary is written to the managed plugins directory
 	return cmd
 }
 
-// installArg dispatches a single install argument to the right path based on
-// catalog-aware addressing:
-//   - "owner/repo@version"  -> direct GitHub release (the '@' is unambiguous)
-//   - "catalog/name"        -> catalog-qualified, when the prefix is a
-//     registered catalog name
-//   - "owner/repo"          -> direct GitHub release otherwise
-//   - "name"                -> bare name, resolved across catalogs (default
-//     first); a collision prints the qualified options instead of guessing
-func installArg(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, arg, currentVersion string) error {
-	if strings.Contains(arg, "@") {
-		return installGitHubArg(cmd, pluginsDir, arg, currentVersion)
-	}
-	if strings.Contains(arg, "/") {
-		prefix, rest, _ := strings.Cut(arg, "/")
+// installRouteKind identifies which install path an argument resolves to.
+type installRouteKind int
+
+const (
+	// routeGitHub installs directly from a GitHub release (owner/repo).
+	routeGitHub installRouteKind = iota
+	// routeCatalog installs a named plugin from a specific registered catalog.
+	routeCatalog
+	// routeBare resolves a bare plugin name across all registered catalogs.
+	routeBare
+)
+
+// installRoute is the parsed routing decision for a single install argument.
+// It is produced by routeInstallArg and consumed by installArg; keeping the
+// decision in a pure value makes the routing logic unit-testable without
+// performing real network installs.
+type installRoute struct {
+	kind installRouteKind
+	// ghSource is the "owner/repo" (or "github.com/owner/repo") string to hand
+	// to the GitHub install path; only set for routeGitHub.
+	ghSource string
+	// catalog is the registered catalog name; only set for routeCatalog.
+	catalog string
+	// name is the plugin name (catalog/bare paths); unset for routeGitHub.
+	name string
+	// version is the trailing "@version" requested, or "" for latest. It is
+	// threaded through every route.
+	version string
+}
+
+// routeInstallArg parses a single install argument into a routing decision.
+// Any trailing "@version" is split off FIRST, then routing is decided on the
+// remaining string so that version-pinning works uniformly across catalogs and
+// GitHub:
+//   - "catalog/name"  -> routeCatalog, when the prefix is a registered catalog
+//   - "owner/repo"    -> routeGitHub otherwise (the slash is owner/repo)
+//   - "name"          -> routeBare, resolved across catalogs (default first)
+//
+// The version is carried on the route so "catalog/name@v2", "name@v2", and
+// "owner/repo@v2" all pin the requested version through their respective paths.
+func routeInstallArg(reg *pluginstore.Registry, arg string) installRoute {
+	rest, version, _ := strings.Cut(arg, "@")
+	if strings.Contains(rest, "/") {
+		prefix, name, _ := strings.Cut(rest, "/")
 		if reg.Find(prefix) != nil {
-			return installFromCatalog(cmd, pluginsDir, reg, prefix, rest, currentVersion)
+			return installRoute{kind: routeCatalog, catalog: prefix, name: name, version: version}
 		}
-		return installGitHubArg(cmd, pluginsDir, arg, currentVersion)
+		return installRoute{kind: routeGitHub, ghSource: rest, version: version}
+	}
+	return installRoute{kind: routeBare, name: rest, version: version}
+}
+
+// installArg dispatches a single install argument to the right path based on
+// catalog-aware addressing. See routeInstallArg for the routing rules.
+func installArg(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, arg, currentVersion string) error {
+	route := routeInstallArg(reg, arg)
+	switch route.kind {
+	case routeCatalog:
+		return installFromCatalog(cmd, pluginsDir, reg, route.catalog, route.name, route.version, currentVersion)
+	case routeBare:
+		return installBareName(cmd, pluginsDir, reg, route.name, route.version, currentVersion)
+	default:
+		return installGitHubArg(cmd, pluginsDir, route.ghSource, route.version, currentVersion)
 	}
-	return installBareName(cmd, pluginsDir, reg, arg, currentVersion)
 }
 
-// installGitHubArg installs directly from a GitHub release (owner/repo[@version]).
-func installGitHubArg(cmd *cobra.Command, pluginsDir, arg, currentVersion string) error {
-	owner, repo, version, parseErr := parseSource(arg)
+// installGitHubArg installs directly from a GitHub release. ghSource is the
+// "owner/repo" (or "github.com/owner/repo") string with any "@version" already
+// split off; the requested version is passed separately.
+func installGitHubArg(cmd *cobra.Command, pluginsDir, ghSource, version, currentVersion string) error {
+	owner, repo, _, parseErr := parseSource(ghSource)
 	if parseErr != nil {
 		return customerrors.NewUserError(parseErr.Error())
 	}
@@ -122,8 +174,10 @@ func installGitHubArg(cmd *cobra.Command, pluginsDir, arg, currentVersion string
 	return saveAndReport(cmd, pluginsDir, pluginName, entry, binaryPath)
 }
 
-// installFromCatalog installs a named plugin from a specific registered catalog.
-func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, catalogName, pluginName, currentVersion string) error {
+// installFromCatalog installs a named plugin from a specific registered
+// catalog. version pins a specific release, or "" installs the catalog's
+// recommended version.
+func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, catalogName, pluginName, version, currentVersion string) error {
 	cat := reg.Find(catalogName)
 	if cat == nil {
 		return customerrors.NewUserError(fmt.Sprintf("catalog %q is not registered; run 'datumctl plugin index add %s <source>' first", catalogName, catalogName))
@@ -132,7 +186,7 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore.
 	if err != nil {
 		return indexFetchUserError(err)
 	}
-	idxEntry, name, binaryPath, installErr := installPlugin(cmd.Context(), pluginsDir, pluginName, "", currentVersion, idx)
+	idxEntry, name, binaryPath, installErr := installPlugin(cmd.Context(), pluginsDir, pluginName, version, currentVersion, idx)
 	if installErr != nil {
 		return customerrors.NewUserError(fmt.Sprintf("install plugin %s/%s: %v", catalogName, pluginName, installErr))
 	}
@@ -144,13 +198,14 @@ func installFromCatalog(cmd *cobra.Command, pluginsDir string, reg *pluginstore.
 
 // installBareName resolves a bare plugin name across all catalogs (default
 // first) and installs the unique match, or surfaces the options on a collision.
-func installBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name, currentVersion string) error {
+// version pins a specific release, or "" installs the recommended version.
+func installBareName(cmd *cobra.Command, pluginsDir string, reg *pluginstore.Registry, name, version, currentVersion string) error {
 	matches := resolveBareName(cmd, pluginsDir, reg, name)
 	switch len(matches) {
 	case 0:
 		return customerrors.NewUserError(fmt.Sprintf("plugin %q not found in any registered catalog; run 'datumctl plugin search %s' to look for it", name, name))
 	case 1:
-		return installFromCatalog(cmd, pluginsDir, reg, matches[0].catalog.Name, name, currentVersion)
+		return installFromCatalog(cmd, pluginsDir, reg, matches[0].catalog.Name, name, version, currentVersion)
 	default:
 		return customerrors.NewUserError(collisionError(name, matches).Error())
 	}
@@ -199,7 +254,7 @@ func installAllFromManifest(cmd *cobra.Command, pluginsDir, currentVersion strin
 	}
 
 	if len(manifest.Plugins) == 0 {
-		fmt.Fprintln(cmd.OutOrStdout(), "No plugins recorded in plugins.json.")
+		fmt.Fprintln(cmd.OutOrStdout(), "No previously installed plugins to restore.")
 		return nil
 	}