From 02d4ee74e62aad87df11dc7b3efdea8896e468eb Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 04:31:29 +0000
Subject: [PATCH] feat(cli): add string array flag helpers

Co-Authored-By: Virgil <virgil@lethean.io>
---
 pkg/cli/command.go      | 22 +++++++++++++++++++++
 pkg/cli/command_test.go | 44 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)

diff --git a/pkg/cli/command.go b/pkg/cli/command.go
index d172ef9..7017fe4 100644
--- a/pkg/cli/command.go
+++ b/pkg/cli/command.go
@@ -173,6 +173,19 @@ func StringSliceFlag(cmd *Command, ptr *[]string, name, short string, def []stri
 	}
 }
 
+// StringArrayFlag adds a string array flag to a command.
+// The value will be stored in the provided pointer.
+//
+//	var tags []string
+//	cli.StringArrayFlag(cmd, &tags, "tag", "t", nil, "Tags to apply")
+func StringArrayFlag(cmd *Command, ptr *[]string, name, short string, def []string, usage string) {
+	if short != "" {
+		cmd.Flags().StringArrayVarP(ptr, name, short, def, usage)
+	} else {
+		cmd.Flags().StringArrayVar(ptr, name, def, usage)
+	}
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Persistent Flag Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -240,6 +253,15 @@ func PersistentStringSliceFlag(cmd *Command, ptr *[]string, name, short string,
 	}
 }
 
+// PersistentStringArrayFlag adds a persistent string array flag (inherited by subcommands).
+func PersistentStringArrayFlag(cmd *Command, ptr *[]string, name, short string, def []string, usage string) {
+	if short != "" {
+		cmd.PersistentFlags().StringArrayVarP(ptr, name, short, def, usage)
+	} else {
+		cmd.PersistentFlags().StringArrayVar(ptr, name, def, usage)
+	}
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Command Configuration
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/pkg/cli/command_test.go b/pkg/cli/command_test.go
index 58a8402..5f12665 100644
--- a/pkg/cli/command_test.go
+++ b/pkg/cli/command_test.go
@@ -58,6 +58,22 @@ func TestPersistentFlagHelpers_Good(t *testing.T) {
 		require.NoError(t, parent.Execute())
 	})
 
+	t.Run("persistent string array flags inherit through subcommands", func(t *testing.T) {
+		parent := NewGroup("parent", "Parent", "")
+
+		var tags []string
+		PersistentStringArrayFlag(parent, &tags, "tag", "t", nil, "Tags")
+
+		child := NewCommand("child", "Child", "", func(_ *Command, _ []string) error {
+			assert.Equal(t, []string{"alpha", "beta"}, tags)
+			return nil
+		})
+		parent.AddCommand(child)
+		parent.SetArgs([]string{"child", "--tag", "alpha", "-t", "beta"})
+
+		require.NoError(t, parent.Execute())
+	})
+
 	t.Run("persistent helpers use short flags when provided", func(t *testing.T) {
 		parent := NewGroup("parent", "Parent", "")
 		var value int
@@ -79,3 +95,31 @@ func TestPersistentFlagHelpers_Good(t *testing.T) {
 		assert.True(t, seen)
 	})
 }
+
+func TestFlagHelpers_Good(t *testing.T) {
+	t.Run("string array flags collect repeated values", func(t *testing.T) {
+		cmd := NewCommand("child", "Child", "", func(_ *Command, _ []string) error {
+			return nil
+		})
+
+		var tags []string
+		StringArrayFlag(cmd, &tags, "tag", "t", nil, "Tags")
+		cmd.SetArgs([]string{"--tag", "alpha", "-t", "beta"})
+
+		require.NoError(t, cmd.Execute())
+		assert.Equal(t, []string{"alpha", "beta"}, tags)
+	})
+
+	t.Run("string array flags use short flags when provided", func(t *testing.T) {
+		cmd := NewCommand("child", "Child", "", func(_ *Command, _ []string) error {
+			return nil
+		})
+
+		var tags []string
+		StringArrayFlag(cmd, &tags, "tag", "t", nil, "Tags")
+		cmd.SetArgs([]string{"-t", "alpha"})
+
+		require.NoError(t, cmd.Execute())
+		assert.Equal(t, []string{"alpha"}, tags)
+	})
+}