feat!(flags): rename CLI flag names and add flag builder

cmd/completion/suggestions.go

@@ -5,14 +5,15 @@ import (
 
 	"github.com/devsy-org/devsy/cmd/flags"
 	"github.com/devsy-org/devsy/pkg/config"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/devsy-org/devsy/pkg/platform"
 	"github.com/devsy-org/devsy/pkg/workspace"
 	"github.com/spf13/cobra"
 )
 
 func RegisterFlagCompletionFuns(rootCmd *cobra.Command, globalFlags *flags.GlobalFlags) error {
 	if err := rootCmd.RegisterFlagCompletionFunc(
-		"provider",
+		names.Provider,
 		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			return GetProviderSuggestions(
 				rootCmd,
@@ -28,7 +29,7 @@ func RegisterFlagCompletionFuns(rootCmd *cobra.Command, globalFlags *flags.Globa
 	}
 
 	if err := rootCmd.RegisterFlagCompletionFunc(
-		"context",
+		names.Context,
 		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			return GetContextSuggestions(
 				rootCmd,

cmd/config/apply.go

@@ -15,6 +15,7 @@ import (
 	devcconfig "github.com/devsy-org/devsy/pkg/devcontainer/config"
 	"github.com/devsy-org/devsy/pkg/devcontainer/feature"
 	"github.com/devsy-org/devsy/pkg/docker"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
 	"github.com/devsy-org/devsy/pkg/log"
 	"github.com/devsy-org/devsy/pkg/output"
 	"github.com/devsy-org/devsy/pkg/types"
@@ -54,15 +55,17 @@ func NewApplyCmd(f *flags.GlobalFlags) *cobra.Command {
 		},
 	}
 
-	applyCmd.Flags().StringVar(&cmd.Container, flagApplyContainer, "",
-		"The container ID or name to apply configuration to (required)")
+	cliflags.Add(applyCmd,
+		cliflags.String(&cmd.Container, flagApplyContainer, "",
+			"The container ID or name to apply configuration to (required)"),
+		cliflags.String(&cmd.Config, flagApplyConfig, "",
+			"Path to devcontainer.json (defaults to auto-detection in current workspace)"),
+		cliflags.String(&cmd.WorkspaceFolder, flagApplyWorkspaceFolder, "",
+			"Workspace folder path inside the container"),
+		cliflags.String(&cmd.DockerPath, flagApplyDockerPath, "",
+			"Path to the docker/podman executable (defaults to 'docker')"),
+	)
 	_ = applyCmd.MarkFlagRequired(flagApplyContainer)
-	applyCmd.Flags().StringVar(&cmd.Config, flagApplyConfig, "",
-		"Path to devcontainer.json (defaults to auto-detection in current workspace)")
-	applyCmd.Flags().StringVar(&cmd.WorkspaceFolder, flagApplyWorkspaceFolder, "",
-		"Workspace folder path inside the container")
-	applyCmd.Flags().StringVar(&cmd.DockerPath, flagApplyDockerPath, "",
-		"Path to the docker/podman executable (defaults to 'docker')")
 
 	return applyCmd
 }

cmd/config/read.go

@@ -11,6 +11,8 @@ import (
 	devcconfig "github.com/devsy-org/devsy/pkg/devcontainer/config"
 	"github.com/devsy-org/devsy/pkg/devcontainer/metadata"
 	"github.com/devsy-org/devsy/pkg/docker"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	pkgworkspace "github.com/devsy-org/devsy/pkg/workspace"
 	"github.com/spf13/cobra"
 )
@@ -37,55 +39,25 @@ func NewReadCmd(f *flags.GlobalFlags) *cobra.Command {
 		RunE:  cmd.Run,
 	}
 
-	readConfigCmd.Flags().
-		StringVar(
-			&cmd.WorkspaceFolder,
-			"workspace-folder",
-			"",
-			"Path to the workspace folder",
-		)
-	readConfigCmd.Flags().
-		StringVar(
-			&cmd.ContainerID,
-			"container-id",
-			"",
-			"Read configuration from a running container with the given ID",
-		)
-	readConfigCmd.Flags().
-		StringVar(
-			&cmd.DockerPath,
-			"docker-path",
-			"",
-			"Path to the docker/podman executable (defaults to 'docker')",
-		)
-	readConfigCmd.Flags().
-		StringVar(
-			&cmd.Config,
-			"config",
-			"",
-			"Path to a specific devcontainer.json",
-		)
-	readConfigCmd.Flags().
-		StringArrayVar(
+	cliflags.Add(readConfigCmd,
+		cliflags.String(&cmd.WorkspaceFolder, names.WorkspaceFolder, "",
+			"Path to the workspace folder"),
+		cliflags.String(&cmd.ContainerID, names.ContainerID, "",
+			"Read configuration from a running container with the given ID"),
+		cliflags.String(&cmd.DockerPath, names.DockerPath, "",
+			"Path to the docker/podman executable (defaults to 'docker')"),
+		cliflags.String(&cmd.Config, names.Config, "", "Path to a specific devcontainer.json"),
+		cliflags.StringArray(
 			&cmd.IDLabels,
-			"id-label",
+			names.IDLabel,
 			nil,
 			"Override the default container identification labels (format: key=value, can be specified multiple times)",
-		)
-	readConfigCmd.Flags().
-		BoolVar(
-			&cmd.IncludeFeaturesConfiguration,
-			"include-features-configuration",
-			false,
-			"Include features in the output",
-		)
-	readConfigCmd.Flags().
-		BoolVar(
-			&cmd.IncludeMergedConfiguration,
-			"include-merged-configuration",
-			false,
-			"Include the merged configuration in the output",
-		)
+		),
+		cliflags.Bool(&cmd.IncludeFeaturesConfiguration, names.IncludeFeaturesConfiguration, false,
+			"Include features in the output"),
+		cliflags.Bool(&cmd.IncludeMergedConfiguration, names.IncludeMergedConfiguration, false,
+			"Include the merged configuration in the output"),
+	)
 
 	return readConfigCmd
 }
@@ -152,7 +124,10 @@ func (cmd *ReadCmd) resolve(ctx context.Context) (
 ) {
 	if cmd.ContainerID == "" && cmd.WorkspaceFolder == "" && len(cmd.IDLabels) == 0 {
 		return nil, "", fmt.Errorf(
-			"either --workspace-folder, --container-id, or --id-label must be provided",
+			"either %s, %s, or %s must be provided",
+			names.Flag(names.WorkspaceFolder),
+			names.Flag(names.ContainerID),
+			names.Flag(names.IDLabel),
 		)
 	}
 	if cmd.ContainerID != "" {

cmd/context/create.go

@@ -9,6 +9,8 @@ import (
 
 	"github.com/devsy-org/devsy/cmd/flags"
 	"github.com/devsy-org/devsy/pkg/config"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	provider2 "github.com/devsy-org/devsy/pkg/provider"
 	"github.com/spf13/cobra"
 )
@@ -34,8 +36,11 @@ func NewCreateCmd(flags *flags.GlobalFlags) *cobra.Command {
 		},
 	}
 
-	createCmd.Flags().
-		StringArrayVarP(&cmd.Options, "option", "o", []string{}, "context option in the form KEY=VALUE")
+	cliflags.Add(
+		createCmd,
+		cliflags.StringArray(&cmd.Options, names.Option, []string{}, "context option in the form KEY=VALUE").
+			Shorthand("o"),
+	)
 	return createCmd
 }
 

cmd/context/set_options.go

@@ -6,6 +6,8 @@ import (
 
 	"github.com/devsy-org/devsy/cmd/flags"
 	"github.com/devsy-org/devsy/pkg/config"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/spf13/cobra"
 )
 
@@ -38,8 +40,11 @@ func NewSetOptionsCmd(flags *flags.GlobalFlags) *cobra.Command {
 		},
 	}
 
-	setOptionsCmd.Flags().
-		StringArrayVarP(&cmd.Options, "option", "o", []string{}, "context option in the form KEY=VALUE")
+	cliflags.Add(
+		setOptionsCmd,
+		cliflags.StringArray(&cmd.Options, names.Option, []string{}, "context option in the form KEY=VALUE").
+			Shorthand("o"),
+	)
 	return setOptionsCmd
 }
 

cmd/context/use.go

@@ -6,6 +6,8 @@ import (
 
 	"github.com/devsy-org/devsy/cmd/flags"
 	"github.com/devsy-org/devsy/pkg/config"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/spf13/cobra"
 )
 
@@ -33,8 +35,11 @@ func NewUseCmd(flags *flags.GlobalFlags) *cobra.Command {
 		},
 	}
 
