Bug fixes for arg parsing and support for positional arguments

* Bug Fix - Missing Required Args
* Bug Fix - Neo4j Duplicate Arguments
* Test Case Corrections
* Added Positional Arguments Support (in CLI config set args too)
* Terminal text output update for results

Author: peteski22

cmd/config/args/set.go

@@ -56,7 +56,7 @@ func (c *SetCmd) run(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("server-name is required")
 	}
 
-	normalizedArgs := config.NormalizeArgs(args[1:])
+	normalizedArgs := config.ProcessAllArgs(args[1:])
 	cfg, err := c.ctxLoader.Load(flags.RuntimeFile)
 	if err != nil {
 		return fmt.Errorf("failed to load execution context config: %w", err)

internal/config/args.go

@@ -7,12 +7,6 @@ import (
 )
 
 const (
-	// OptionTerminator represents the character sequence generally understood to indicate the termination of options
-	// to be parsed that are supplied to a command line interface.
-	// e.g. in the command: kubectl exec random_pod -- ls
-	// 'ls' is not parsed by kubectl and instead passed verbatim to the random_pod.
-	OptionTerminator = "--"
-
 	// FlagPrefixLong represents the expected prefix for a long format flag (e.g. --flag).
 	FlagPrefixLong = "--"
 
@@ -32,7 +26,7 @@ const (
 //	--flag=value     -> preserved as-is
 //	-xyz             -> -x, -y, -z (expanded short flags)
 //
-// Parsing stops at OptionTerminator ("--"). Positional arguments and arguments after OptionTerminator are excluded.
+// Positional arguments are excluded.
 //
 // This function is intended for internal normalization of flag arguments only.
 func NormalizeArgs(rawArgs []string) []string {
@@ -42,10 +36,6 @@ func NormalizeArgs(rawArgs []string) []string {
 	for i := 0; i < numArgs; i++ {
 		arg := strings.TrimSpace(rawArgs[i])
 
-		if arg == OptionTerminator {
-			break // stop parsing flags (exclude "--" and everything after).
-		}
-
 		nextIndex := i + 1
 		hasNext := nextIndex < numArgs
 		isShortFlag := strings.HasPrefix(arg, FlagPrefixShort) && !strings.HasPrefix(arg, FlagPrefixLong)
@@ -152,6 +142,60 @@ func MergeArgs(a, b []string) []string {
 	return result
 }
 
+// ProcessAllArgs processes a slice of arguments, normalizing flags while preserving positional arguments.
+// It processes arguments sequentially, normalizing flag groups as it encounters them,
+// and returns them in their original relative order.
+//
+// Examples:
+//   - ["--flag", "value", "pos1", "pos2"] -> ["--flag=value", "pos1", "pos2"]
+//   - ["pos1", "--flag=value", "pos2"] -> ["pos1", "--flag=value", "pos2"]
+//   - ["/path/to/dir", "--verbose"] -> ["/path/to/dir", "--verbose"]
+func ProcessAllArgs(rawArgs []string) []string {
+	if len(rawArgs) == 0 {
+		return []string{}
+	}
+
+	var result []string
+
+	// Process arguments sequentially
+	for i := 0; i < len(rawArgs); i++ {
+		arg := strings.TrimSpace(rawArgs[i])
+
+		isFlag := strings.HasPrefix(arg, FlagPrefixShort) || strings.HasPrefix(arg, FlagPrefixLong)
+		if isFlag {
+			// Check for combined short flags (like -xyz) which should not consume next arg as value
+			isCombinedShortFlag := strings.HasPrefix(arg, FlagPrefixShort) &&
+				!strings.HasPrefix(arg, FlagPrefixLong) &&
+				len(arg) > 2 &&
+				!strings.Contains(arg, FlagValueSeparator)
+
+			// Collect this flag and potentially its value for normalization
+			flagGroup := []string{arg}
+
+			// Check if next argument is a value for this flag (not embedded with =)
+			// Don't consume next arg for combined short flags
+			if !isCombinedShortFlag && !strings.Contains(arg, FlagValueSeparator) && i+1 < len(rawArgs) {
+				nextArg := strings.TrimSpace(rawArgs[i+1])
+				nextIsFlag := strings.HasPrefix(nextArg, FlagPrefixShort) || strings.HasPrefix(nextArg, FlagPrefixLong)
+				if !nextIsFlag {
+					// Include the value
+					flagGroup = append(flagGroup, nextArg)
+					i++ // Skip the next argument since we processed it
+				}
+			}
+
+			// Normalize this flag group and add to result
+			normalizedFlags := NormalizeArgs(flagGroup)
+			result = append(result, normalizedFlags...)
+		} else {
+			// Positional argument - add as-is
+			result = append(result, arg)
+		}
+	}
+
+	return result
+}
+
 // parseArgs converts a slice of argument strings into a map of argEntry
 func parseArgs(args []string) map[string]argEntry {
 	result := make(map[string]argEntry, len(args))

internal/config/args_test.go

@@ -40,11 +40,6 @@ func TestNormalizeArgs(t *testing.T) {
 			input:    []string{"-xzv"},
 			expected: []string{"-x", "-z", "-v"},
 		},
-		{
-			name:     "terminator excludes all after",
-			input:    []string{"--foo", "bar", "--", "--ignored", "positional"},
-			expected: []string{"--foo=bar"},
-		},
 		{
 			name:     "positional args are skipped",
 			input:    []string{"--foo", "bar", "main.go", "--baz", "qux"},
@@ -490,3 +485,88 @@ func TestArgEntry_String(t *testing.T) {
 		})
 	}
 }
+
+func TestProcessAllArgs(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		input    []string
+		expected []string
+	}{
+		{
+			name:     "empty input",
+			input:    []string{},
+			expected: []string{},
+		},
+		{
+			name:     "only positional args",
+			input:    []string{"pos1", "pos2", "pos3"},
+			expected: []string{"pos1", "pos2", "pos3"},
+		},
+		{
+			name:     "only flags with embedded values",
+			input:    []string{"--flag=value", "--other=val"},
+			expected: []string{"--flag=value", "--other=val"},
+		},
+		{
+			name:     "only boolean flags",
+			input:    []string{"--verbose", "--debug"},
+			expected: []string{"--verbose", "--debug"},
+		},
+		{
+			name:     "flags with separate values (regression test)",
+			input:    []string{"--config", "dev.toml", "--output", "result.txt"},
+			expected: []string{"--config=dev.toml", "--output=result.txt"},
+		},
+		{
+			name:     "mixed flags and positional args maintaining order",
+			input:    []string{"pos1", "--flag=value", "pos2", "--verbose", "pos3"},
+			expected: []string{"pos1", "--flag=value", "pos2", "--verbose=pos3"},
+		},
+		{
+			name:     "flag with separate value followed by positional",
+			input:    []string{"--config", "dev.toml", "positional"},
+			expected: []string{"--config=dev.toml", "positional"},
+		},
+		{
+			name:     "positional followed by flag with separate value",
+			input:    []string{"positional", "--config", "dev.toml"},
+			expected: []string{"positional", "--config=dev.toml"},
+		},
+		{
+			name:     "complex mix with various flag formats",
+			input:    []string{"pos1", "--flag=embedded", "--other", "separate", "--bool", "pos2"},
+			expected: []string{"pos1", "--flag=embedded", "--other=separate", "--bool=pos2"},
+		},
+		{
+			name:     "short flags with separate values",
+			input:    []string{"-f", "value", "-x", "other"},
+			expected: []string{"-f=value", "-x=other"},
+		},
+		{
+			name:     "combined short flags",
+			input:    []string{"-xyz", "pos1"},
+			expected: []string{"-x", "-y", "-z", "pos1"},
+		},
+		{
+			name:     "flag followed by another flag (no value consumption)",
+			input:    []string{"--verbose", "--debug", "pos1"},
+			expected: []string{"--verbose", "--debug=pos1"},
+		},
+		{
+			name:     "multiple consecutive flags with separate values",
+			input:    []string{"--first", "val1", "--second", "val2", "--third", "val3"},
+			expected: []string{"--first=val1", "--second=val2", "--third=val3"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			actual := ProcessAllArgs(tc.input)
+			require.Equal(t, tc.expected, actual, "ProcessAllArgs should preserve order and normalize flags correctly")
+		})
+	}
+}

internal/packages/argument.go

@@ -15,6 +15,9 @@ const (
 
 	// VariableTypeArgBool represents a command line argument that is a boolean flag (doesn't have a value).
 	VariableTypeArgBool VariableType = "argument_bool"
+
+	// VariableTypePositionalArg represents a positional command line argument.
+	VariableTypePositionalArg VariableType = "positional_argument"
 )
 
 // EnvVarPlaceholderRegex is used to find environment variable placeholders like ${VAR_NAME}.
@@ -27,9 +30,11 @@ type Arguments map[string]ArgumentMetadata
 
 // ArgumentMetadata represents metadata about an argument/variable
 type ArgumentMetadata struct {
+	Name         string       `json:"name"`
 	Description  string       `json:"description"`
 	Required     bool         `json:"required"`
 	VariableType VariableType `json:"type"`
+	Position     *int         `json:"position,omitempty"` // Position in args array for positional arguments
 }
 
 // FilterBy allows filtering of Arguments using predicates.
@@ -43,6 +48,46 @@ func (a Arguments) Names() []string {
 	return slices.Collect(maps.Keys(a))
 }
 
+// Ordered returns all arguments with positional arguments first (in position order),
+// followed by all other arguments in alphabetical order by name.
+func (a Arguments) Ordered() []ArgumentMetadata {
+	var positional []ArgumentMetadata
+	var others []ArgumentMetadata
+
+	for name, meta := range a {
+		// Ensure name is set in the metadata
+		meta.Name = name
+
+		if meta.VariableType == VariableTypePositionalArg && meta.Position != nil {
+			positional = append(positional, meta)
+		} else {
+			others = append(others, meta)
+		}
+	}
+
+	// Sort positional by position
+	slices.SortFunc(positional, func(a, b ArgumentMetadata) int {
+		return *a.Position - *b.Position
+	})
+
+	// Sort others alphabetically by name
+	slices.SortFunc(others, func(a, b ArgumentMetadata) int {
+		if a.Name < b.Name {
+			return -1
+		} else if a.Name > b.Name {
+			return 1
+		}
+		return 0
+	})
+
+	// Combine: positional first, then others
+	result := make([]ArgumentMetadata, 0, len(positional)+len(others))
+	result = append(result, positional...)
+	result = append(result, others...)
+
+	return result
+}
+
 // FilterArguments allows Arguments to be filtered using any number of predicates.
 // All predicates must be true in order for an argument to be included in the results.
 func FilterArguments(args Arguments, predicate ...func(name string, data ArgumentMetadata) bool) Arguments {
@@ -71,7 +116,7 @@ func EnvVar(_ string, data ArgumentMetadata) bool {
 
 // Argument is a predicate that requires the argument is a command line argument.
 func Argument(s string, data ArgumentMetadata) bool {
-	return ValueArgument(s, data) || BoolArgument(s, data)
+	return ValueArgument(s, data) || BoolArgument(s, data) || PositionalArgument(s, data)
 }
 
 // ValueArgument is a predicate that requires the argument is a command line argument which requires a value.
@@ -83,3 +128,13 @@ func ValueArgument(_ string, data ArgumentMetadata) bool {
 func BoolArgument(_ string, data ArgumentMetadata) bool {
 	return data.VariableType == VariableTypeArgBool
 }
+
+// PositionalArgument is a predicate that requires the argument is a positional command line argument.
+func PositionalArgument(_ string, data ArgumentMetadata) bool {
+	return data.VariableType == VariableTypePositionalArg
+}
+
+// NonPositionalArgument is a predicate that requires the argument is not a positional command line argument.
+func NonPositionalArgument(s string, data ArgumentMetadata) bool {
+	return !PositionalArgument(s, data)
+}

internal/printer/package_printer.go

@@ -145,12 +145,25 @@ func (p *PackagePrinter) Item(w io.Writer, pkg packages.Package) error {
 			}
 		}
 
-		args := pkg.Arguments.FilterBy(packages.Argument).Names()
-		if len(args) > 0 {
-			if _, err := fmt.Fprintln(w, "  📋 Args configurable via command line..."); err != nil {
+		// Positional arguments (in order)
+		positionalArgs := pkg.Arguments.FilterBy(packages.PositionalArgument).Ordered()
+		if len(positionalArgs) > 0 {
+			if _, err := fmt.Fprintln(w, "  📍 Positional arguments:"); err != nil {
 				return err
 			}
-			if _, err := fmt.Fprintf(w, "  🖥️ %s\n", strings.Join(args, ", ")); err != nil {
+
+			for _, arg := range positionalArgs {
+				_, _ = fmt.Fprintf(w, "\t(%d) %s\n", *arg.Position, arg.Name)
+			}
+		}
+
+		// Command-line flags (excluding positional arguments)
+		flagArgs := pkg.Arguments.FilterBy(packages.NonPositionalArgument).Names()
+		if len(flagArgs) > 0 {
+			if _, err := fmt.Fprintln(w, "  📋 Args configurable via command line flags..."); err != nil {
+				return err
+			}
+			if _, err := fmt.Fprintf(w, "  🖥️ %s\n", strings.Join(flagArgs, ", ")); err != nil {
 				return err
 			}
 		}