feat(understackctl): add deploy versions cmd for users

Added a sub-command to deploy for displaying the versions of all the
environments in a deployment repo. This helps users see what version
everything is at in a quick glance.

Author: cardoe

docs/operator-guide/understackctl.md

@@ -144,6 +144,21 @@ Walk all YAML files in the cluster directory and update UnderStack container ima
 
 - `--no-digest` — Write the tag only, skip the registry digest lookup.
 
+#### deploy versions
+
+```bash
+understackctl deploy versions
+```
+
+List every environment in the deployment repo along with the `understack_ref` and `deploy_ref` from its `deploy.yaml`. Environments without a ref set are shown as `unknown`.
+
+```console
+$ understackctl deploy versions
+ENVIRONMENT  UNDERSTACK  DEPLOY
+cluster-a    v0.4.16     HEAD
+cluster-b    unknown     unknown
+```
+
 ### device-type
 
 Manage hardware device type definitions. Requires `UC_DEPLOY` to be set.

go/understackctl/cmd/deploy/deploy.go

@@ -37,6 +37,7 @@ func NewCmdDeploy() *cobra.Command {
 	cmd.AddCommand(newCmdDeployEnable())
 	cmd.AddCommand(newCmdDeployDisable())
 	cmd.AddCommand(newCmdDeployImageSet())
+	cmd.AddCommand(newCmdDeployVersions())
 
 	return cmd
 }

go/understackctl/cmd/deploy/deploy_test.go

@@ -72,9 +72,9 @@ func TestEnabledComponentsConvertsToHyphens(t *testing.T) {
 	components := enabledComponents(config)
 
 	expected := map[string]bool{
-		"cert-manager":      true,
-		"external-secrets":  true,
-		"argo-workflows":    true,
+		"cert-manager":     true,
+		"external-secrets": true,
+		"argo-workflows":   true,
 	}
 
 	if len(components) != len(expected) {
@@ -629,6 +629,83 @@ func TestDeployDisableRequiresTypeFlag(t *testing.T) {
 	}
 }
 
+func TestDeployVersions(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	writeCluster := func(name string, config map[string]any) {
+		clusterDir := filepath.Join(tmpDir, name)
+		if err := os.MkdirAll(clusterDir, 0755); err != nil {
+			t.Fatalf("failed to create cluster dir: %v", err)
+		}
+
+		data, err := yaml.Marshal(&config)
+		if err != nil {
+			t.Fatalf("failed to marshal config: %v", err)
+		}
+
+		deployYaml := filepath.Join(clusterDir, "deploy.yaml")
+		if err := os.WriteFile(deployYaml, data, 0644); err != nil {
+			t.Fatalf("failed to write deploy.yaml: %v", err)
+		}
+	}
+
+	writeCluster("cluster-a", map[string]any{
+		"understack_ref": "v0.4.16",
+		"deploy_ref":     "HEAD",
+	})
+	writeCluster("cluster-b", map[string]any{
+		"site": map[string]any{"enabled": true},
+	})
+
+	// Directories without a deploy.yaml and plain files should be skipped.
+	if err := os.MkdirAll(filepath.Join(tmpDir, "not-a-cluster"), 0755); err != nil {
+		t.Fatalf("failed to create dir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(tmpDir, "README.md"), []byte("test"), 0644); err != nil {
+		t.Fatalf("failed to write file: %v", err)
+	}
+
+	var out strings.Builder
+	if err := runDeployVersions(tmpDir, &out); err != nil {
+		t.Fatalf("runDeployVersions failed: %v", err)
+	}
+
+	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
+	if len(lines) != 3 {
+		t.Fatalf("expected header plus 2 environments, got %d lines: %q", len(lines), out.String())
+	}
+
+	rows := map[string][]string{}
+	for _, line := range lines[1:] {
+		fields := strings.Fields(line)
+		if len(fields) != 3 {
+			t.Fatalf("expected 3 columns, got %q", line)
+		}
+		rows[fields[0]] = fields[1:]
+	}
+
+	if refs, ok := rows["cluster-a"]; !ok || refs[0] != "v0.4.16" || refs[1] != "HEAD" {
+		t.Errorf("unexpected refs for cluster-a: %v", rows["cluster-a"])
+	}
+
+	if refs, ok := rows["cluster-b"]; !ok || refs[0] != "unknown" || refs[1] != "unknown" {
+		t.Errorf("expected unknown refs for cluster-b, got: %v", rows["cluster-b"])
+	}
+
+	if _, ok := rows["not-a-cluster"]; ok {
+		t.Error("directories without deploy.yaml should be skipped")
+	}
+}
+
+func TestDeployVersionsNoEnvironments(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	var out strings.Builder
+	if err := runDeployVersions(tmpDir, &out); err == nil {
+		t.Fatal("expected error when no environments exist")
+	}
+}
+
 func TestDeployRenderDefaultsToDeployYAML(t *testing.T) {
 	tmpDir := t.TempDir()
 	clusterName := filepath.Join(tmpDir, "test-cluster")

go/understackctl/cmd/deploy/versions.go

@@ -0,0 +1,72 @@
+package deploy
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"text/tabwriter"
+
+	"github.com/spf13/cobra"
+)
+
+func newCmdDeployVersions() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "versions",
+		Short: "Show the UnderStack version deployed in each environment",
+		Long:  `List every environment in the deployment repo along with its understack_ref and deploy_ref from deploy.yaml.`,
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDeployVersions(".", cmd.OutOrStdout())
+		},
+	}
+
+	return cmd
+}
+
+func runDeployVersions(repoDir string, out io.Writer) error {
+	entries, err := os.ReadDir(repoDir)
+	if err != nil {
+		return fmt.Errorf("failed to read deployment repo: %w", err)
+	}
+
+	// tabwriter defers write errors to Flush, which is returned below.
+	w := tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)
+	_, _ = fmt.Fprintln(w, "ENVIRONMENT\tUNDERSTACK\tDEPLOY")
+
+	found := false
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+
+		clusterDir := filepath.Join(repoDir, entry.Name())
+		if _, err := os.Stat(filepath.Join(clusterDir, "deploy.yaml")); err != nil {
+			continue
+		}
+
+		config, err := loadDeployConfig(clusterDir)
+		if err != nil {
+			return err
+		}
+
+		understackRef, _ := config["understack_ref"].(string)
+		if understackRef == "" {
+			understackRef = "unknown"
+		}
+
+		deployRef, _ := config["deploy_ref"].(string)
+		if deployRef == "" {
+			deployRef = "unknown"
+		}
+
+		_, _ = fmt.Fprintf(w, "%s\t%s\t%s\n", entry.Name(), understackRef, deployRef)
+		found = true
+	}
+
+	if !found {
+		return fmt.Errorf("no environments with a deploy.yaml found, is this a deployment repo?")
+	}
+
+	return w.Flush()
+}