-	useCmd.Flags().
-		StringArrayVarP(&cmd.Options, "option", "o", []string{}, "context option in the form KEY=VALUE")
+	cliflags.Add(
+		useCmd,
+		cliflags.StringArray(&cmd.Options, names.Option, []string{}, "context option in the form KEY=VALUE").
+			Shorthand("o"),
+	)
 	return useCmd
 }
 

cmd/env_flags_test.go

@@ -4,6 +4,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -77,7 +78,7 @@ func TestOptInEnvFlags_NoEnvLeavesDefault(t *testing.T) {
 		t.Setenv(name, "")
 	}
 	rootCmd, _ := BuildRoot()
-	f := rootCmd.PersistentFlags().Lookup("context")
+	f := rootCmd.PersistentFlags().Lookup(names.Context)
 	require.NotNil(t, f)
 	assert.False(t, f.Changed)
 	assert.Equal(t, "", f.Value.String())
@@ -91,7 +92,7 @@ func TestOptInEnvFlags_EmptyEnvIsNoOp(t *testing.T) {
 	t.Setenv(envDevsyHost, "")
 	rootCmd, _ := BuildRoot()
 	cmd := resolveCommand(t, rootCmd, "pro workspace list")
-	f := cmd.Flags().Lookup("host")
+	f := cmd.Flags().Lookup(names.Host)
 	require.NotNil(t, f)
 	assert.False(t, f.Changed, "empty env value must not mark flag as Changed")
 }
@@ -109,25 +110,22 @@ func TestOptInEnvFlags_CLIOverridesEnv(t *testing.T) {
 	leaf := resolveCommand(t, rootCmd, "pro workspace list")
 	var seen string
 	leaf.RunE = func(c *cobra.Command, _ []string) error {
-		seen, _ = c.Flags().GetString("host")
+		seen, _ = c.Flags().GetString(names.Host)
 		return nil
 	}
 	rootCmd.SetArgs([]string{"pro", cmdWorkspace, cmdList, "--host", "cli-value"})
 	require.NoError(t, rootCmd.Execute())
 	assert.Equal(t, "cli-value", seen, "CLI flag must override env value")
 }
 
-// TestOptInEnvFlags_EnvSatisfiesRequired drives cobra's full parse +
-// ValidateRequiredFlags pipeline to prove DEVSY_HOST satisfies
-// MarkFlagRequired("host") at execution time, not just in static inspection.
 func TestOptInEnvFlags_EnvSatisfiesRequired(t *testing.T) {
 	t.Setenv(envProEnabled, "true")
 	t.Setenv(envDevsyHost, "from-env.example.com")
 	rootCmd, _ := BuildRoot()
 	leaf := resolveCommand(t, rootCmd, "pro workspace list")
 	var seen string
 	leaf.RunE = func(c *cobra.Command, _ []string) error {
-		seen, _ = c.Flags().GetString("host")
+		seen, _ = c.Flags().GetString(names.Host)
 		return nil
 	}
 	rootCmd.SetArgs([]string{"pro", cmdWorkspace, cmdList})

cmd/feature/generatedocs.go

@@ -9,6 +9,8 @@ import (
 
 	"github.com/devsy-org/devsy/cmd/flags"
 	"github.com/devsy-org/devsy/pkg/devcontainer/config"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/devsy-org/devsy/pkg/output"
 	"github.com/devsy-org/devsy/pkg/table"
 	"github.com/spf13/cobra"
@@ -42,16 +44,28 @@ documentation for each feature based on its devcontainer-feature.json.`,
 		},
 	}
 
-	generateDocsCmd.Flags().StringVar(
-		&cmd.ProjectFolder, "project-folder", "", "Path to feature project containing src/ directory",
+	cliflags.Add(
+		generateDocsCmd,
+		cliflags.String(
+			&cmd.ProjectFolder,
+			names.ProjectFolder,
+			"",
+			"Path to feature project containing src/ directory",
+		),
+		cliflags.String(
+			&cmd.OutputFolder,
+			names.OutputFolder,
+			"",
+			"Where to write generated docs (default: project-folder)",
+		),
+		cliflags.String(
+			&cmd.Namespace,
+			names.Namespace,
+			"",
+			"Registry namespace for linking (e.g.ghcr.io/myorg/features)",
+		),
 	)
-	generateDocsCmd.Flags().StringVar(
-		&cmd.OutputFolder, "output-folder", "", "Where to write generated docs (default: project-folder)",
-	)
-	generateDocsCmd.Flags().StringVar(
-		&cmd.Namespace, "namespace", "", "Registry namespace for linking (e.g. ghcr.io/myorg/features)",
-	)
-	_ = generateDocsCmd.MarkFlagRequired("project-folder")
+	_ = generateDocsCmd.MarkFlagRequired(names.ProjectFolder)
 
 	return generateDocsCmd
 }

cmd/feature/info.go

@@ -7,6 +7,8 @@ import (
 	"github.com/devsy-org/devsy/cmd/flags"
 	"github.com/devsy-org/devsy/pkg/devcontainer/config"
 	"github.com/devsy-org/devsy/pkg/devcontainer/feature"
+	cliflags "github.com/devsy-org/devsy/pkg/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/devsy-org/devsy/pkg/output"
 	"github.com/devsy-org/devsy/pkg/table"
 	"github.com/google/go-containerregistry/pkg/authn"
@@ -55,11 +57,20 @@ to display metadata.`,
 		},
 	}
 
-	infoCmd.Flags().BoolVar(
-		&cmd.ShowTags, "show-tags", false, "List available tags from the registry",
-	)
-	infoCmd.Flags().BoolVar(
-		&cmd.ShowDependencies, "show-dependencies", false, "Show declared dependencies",
+	cliflags.Add(
+		infoCmd,
+		cliflags.Bool(
+			&cmd.ShowTags,
+			names.ShowTags,
+			false,
+			"List available tags from the registry",
+		),
+		cliflags.Bool(
+			&cmd.ShowDependencies,
+			names.ShowDependencies,
+			false,
+			"Show declared dependencies",
+		),
 	)
 
 	infoCmd.AddCommand(NewInfoManifestCmd(globalFlags))

cmd/feature/info_test.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 
 	"github.com/devsy-org/devsy/cmd/flags"
+	"github.com/devsy-org/devsy/pkg/flags/names"
 	"github.com/devsy-org/devsy/pkg/output"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -12,11 +13,11 @@ import (
 func TestInfoCmd_FlagDefaults(t *testing.T) {
 	cmd := NewInfoCmd(nil)
 
-	showTagsFlag := cmd.Flags().Lookup("show-tags")
+	showTagsFlag := cmd.Flags().Lookup(names.ShowTags)
 	require.NotNil(t, showTagsFlag)
 	assert.Equal(t, "false", showTagsFlag.DefValue)
 
-	showDepsFlag := cmd.Flags().Lookup("show-dependencies")
+	showDepsFlag := cmd.Flags().Lookup(names.ShowDependencies)
 	require.NotNil(t, showDepsFlag)
 	assert.Equal(t, "false", showDepsFlag.DefValue)
 }