ra_cmd_parse.go

package ra

import (
	"errors"
	"fmt"
	"os"
	"strconv"
	"strings"

	"github.com/amterp/color"
)

// HelpInvokedErr is returned by ParseOrError when help is invoked (via -h, --help, or auto-help).
// Users can compare against this constant to detect when help was shown instead of a parsing error.
var HelpInvokedErr = errors.New("help invoked")

// DumpInvokedErr is returned by ParseOrError when dump is invoked (via WithDump(true)).
// Users can compare against this constant to detect when dump was shown instead of parsing.
var DumpInvokedErr = errors.New("dump invoked")

// Internal error wrapper to carry exit code for ParseOrExit
type helpInvokedError struct {
	output         string // The usage text that was/would be output (empty if not yet generated)
	exitCode       int    // The exit code (0 for help, 1 for error)
	useStdout      bool   // Whether to output to stdout (true for help requests) or stderr (false for errors)
	isLongHelp     bool   // true for --help, false for -h or auto-help
	isAutoHelp     bool   // true if triggered by auto-help (no args with required flags)
	useCustomUsage bool   // true if custom usage function should be used
	cmd            *Cmd   // The command that help was invoked for (for subcommand help)
}

// newHelpInvokedError creates a new helpInvokedError with mandatory cmd field.
// This ensures that help errors always know which command they originated from,
// allowing proper help generation for subcommands.
func newHelpInvokedError(
	cmd *Cmd,
	exitCode int,
	useStdout bool,
	isLongHelp bool,
	isAutoHelp bool,
	useCustomUsage bool,
) *helpInvokedError {
	if cmd == nil {
		panic("helpInvokedError requires non-nil cmd - this is a programming error")
	}
	return &helpInvokedError{
		output:         "",
		exitCode:       exitCode,
		useStdout:      useStdout,
		isLongHelp:     isLongHelp,
		isAutoHelp:     isAutoHelp,
		useCustomUsage: useCustomUsage,
		cmd:            cmd,
	}
}

func (e *helpInvokedError) Error() string {
	return HelpInvokedErr.Error()
}

func (e *helpInvokedError) Unwrap() error {
	return HelpInvokedErr
}

// Internal error wrapper for dump invocation
type dumpInvokedError struct {
	output   string // The dump output (empty if not yet generated)
	exitCode int    // The exit code (0 for successful dump)
}

func (e *dumpInvokedError) Error() string {
	return DumpInvokedErr.Error()
}

func (e *dumpInvokedError) Unwrap() error {
	return DumpInvokedErr
}

// TooManyPositionalArgsError is returned when positional arguments are provided
// beyond what the command's positional flags can consume. Unused contains every
// unconsumed positional, in the order they appeared.
type TooManyPositionalArgsError struct {
	Unused []string
}

func (e *TooManyPositionalArgsError) Error() string {
	return fmt.Sprintf("Too many positional arguments. Unused: [%s]", strings.Join(e.Unused, ", "))
}

// ProgrammingError wraps errors caused by incorrect library setup/configuration.
// These are bugs in the code using Ra, not user input errors.
type ProgrammingError struct {
	msg string
}

func (e *ProgrammingError) Error() string {
	return e.msg
}

// NewProgrammingError creates a new programming error
func NewProgrammingError(msg string) *ProgrammingError {
	return &ProgrammingError{msg: msg}
}

func (c *Cmd) ParseOrExit(args []string, opts ...ParseOpt) {
	err := c.parse(args, opts...)

	// Call PostParse hook after parsing, before any output (success or error)
	if c.parseHooks != nil && c.parseHooks.PostParse != nil {
		c.parseHooks.PostParse(c, err)
	}

	if err != nil {
		// Check if this is a completion invoked error (output already written)
		if _, ok := err.(*completionInvokedError); ok {
			osExit(0)
			return
		}

		// Check if this is a help invoked error
		if helpErr, ok := err.(*helpInvokedError); ok {
			// Determine which command to generate help for
			targetCmd := c
			if helpErr.cmd != nil {
				targetCmd = helpErr.cmd
			}

			// Generate help output now, after PostParse hook has been called
			var output string
			if helpErr.useCustomUsage {
				if targetCmd.customUsage != nil {
					targetCmd.customUsage(helpErr.isLongHelp)
					output = "" // Custom usage handles output directly
				}
			} else {
				if helpErr.isLongHelp {
					output = targetCmd.GenerateLongUsage()
				} else {
					output = targetCmd.GenerateShortUsage()
				}
			}

			// Route output to stdout for help requests, stderr for errors
			if output != "" {
				if helpErr.useStdout {
					fmt.Fprint(stdoutWriter, output)
				} else {
					fmt.Fprint(stderrWriter, output)
				}
			}
			osExit(helpErr.exitCode)
		} else if dumpErr, ok := err.(*dumpInvokedError); ok {
			// Generate dump output now, after PostParse hook has been called
			output := c.generateDump(args, opts...)
			if output != "" {
				fmt.Fprint(stdoutWriter, output)
			}
			osExit(dumpErr.exitCode)
		} else if _, ok := err.(*ProgrammingError); ok {
			// Programming error - show only error message (no usage)
			fmt.Fprintln(stderrWriter, err.Error())
			osExit(1)
		} else {
			// Regular error - show error message and usage
			fmt.Fprintln(stderrWriter, err.Error())
			if c.parseHooks != nil && c.parseHooks.ErrorHint != nil {
				if hint := c.parseHooks.ErrorHint(c, err); hint != "" {
					fmt.Fprintln(stderrWriter, hint)
				}
			}
			fmt.Fprintln(stderrWriter)
			fmt.Fprint(stderrWriter, c.GenerateLongUsage())
			osExit(1)
		}
	}
}

func (c *Cmd) ParseOrError(args []string, opts ...ParseOpt) error {
	err := c.parse(args, opts...)

	// Call PostParse hook after parsing, before any output (success or error)
	if c.parseHooks != nil && c.parseHooks.PostParse != nil {
		c.parseHooks.PostParse(c, err)
	}

	if err != nil {
		// Check if this is a completion invoked error
		if _, ok := err.(*completionInvokedError); ok {
			return CompletionInvokedErr
		}

		// Check if this is a help invoked error
		if helpErr, ok := err.(*helpInvokedError); ok {
			// Determine which command to use for custom usage
			targetCmd := c
			if helpErr.cmd != nil {
				targetCmd = helpErr.cmd
			}

			// Call custom usage function if it exists, even though ParseOrError doesn't display output
			// This maintains backward compatibility for custom usage functions that may have side effects
			if helpErr.useCustomUsage && targetCmd.customUsage != nil {
				targetCmd.customUsage(helpErr.isLongHelp)
			}
			return HelpInvokedErr
		} else if _, ok := err.(*dumpInvokedError); ok {
			// Dump was invoked - ParseOrError doesn't display output, but we return the standard error
			return DumpInvokedErr
		}
	}
	return err
}

func (c *Cmd) parse(args []string, opts ...ParseOpt) error {
	return c.parseWithPreserveState(args, false, opts...)
}

func (c *Cmd) parseWithPreserveState(args []string, preserveConfigured bool, opts ...ParseOpt) error {
	initializeColorFromEnv()

	cfg := &parseCfg{}
	for _, opt := range opts {
		opt(cfg)
	}

	// reset state in case this is called multiple times
	if !preserveConfigured {
		c.configured = make(map[string]bool)
	}
	c.unknownArgs = []string{}
	c.excessPositionals = []string{}
	c.collectingSlice = ""
	c.sawFlag = false

	// Add help flags if enabled
	if c.helpEnabled {
		if _, exists := c.flags["help"]; !exists {
			NewBool(
				"help",
			).SetShort("h").
				SetUsage("Print usage string.").
				SetOptional(true).
				Register(c, WithGlobal(true))
		}
	}

	if err := c.validateBeforeParsing(); err != nil {
		return err
	}

	// Set defaults first
	if err := c.setDefaults(); err != nil {
		return err
	}

	// Check for __complete - divert to completion logic if enabled
	if c.completionEnabled && len(args) > 0 && args[0] == "__complete" {
		return c.handleCompletion(args[1:])
	}

	// Check for dump mode - if enabled, generate dump output and return
	if cfg.dump {
		return &dumpInvokedError{
			output:   "", // Will be generated later, after PostParse hook
			exitCode: 0,
		}
	}

	// Check for auto-help: if enabled, no args provided, and something on this
	// invocation would have required an argument. The default sub-command counts:
	// routing a bare invocation into it would answer with "missing required
	// argument", which hides the fact that other commands exist. Help says both.
	if c.autoHelpOnNoArgs && len(args) == 0 && (c.hasRequiredFlags() || c.defaultRequiresArgs()) {
		return newHelpInvokedError(
			c,                    // cmd
			0,                    // exitCode
			true,                 // useStdout
			false,                // isLongHelp (auto-help uses short help)
			true,                 // isAutoHelp
			c.customUsage != nil, // useCustomUsage
		)
	}

	// Check if we have number shorts mode
	numberShortsMode := c.hasNumberShorts()

	// Parse arguments
	i := 0
	seenDashDash := false // Track if we've seen -- and should treat everything as positional

	for i < len(args) {
		arg := args[i]

		// Check for -- (end of flags marker)
		if arg == "--" && !seenDashDash {
			seenDashDash = true
			i++
			continue
		}

		// If we're in positional-only mode, treat everything as positional
		if seenDashDash {
			if err := c.assignPositionalWithMode(arg, posAfterDashDash); err != nil {
				// `--` suppresses sub-command lookup, so this is how a caller
				// says "route to the default even though the value looks like
				// a command name". Re-prefix `--` so it keeps meaning that all
				// the way down.
				if routed, handled := c.routeToDefault(append([]string{"--"}, args[i:]...), opts...); handled {
					return routed
				}
				if cfg.ignoreUnknown {
					c.unknownArgs = append(c.unknownArgs, arg)
				} else if !c.collectIfExcessPositional(arg, err) {
					return err
				}
			}
			i++
			continue
		}

		// Check for subcommand first (only if not in positional-only mode)
		if !strings.HasPrefix(arg, "-") {
			if subCmd, exists := c.subCmds[arg]; exists {
				// The named command wins over the default, which is what makes
				// the default's own name a usable escape hatch for a value that
				// collides with a sibling's.
				return c.dispatchTo(subCmd, args[i+1:], opts...)
			}
		}

		// Handle flags (only if not in positional-only mode)
		if strings.HasPrefix(arg, "-") {
			consumed, err := c.parseFlag(args, i, numberShortsMode, cfg)
			if err != nil {
				if err.Error() == "not a flag: "+arg {
					// This is a negative number, treat as positional
					if err := c.assignPositional(arg); err != nil {
						if routed, handled := c.routeToDefault(args[i:], opts...); handled {
							return routed
						}
						if cfg.ignoreUnknown {
							c.unknownArgs = append(c.unknownArgs, arg)
						} else if !c.collectIfExcessPositional(arg, err) {
							return err
						}
					}
					i++
					continue
				}

				// Handle unknown flags
				if cfg.variadicUnknownFlags {
					// Check if we have an active variadic or an unassigned variadic positional.
					// This allows variadics to be "activated" in two ways:
					//   1. Already active (collectingSlice != "") from consuming a previous value
					//   2. Newly activated by finding the first unassigned variadic positional
					// This enables: radd test.rad -U (where -U activates the variadic)
					// Swallowing flag-shaped tokens is raw rest capture, which stays
					// the variadic's job. A plain list may be the active collector,
					// but it declines here so the unknown flag stays the error it is.
					variadicFlag := c.collectingSlice
					if variadicFlag != "" && !isVariadicFlag(c.flags[variadicFlag]) {
						variadicFlag = ""
					}
					if variadicFlag == "" {
						variadicFlag = c.findNextUnassignedVariadicPositional()
					}

					if variadicFlag != "" {
						// We have a variadic that can consume this unknown flag
						if err := c.assignPositionalWithMode(arg, posUnknownFlagToken); err != nil {
							// If variadic assignment fails, fall back to normal unknown handling
							if routed, handled := c.routeToDefault(args[i:], opts...); handled {
								return routed
							}
							if cfg.ignoreUnknown {
								c.unknownArgs = append(c.unknownArgs, arg)
							} else if !c.collectIfExcessPositional(arg, err) {
								return err
							}
						} else {
							// Successfully assigned - activate the variadic if it wasn't already
							c.collectingSlice = variadicFlag
						}
						i++
						continue
					}
				}

				// A flag this command has never heard of may still belong to
				// the default. That matters because a default's own flags are
				// registered on it, not here, so without this only the
				// positional spellings of the default would be reachable.
				if routed, handled := c.routeToDefault(args[i:], opts...); handled {
					return routed
				}

				if cfg.ignoreUnknown {
					c.unknownArgs = append(c.unknownArgs, arg)
					i++
					continue
				}
				return err
			}
			c.sawFlag = true
			c.collectingSlice = "" // A flag ends the current collection run
			i += consumed
		} else {
			// Handle positional argument
			if err := c.assignPositional(arg); err != nil {
				// Nothing here can hold this value. If a default exists, the
				// value is its first argument rather than an error.
				if routed, handled := c.routeToDefault(args[i:], opts...); handled {
					return routed
				}
				if cfg.ignoreUnknown {
					c.unknownArgs = append(c.unknownArgs, arg)
				} else if !c.collectIfExcessPositional(arg, err) {
					return err
				}
			}
			i++
		}
	}

	// Check for help flags after parsing (only if helpEnabled is true)
	if c.helpEnabled {
		for _, arg := range args {
			if arg == "--help" {
				return newHelpInvokedError(
					c,                    // cmd
					0,                    // exitCode
					true,                 // useStdout
					true,                 // isLongHelp
					false,                // isAutoHelp
					c.customUsage != nil, // useCustomUsage
				)
			}
			if arg == "-h" {
				return newHelpInvokedError(
					c,                    // cmd
					0,                    // exitCode
					true,                 // useStdout
					false,                // isLongHelp
					false,                // isAutoHelp
					c.customUsage != nil, // useCustomUsage
				)
			}
		}
	}

	// Reaching here means no sub-command was named at this level - a named one
	// returns from the loop. A default takes the invocation, including the bare
	// one, which is what makes `tool <args>` work without naming a command.
	// After the help scan above, so `tool -h` still shows this level's help
	// rather than the default's.
	if routed, handled := c.routeToDefault(nil, opts...); handled {
		return routed
	}

	// Report all unconsumed positionals together, now that flags after them have
	// still been parsed and help (above) has had a chance to win.
	if len(c.excessPositionals) > 0 {
		return &TooManyPositionalArgsError{Unused: c.excessPositionals}
	}

	// Validate required flags
	return c.validateRequired()
}

// dispatchTo hands the rest of the command line to a sub-command. Both the
// named route and the default route go through here: the "was used" flag, the
// global-flag cascade and the configured-state carry-over all have to happen
// identically, and a second copy is where they would quietly diverge.
func (c *Cmd) dispatchTo(subCmd *Cmd, rest []string, opts ...ParseOpt) error {
	// Delegating returns the child's result directly, so excess positionals
	// collected so far would be silently dropped - report them now instead
	// (pre-collect fail-fast behavior).
	if len(c.excessPositionals) > 0 {
		return &TooManyPositionalArgsError{Unused: c.excessPositionals}
	}
	*subCmd.used = true
	// Apply global flags to subcommand before parsing
	if err := c.applyGlobalFlags(subCmd); err != nil {
		return err
	}
	// Apply global configured state before parsing
	for _, globalFlagName := range c.globalFlags {
		if c.configured[globalFlagName] {
			subCmd.configured[globalFlagName] = true
		}
	}
	return subCmd.parseWithPreserveState(rest, true, opts...)
}

// routeToDefault hands args to the default sub-command, if one is set. The
// caller passes the offending token *included* - unlike a named dispatch, the
// token is not a command name being consumed, it is the default's first value.
//
// Returns handled=false when there is no default, leaving the caller to report
// its original error.
func (c *Cmd) routeToDefault(rest []string, opts ...ParseOpt) (error, bool) {
	def := c.defaultCmd()
	if def == nil {
		return nil, false
	}
	return c.dispatchTo(def, rest, opts...), true
}

// collectIfExcessPositional records value for end-of-parse reporting if err is a
// TooManyPositionalArgsError, letting parsing continue past stray positionals so
// the full set can be reported at once. Returns false for any other error, which
// should abort parsing as before (e.g. type-conversion failures).
func (c *Cmd) collectIfExcessPositional(value string, err error) bool {
	var tooMany *TooManyPositionalArgsError
	if errors.As(err, &tooMany) {
		c.excessPositionals = append(c.excessPositionals, value)
		return true
	}
	return false
}

func (c *Cmd) setDefaults() error {
	for _, flag := range c.flags {
		switch f := flag.(type) {
		case *BoolFlag:
			if f.Default != nil && !c.configured[f.Name] {
				*f.Value = *f.Default
			}
		case *StringFlag:
			if f.Default != nil && !c.configured[f.Name] {
				*f.Value = *f.Default
			}
		case *IntFlag:
			if f.Default != nil && !c.configured[f.Name] {
				*f.Value = *f.Default
			}
		case *Int64Flag:
			if f.Default != nil && !c.configured[f.Name] {
				*f.Value = *f.Default
			}
		case *Float64Flag:
			if f.Default != nil && !c.configured[f.Name] {
				*f.Value = *f.Default
			}
		case *StringSliceFlag:
			if !c.configured[f.Name] {
				if f.Default != nil {
					*f.Value = *f.Default
				} else {
					*f.Value = []string{}
				}
			}
		case *IntSliceFlag:
			if !c.configured[f.Name] {
				if f.Default != nil {
					*f.Value = *f.Default
				} else {
					*f.Value = []int{}
				}
			}
		case *Int64SliceFlag:
			if !c.configured[f.Name] {
				if f.Default != nil {
					*f.Value = *f.Default
				} else {
					*f.Value = []int64{}
				}
			}
		case *Float64SliceFlag:
			if !c.configured[f.Name] {
				if f.Default != nil {
					*f.Value = *f.Default
				} else {
					*f.Value = []float64{}
				}
			}
		case *BoolSliceFlag:
			if !c.configured[f.Name] {
				if f.Default != nil {
					*f.Value = *f.Default
				} else {
					*f.Value = []bool{}
				}
			}
		}
	}
	return nil
}
func (c *Cmd) hasNumberShorts() bool {
	for _, flag := range c.flags {
		var short string
		switch f := flag.(type) {
		case *IntFlag:
			short = f.Short
		case *Int64Flag:
			short = f.Short
		case *Float64Flag:
			short = f.Short
		case *StringFlag:
			short = f.Short
		case *BoolFlag:
			short = f.Short
		case *StringSliceFlag:
			short = f.Short
		case *IntSliceFlag:
			short = f.Short
		case *Int64SliceFlag:
			short = f.Short
		case *Float64SliceFlag:
			short = f.Short
		case *BoolSliceFlag:
			short = f.Short
		}
		if short != "" && len(short) == 1 && isDigit(short[0]) {
			return true
		}
	}
	return false
}

// findNextUnassignedVariadicPositional returns the name of the first unassigned variadic positional flag
// (in registration order), or an empty string if none exists
func (c *Cmd) findNextUnassignedVariadicPositional() string {
	for _, name := range c.positional {
		flag := c.flags[name]

		// Skip if already configured
		if c.configured[name] {
			continue
		}

		// Check if it's a variadic slice flag
		switch f := flag.(type) {
		case *StringSliceFlag:
			if f.Variadic && !f.FlagOnly {
				return name
			}
		case *IntSliceFlag:
			if f.Variadic && !f.FlagOnly {
				return name
			}
		case *Int64SliceFlag:
			if f.Variadic && !f.FlagOnly {
				return name
			}
		case *Float64SliceFlag:
			if f.Variadic && !f.FlagOnly {
				return name
			}
		case *BoolSliceFlag:
			if f.Variadic && !f.FlagOnly {
				return name
			}
		}
	}
	return ""
}

func (c *Cmd) parseFlag(args []string, index int, numberShortsMode bool, cfg *parseCfg) (int, error) {
	arg := args[index]

	if strings.HasPrefix(arg, "--") {
		// Long flag
		return c.parseLongFlag(args, index, numberShortsMode, cfg)
	} else if strings.HasPrefix(arg, "-") {
		// Short flag(s)
		return c.parseShortFlag(args, index, numberShortsMode, cfg)
	}

	return 0, fmt.Errorf("invalid flag: %s", arg)
}

func (c *Cmd) parseLongFlag(args []string, index int, numberShortsMode bool, cfg *parseCfg) (int, error) {
	arg := args[index]
	flagName := arg[2:] // remove --

	// Check for = syntax
	var value string
	var hasValue bool
	if idx := strings.Index(flagName, "="); idx != -1 {
		value = flagName[idx+1:]
		flagName = flagName[:idx]
		hasValue = true
	}

	flag, exists := c.flags[flagName]
	if !exists {
		// Before returning unknown flag error, check if help flags are present
		if c.helpEnabled && c.hasHelpFlags(args) {
			return 0, c.createHelpError(args)
		}
		return 0, fmt.Errorf("unknown flag: --%s", flagName)
	}

	c.configured[flagName] = true

	switch f := flag.(type) {
	case *BoolFlag:
		if hasValue {
			val, err := c.parseBoolValue(value)
			if err != nil {
				return 0, fmt.Errorf("invalid value for flag --%s: %s", flagName, err.Error())
			}
			*f.Value = val
		} else {
			*f.Value = true
		}
		return 1, nil
	case *StringFlag:
		if hasValue {
			err := c.setStringValue(f, value)
			return 1, err
		}
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag --%s requires a value", flagName)
		}
		if err := c.checkFlagValue(args, args[index+1], "--"+flagName, false, numberShortsMode); err != nil {
			return 0, err
		}
		err := c.setStringValue(f, args[index+1])
		return 2, err
	case *IntFlag:
		if hasValue {
			err := c.setIntValue(f, value)
			return 1, err
		}
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag --%s requires a value", flagName)
		}
		if err := c.checkFlagValue(args, args[index+1], "--"+flagName, true, numberShortsMode); err != nil {
			return 0, err
		}
		err := c.setIntValue(f, args[index+1])
		return 2, err
	case *Int64Flag:
		if hasValue {
			err := c.setInt64Value(f, value)
			return 1, err
		}
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag --%s requires a value", flagName)
		}
		if err := c.checkFlagValue(args, args[index+1], "--"+flagName, true, numberShortsMode); err != nil {
			return 0, err
		}
		err := c.setInt64Value(f, args[index+1])
		return 2, err
	case *Float64Flag:
		if hasValue {
			err := c.setFloat64Value(f, value)
			return 1, err
		}
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag --%s requires a value", flagName)
		}
		if err := c.checkFlagValue(args, args[index+1], "--"+flagName, true, numberShortsMode); err != nil {
			return 0, err
		}
		err := c.setFloat64Value(f, args[index+1])
		return 2, err
	case *StringSliceFlag:
		if hasValue {
			_, err := c.appendStringSliceValue(f, value)
			return 1, err
		}
		return c.parseSliceFlag(args, index, f, "--"+flagName, numberShortsMode, cfg)
	case *IntSliceFlag:
		if hasValue {
			_, err := c.appendIntSliceValue(f, value)
			return 1, err
		}
		return c.parseIntSliceFlag(args, index, f, "--"+flagName, numberShortsMode)
	case *Int64SliceFlag:
		if hasValue {
			_, err := c.appendInt64SliceValue(f, value)
			return 1, err
		}
		return c.parseInt64SliceFlag(args, index, f, "--"+flagName, numberShortsMode)
	case *Float64SliceFlag:
		if hasValue {
			_, err := c.appendFloat64SliceValue(f, value)
			return 1, err
		}
		return c.parseFloat64SliceFlag(args, index, f, "--"+flagName, numberShortsMode)
	case *BoolSliceFlag:
		if hasValue {
			_, err := c.appendBoolSliceValue(f, value)
			return 1, err
		}
		return c.parseBoolSliceFlag(args, index, f, "--"+flagName, numberShortsMode)
	}

	return 0, NewProgrammingError(fmt.Sprintf("unsupported flag type for: %s", flagName))
}

func (c *Cmd) parseShortFlag(args []string, index int, numberShortsMode bool, cfg *parseCfg) (int, error) {
	arg := args[index]
	shorts := arg[1:] // remove -

	// Check for = syntax in short flags (e.g., -r=value)
	var value string
	var hasValue bool
	if idx := strings.Index(shorts, "="); idx != -1 {
		value = shorts[idx+1:]
		shorts = shorts[:idx]
		hasValue = true
	}

	// Check if this is a negative number without number shorts mode
	if !numberShortsMode && len(shorts) > 0 && (isDigit(shorts[0]) || shorts[0] == '.') {
		// This is a negative number, treat as positional
		return 0, fmt.Errorf("not a flag: %s", arg)
	}

	// In number shorts mode, check if this is a negative number
	if numberShortsMode && len(shorts) > 0 && isDigit(shorts[0]) {
		// This is a number short flag
		if flagName, exists := c.shortToName[shorts]; exists {
			flag := c.flags[flagName]
			c.configured[flagName] = true

			switch f := flag.(type) {
			case *IntFlag:
				if len(shorts) > 1 {
					// Multiple occurrences like -aaa
					count := len(shorts)
					*f.Value = count
					return 1, nil
				}
				// Single occurrence
				if hasValue {
					// Use equals value
					err := c.setIntValue(f, value)
					return 1, err
				} else {
					// Check if next argument exists and is a valid value. A flag-shaped
					// token isn't one, but a negative number is - "-c -5" means -5, the
					// same as "--count -5".
					if index+1 < len(args) && canBeCountedFlagValue(args[index+1], numberShortsMode) {
						// Next arg is a value, try to parse it
						err := c.setIntValue(f, args[index+1])
						return 2, err
					} else {
						// No value provided or next arg is a flag, treat as count of 1
						*f.Value = 1
						return 1, nil
					}
				}
			case *Int64Flag:
				if len(shorts) > 1 {
					// Multiple occurrences like -nnn
					count := len(shorts)
					*f.Value = int64(count)
					return 1, nil
				}
				// Single occurrence
				if hasValue {
					// Use equals value
					err := c.setInt64Value(f, value)
					return 1, err
				} else {
					// Check if next argument exists and is a valid value. A flag-shaped
					// token isn't one, but a negative number is - "-c -5" means -5, the
					// same as "--count -5".
					if index+1 < len(args) && canBeCountedFlagValue(args[index+1], numberShortsMode) {
						// Next arg is a value, try to parse it
						err := c.setInt64Value(f, args[index+1])
						return 2, err
					} else {
						// No value provided or next arg is a flag, treat as count of 1
						*f.Value = 1
						return 1, nil
					}
				}
			case *StringFlag:
				if hasValue {
					// Use equals value
					err := c.setStringValue(f, value)
					return 1, err
				} else {
					// Use next argument
					if index+1 >= len(args) {
						return 0, fmt.Errorf("flag -%s requires a value", shorts)
					}
					if err := c.checkFlagValue(args, args[index+1], "-"+shorts, false, numberShortsMode); err != nil {
						return 0, err
					}
					err := c.setStringValue(f, args[index+1])
					return 2, err
				}
			}
		}
	}

	// Handle equals syntax for short flags (e.g., -r=value or -fr=value)
	if hasValue {
		// For single short flag with equals, handle directly
		if len(shorts) == 1 {
			shortStr := string(shorts[0])
			flagName, exists := c.shortToName[shortStr]
			if !exists {
				return 0, fmt.Errorf("unknown shorthand flag: -%s", shortStr)
			}

			flag := c.flags[flagName]
			c.configured[flagName] = true

			switch f := flag.(type) {
			case *BoolFlag:
				val, err := c.parseBoolValue(value)
				if err != nil {
					return 0, fmt.Errorf("invalid value for flag -%s: %s", shortStr, err.Error())
				}
				*f.Value = val
				return 1, nil
			case *StringFlag:
				err := c.setStringValue(f, value)
				return 1, err
			case *IntFlag:
				err := c.setIntValue(f, value)
				return 1, err
			case *Int64Flag:
				err := c.setInt64Value(f, value)
				return 1, err
			case *Float64Flag:
				err := c.setFloat64Value(f, value)
				return 1, err
			case *StringSliceFlag:
				_, err := c.appendStringSliceValue(f, value)
				return 1, err
			case *IntSliceFlag:
				_, err := c.appendIntSliceValue(f, value)
				return 1, err
			case *Int64SliceFlag:
				_, err := c.appendInt64SliceValue(f, value)
				return 1, err
			case *Float64SliceFlag:
				_, err := c.appendFloat64SliceValue(f, value)
				return 1, err
			case *BoolSliceFlag:
				_, err := c.appendBoolSliceValue(f, value)
				return 1, err
			}

			return 0, NewProgrammingError(fmt.Sprintf("unsupported flag type for: %s", flagName))
		}
		// For clustered flags with equals (e.g., -fr=value), fall through to regular clustering
		// but the equals value will be used by the last flag in the cluster
	}

	// Regular short flag processing
	consumed := 1

	// Check if all chars are the same (for int flag counting)
	if len(shorts) > 1 {
		firstChar := shorts[0]
		allSame := true
		for i := 1; i < len(shorts); i++ {
			if shorts[i] != firstChar {
				allSame = false
				break
			}
		}
		if allSame {
			// All chars are the same, check if it's an int or int64 flag
			if flagName, exists := c.shortToName[string(firstChar)]; exists {
				if flag, exists := c.flags[flagName]; exists {
					if intFlag, ok := flag.(*IntFlag); ok {
						c.configured[flagName] = true
						if hasValue {
							// Explicit equals value takes precedence over counting
							err := c.setIntValue(intFlag, value)
							return 1, err
						} else {
							// This is an int flag being repeated, set it to the count
							*intFlag.Value = len(shorts)
							return 1, nil
						}
					}
					if int64Flag, ok := flag.(*Int64Flag); ok {
						c.configured[flagName] = true
						if hasValue {
							// Explicit equals value takes precedence over counting
							err := c.setInt64Value(int64Flag, value)
							return 1, err
						} else {
							// This is an int64 flag being repeated, set it to the count
							*int64Flag.Value = int64(len(shorts))
							return 1, nil
						}
					}
				}
			}
		}
	}

	for i, short := range shorts {
		shortStr := string(short)
		flagName, exists := c.shortToName[shortStr]
		if !exists {
			return 0, fmt.Errorf("unknown shorthand flag: '%s' in -%s", shortStr, shortStr)
		}

		flag := c.flags[flagName]
		c.configured[flagName] = true

		switch f := flag.(type) {
		case *BoolFlag:
			*f.Value = true
		case *StringFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					err := c.setStringValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use next argument
					if index+1 >= len(args) {
						return 0, fmt.Errorf("flag -%s requires a value", shortStr)
					}
					if err := c.checkFlagValue(args, args[index+1], "-"+shortStr, false, numberShortsMode); err != nil {
						return 0, err
					}
					err := c.setStringValue(f, args[index+1])
					if err != nil {
						return 0, err
					}
					consumed = 2
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *IntFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					err := c.setIntValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Check if next argument exists and is a valid value. A flag-shaped
					// token isn't one, but a negative number is - "-c -5" means -5, the
					// same as "--count -5".
					if index+1 < len(args) && canBeCountedFlagValue(args[index+1], numberShortsMode) {
						// Next arg is a value, try to parse it
						err := c.setIntValue(f, args[index+1])
						if err != nil {
							return 0, err
						}
						consumed = 2
					} else {
						// No value provided or next arg is a flag, treat as count of 1
						*f.Value = 1
						consumed = 1
					}
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *StringSliceFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					_, err := c.appendStringSliceValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use parseSliceFlag for next argument(s)
					consumed, err := c.parseSliceFlag(args, index, f, "-"+shortStr, numberShortsMode, cfg)
					if err != nil {
						return 0, err
					}
					return consumed, nil
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *Int64Flag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					err := c.setInt64Value(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Check if next argument exists and is a valid value. A flag-shaped
					// token isn't one, but a negative number is - "-c -5" means -5, the
					// same as "--count -5".
					if index+1 < len(args) && canBeCountedFlagValue(args[index+1], numberShortsMode) {
						// Next arg is a value, try to parse it
						err := c.setInt64Value(f, args[index+1])
						if err != nil {
							return 0, err
						}
						consumed = 2
					} else {
						// No value provided or next arg is a flag, treat as count of 1
						*f.Value = 1
						consumed = 1
					}
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *Float64Flag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					err := c.setFloat64Value(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use next argument
					if index+1 >= len(args) {
						return 0, fmt.Errorf("flag -%s requires a value", shortStr)
					}
					if err := c.checkFlagValue(args, args[index+1], "-"+shortStr, true, numberShortsMode); err != nil {
						return 0, err
					}
					err := c.setFloat64Value(f, args[index+1])
					if err != nil {
						return 0, err
					}
					consumed = 2
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *IntSliceFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					_, err := c.appendIntSliceValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use parseIntSliceFlag for next argument(s)
					consumed, err := c.parseIntSliceFlag(args, index, f, "-"+shortStr, numberShortsMode)
					if err != nil {
						return 0, err
					}
					return consumed, nil
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *Int64SliceFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					_, err := c.appendInt64SliceValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use parseInt64SliceFlag for next argument(s)
					consumed, err := c.parseInt64SliceFlag(args, index, f, "-"+shortStr, numberShortsMode)
					if err != nil {
						return 0, err
					}
					return consumed, nil
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *Float64SliceFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					_, err := c.appendFloat64SliceValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use parseFloat64SliceFlag for next argument(s)
					consumed, err := c.parseFloat64SliceFlag(args, index, f, "-"+shortStr, numberShortsMode)
					if err != nil {
						return 0, err
					}
					return consumed, nil
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		case *BoolSliceFlag:
			if i == len(shorts)-1 {
				// Last flag in cluster, can take value
				if hasValue {
					// Use equals value
					_, err := c.appendBoolSliceValue(f, value)
					if err != nil {
						return 0, err
					}
					consumed = 1
				} else {
					// Use parseBoolSliceFlag for next argument(s)
					consumed, err := c.parseBoolSliceFlag(args, index, f, "-"+shortStr, numberShortsMode)
					if err != nil {
						return 0, err
					}
					return consumed, nil
				}
			} else {
				return 0, fmt.Errorf("non-bool flag -%s must be last in cluster", shortStr)
			}
		}
	}

	return consumed, nil
}

// positionalSource is why a token is being offered to the positional slots. It
// decides which slots may take it: a plain list declines flag-shaped tokens, and
// only "--" reopens a collector that a flag already closed.
type positionalSource int

const (
	posBare             positionalSource = iota // an ordinary bare token
	posAfterDashDash                            // everything after "--"
	posUnknownFlagToken                         // a flag-shaped token offered to variadics
)

func (c *Cmd) assignPositional(value string) error {
	return c.assignPositionalWithMode(value, posBare)
}

func (c *Cmd) assignPositionalWithMode(value string, src positionalSource) error {
	// Find next unassigned positional flag
	for _, name := range c.positional {
		flag := c.flags[name]

		// Check if it's positional-only or can be positional
		switch f := flag.(type) {
		case *StringFlag:
			if f.FlagOnly {
				continue
			}
			if c.configured[name] {
				continue // Already assigned
			}
			c.configured[name] = true
			return c.setStringValue(f, value)
		case *IntFlag:
			if f.FlagOnly {
				continue
			}
			if c.configured[name] {
				continue // Already assigned
			}
			c.configured[name] = true
			return c.setIntValue(f, value)
		case *Int64Flag:
			if f.FlagOnly {
				continue
			}
			if c.configured[name] {
				continue // Already assigned
			}
			c.configured[name] = true
			return c.setInt64Value(f, value)
		case *Float64Flag:
			if f.FlagOnly {
				continue
			}
			if c.configured[name] {
				continue // Already assigned
			}
			c.configured[name] = true
			return c.setFloat64Value(f, value)
		case *BoolFlag:
			if f.FlagOnly {
				continue
			}
			if c.configured[name] {
				continue // Already assigned
			}
			c.configured[name] = true
			val, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid bool value for %s: %s", name, value)
			}
			*f.Value = val
			return nil
		case *StringSliceFlag:
			if f.FlagOnly {
				continue
			}
			if src == posUnknownFlagToken && !f.Variadic {
				continue // Only a variadic captures flag-shaped tokens
			}
			handled, err := c.collectPositionalIntoSlice(name, src, func() error {
				_, err := c.appendStringSliceValue(f, value)
				return err
			})
			if handled {
				return err
			}
			continue // This collector is closed; try the next positional
		case *IntSliceFlag:
			if f.FlagOnly {
				continue
			}
			if src == posUnknownFlagToken && !f.Variadic {
				continue // Only a variadic captures flag-shaped tokens
			}
			handled, err := c.collectPositionalIntoSlice(name, src, func() error {
				_, err := c.appendIntSliceValue(f, value)
				return err
			})
			if handled {
				return err
			}
			continue // This collector is closed; try the next positional
		case *Int64SliceFlag:
			if f.FlagOnly {
				continue
			}
			if src == posUnknownFlagToken && !f.Variadic {
				continue // Only a variadic captures flag-shaped tokens
			}
			handled, err := c.collectPositionalIntoSlice(name, src, func() error {
				_, err := c.appendInt64SliceValue(f, value)
				return err
			})
			if handled {
				return err
			}
			continue // This collector is closed; try the next positional
		case *Float64SliceFlag:
			if f.FlagOnly {
				continue
			}
			if src == posUnknownFlagToken && !f.Variadic {
				continue // Only a variadic captures flag-shaped tokens
			}
			handled, err := c.collectPositionalIntoSlice(name, src, func() error {
				_, err := c.appendFloat64SliceValue(f, value)
				return err
			})
			if handled {
				return err
			}
			continue // This collector is closed; try the next positional
		case *BoolSliceFlag:
			if f.FlagOnly {
				continue
			}
			if src == posUnknownFlagToken && !f.Variadic {
				continue // Only a variadic captures flag-shaped tokens
			}
			handled, err := c.collectPositionalIntoSlice(name, src, func() error {
				_, err := c.appendBoolSliceValue(f, value)
				return err
			})
			if handled {
				return err
			}
			continue // This collector is closed; try the next positional
		}
	}

	return &TooManyPositionalArgsError{Unused: []string{value}}
}

// collectPositionalIntoSlice offers a bare positional value to a slice flag,
// reporting whether that flag took it. Collection is greedy but does not resume:
// the run continues while this flag stays the active collector, and any flag
// token ends it for good, which is what lets several collectors divide up one
// argv. Applies to plain lists and variadics alike - they differ on the flag
// side, not here.
func (c *Cmd) collectPositionalIntoSlice(
	name string,
	src positionalSource,
	appendFunc func() error,
) (bool, error) {
	// The active collector keeps taking values.
	if c.collectingSlice == name {
		c.configured[name] = true
		return true, appendFunc()
	}
	// "--" reopens a collector that a flag closed.
	if src == posAfterDashDash && c.configured[name] {
		return true, appendFunc()
	}
	// A flag has closed this one since it last collected; it does not resume.
	if c.sawFlag && c.configured[name] {
		return false, nil
	}
	// Otherwise a collector that hasn't run yet may open.
	if !c.sawFlag || c.collectingSlice == "" {
		c.configured[name] = true
		c.collectingSlice = name
		return true, appendFunc()
	}
	return false, nil
}

func (c *Cmd) setStringValue(f *StringFlag, value string) error {
	if f.EnumConstraint != nil {
		valid := false
		for _, allowed := range *f.EnumConstraint {
			if value == allowed {
				valid = true
				break
			}
		}
		if !valid {
			return fmt.Errorf(
				"Invalid '%s' value: %s (valid values: %s)",
				f.Name,
				value,
				strings.Join(*f.EnumConstraint, ", "),
			)
		}
	}

	if f.RegexConstraint != nil {
		if !f.RegexConstraint.MatchString(value) {
			return fmt.Errorf(
				"Invalid '%s' value: %s (must match regex: %s)",
				f.Name,
				value,
				f.RegexConstraint.String(),
			)
		}
	}

	*f.Value = value
	return nil
}

func (c *Cmd) setIntValue(f *IntFlag, value string) error {
	// Parse as int64 first to detect overflow
	val64, err := strconv.ParseInt(value, 10, 64)
	if err != nil {
		return fmt.Errorf("invalid integer value for %s: %s", f.Name, value)
	}

	// Check for platform-specific int overflow
	if val64 < int64(int(^uint(0)>>1)*-1-1) || val64 > int64(int(^uint(0)>>1)) {
		return fmt.Errorf("integer overflow for %s: %s (value exceeds platform int range)", f.Name, value)
	}

	val := int(val64)

	if f.min != nil {
		inclusive := f.minInclusive == nil || *f.minInclusive // default to inclusive
		if (inclusive && val < *f.min) || (!inclusive && val <= *f.min) {
			if inclusive {
				return fmt.Errorf("'%s' value %d is < minimum %d", f.Name, val, *f.min)
			} else {
				return fmt.Errorf("'%s' value %d is <= minimum (exclusive) %d", f.Name, val, *f.min)
			}
		}
	}

	if f.max != nil {
		inclusive := f.maxInclusive == nil || *f.maxInclusive // default to inclusive
		if (inclusive && val > *f.max) || (!inclusive && val >= *f.max) {
			if inclusive {
				return fmt.Errorf("'%s' value %d is > maximum %d", f.Name, val, *f.max)
			} else {
				return fmt.Errorf("'%s' value %d is >= maximum (exclusive) %d", f.Name, val, *f.max)
			}
		}
	}

	*f.Value = val
	return nil
}

func (c *Cmd) setInt64Value(f *Int64Flag, value string) error {
	val, err := strconv.ParseInt(value, 10, 64)
	if err != nil {
		return fmt.Errorf("invalid int64 value for %s: %s", f.Name, value)
	}

	if f.min != nil {
		inclusive := f.minInclusive == nil || *f.minInclusive // default to inclusive
		if (inclusive && val < *f.min) || (!inclusive && val <= *f.min) {
			if inclusive {
				return fmt.Errorf("'%s' value %d is < minimum %d", f.Name, val, *f.min)
			} else {
				return fmt.Errorf("'%s' value %d is <= minimum (exclusive) %d", f.Name, val, *f.min)
			}
		}
	}

	if f.max != nil {
		inclusive := f.maxInclusive == nil || *f.maxInclusive // default to inclusive
		if (inclusive && val > *f.max) || (!inclusive && val >= *f.max) {
			if inclusive {
				return fmt.Errorf("'%s' value %d is > maximum %d", f.Name, val, *f.max)
			} else {
				return fmt.Errorf("'%s' value %d is >= maximum (exclusive) %d", f.Name, val, *f.max)
			}
		}
	}

	*f.Value = val
	return nil
}

func (c *Cmd) setFloat64Value(f *Float64Flag, value string) error {
	val, err := strconv.ParseFloat(value, 64)
	if err != nil {
		return fmt.Errorf("invalid float64 value for %s: %s", f.Name, value)
	}

	if f.min != nil {
		inclusive := f.minInclusive == nil || *f.minInclusive // default to inclusive
		if (inclusive && val < *f.min) || (!inclusive && val <= *f.min) {
			if inclusive {
				return fmt.Errorf("'%s' value %g is < minimum %g", f.Name, val, *f.min)
			} else {
				return fmt.Errorf("'%s' value %g is <= minimum (exclusive) %g", f.Name, val, *f.min)
			}
		}
	}

	if f.max != nil {
		inclusive := f.maxInclusive == nil || *f.maxInclusive // default to inclusive
		if (inclusive && val > *f.max) || (!inclusive && val >= *f.max) {
			if inclusive {
				return fmt.Errorf("'%s' value %g is > maximum %g", f.Name, val, *f.max)
			} else {
				return fmt.Errorf("'%s' value %g is >= maximum (exclusive) %g", f.Name, val, *f.max)
			}
		}
	}

	*f.Value = val
	return nil
}

// parseBoolValue parses a string value as a boolean, supporting standard formats and 0/1
func (c *Cmd) parseBoolValue(value string) (bool, error) {
	val, err := strconv.ParseBool(value)
	if err != nil {
		// Try parsing as 0/1
		if value == "0" {
			return false, nil
		} else if value == "1" {
			return true, nil
		}
		return false, err
	}
	return val, nil
}

func (c *Cmd) parseSliceFlag(
	args []string,
	index int,
	f *StringSliceFlag,
	flagToken string,
	numberShortsMode bool,
	cfg *parseCfg,
) (int, error) {
	if !f.Variadic {
		// Single value. A non-variadic list is required unless it has a
		// default, so accepting a bare flag as an empty slice let it
		// satisfy that requirement with nothing - and where a default
		// existed, did nothing at all. Variadic flags are inherently
		// optional and keep collecting zero values happily.
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag %s requires a value", flagToken)
		}
		if err := c.checkFlagValue(args, args[index+1], flagToken, false, numberShortsMode); err != nil {
			return 0, err
		}
		return c.appendStringSliceValue(f, args[index+1])
	}

	// Variadic - consume until next flag
	consumed := 1
	for i := index + 1; i < len(args); i++ {
		arg := args[i]
		if strings.HasPrefix(arg, "-") {
			// An unknown flag-looking token can be collected as a value; a known
			// flag ends the collection. The check must be side-effect free:
			// actually parsing the candidate here (as this once did) executed
			// every later flag in the argv once per probe, duplicating slice
			// flag values.
			if cfg.variadicUnknownFlags && !c.wouldParseAsFlag(arg) {
				if _, err := c.appendStringSliceValue(f, arg); err != nil {
					return 0, err
				}
				consumed++
				continue
			}
			// Known flag or not collecting unknown flags - stop variadic collection
			break
		}
		if _, err := c.appendStringSliceValue(f, args[i]); err != nil {
			return 0, err
		}
		consumed++
	}

	return consumed, nil
}

// isNegativeNumberToken reports whether a "-"-prefixed token reads as a
// negative number (-5, -.5, -3.2) rather than a flag, using the same leading
// digit/dot test as parseShortFlag's negative-number detection.
func isNegativeNumberToken(arg string) bool {
	return len(arg) > 1 && (isDigit(arg[1]) || arg[1] == '.')
}

// isNegativeNumberValue reports whether a token should be read as a negative
// number rather than a flag. Never in number-shorts mode, where a leading digit
// is precisely what makes something a flag.
func isNegativeNumberValue(arg string, numberShortsMode bool) bool {
	return !numberShortsMode && isNegativeNumberToken(arg)
}

// canBeFlagValue reports whether a token may be consumed as the value of the
// flag that precedes it. A "-"-prefixed token is a flag, not a value: taking it
// silently turns a mistyped flag into data. Two exceptions - a bare "-" is the
// stdin/stdout convention, and a number-typed flag can take a negative number.
// Say you meant a flag-shaped value literally with the "=" form.
func canBeFlagValue(arg string, numeric, numberShortsMode bool) bool {
	if !strings.HasPrefix(arg, "-") || arg == "-" {
		return true
	}
	return numeric && isNegativeNumberValue(arg, numberShortsMode)
}

// flagValueLooksLikeFlagErr builds the rejection for canBeFlagValue. flagToken
// is the token the user actually typed ("--name", "-n"), not the flag's name: a
// name-shadowed global is stored under its short key, so the flag name would
// suggest an "=" form that resolves to a different flag.
func flagValueLooksLikeFlagErr(flagToken, arg string) error {
	return fmt.Errorf(
		"flag %s requires a value, but %q looks like a flag; use %s=%s if you meant it as a value",
		flagToken, arg, flagToken, arg,
	)
}

// canBeCountedFlagValue is canBeFlagValue for the short int/int64 flags that
// double as counters (-vvv). It drops the bare-"-" carve-out: "-c -" has always
// meant "count of 1", and parsing "-" as an integer would only ever error.
// These flags never reject - a flag-shaped token just falls back to counting.
func canBeCountedFlagValue(arg string, numberShortsMode bool) bool {
	return !strings.HasPrefix(arg, "-") || isNegativeNumberValue(arg, numberShortsMode)
}

// checkFlagValue guards a token about to be consumed as flagToken's value.
// Help keeps winning over the rejection: "--name --help" has always shown help
// rather than complaining about --name, and users rely on it.
func (c *Cmd) checkFlagValue(args []string, arg, flagToken string, numeric, numberShortsMode bool) error {
	if canBeFlagValue(arg, numeric, numberShortsMode) {
		return nil
	}
	if c.helpEnabled && c.hasHelpFlags(args) {
		return c.createHelpError(args)
	}
	return flagValueLooksLikeFlagErr(flagToken, arg)
}

// wouldParseAsFlag reports whether parseFlag would resolve the "-"-prefixed
// token against the registered flags, without performing the parse (and its
// side effects). Mirrors parseFlag's resolution outside number-shorts mode.
func (c *Cmd) wouldParseAsFlag(arg string) bool {
	if strings.HasPrefix(arg, "--") {
		name := arg[2:]
		if idx := strings.Index(name, "="); idx != -1 {
			name = name[:idx]
		}
		_, ok := c.flags[name]
		return ok
	}
	shorts := arg[1:]
	if idx := strings.Index(shorts, "="); idx != -1 {
		shorts = shorts[:idx]
	}
	if shorts == "" {
		// Bare "-": parseShortFlag treats it as an empty cluster and succeeds.
		return true
	}
	if isDigit(shorts[0]) || shorts[0] == '.' {
		// Negative number: parseFlag rejects these outside number-shorts mode.
		return false
	}
	// A cluster resolves only if every short is registered; parseShortFlag
	// errors on the first unknown one.
	for _, r := range shorts {
		if _, ok := c.shortToName[string(r)]; !ok {
			return false
		}
	}
	return true
}

func (c *Cmd) appendStringSliceValue(f *StringSliceFlag, value string) (int, error) {
	// Check if this is the first user-provided value and we should replace defaults
	shouldReplace := false
	if f.Default != nil {
		// Check if current value equals the default value - if so, this is the first user input
		if len(*f.Value) == len(*f.Default) {
			equal := true
			for i, v := range *f.Value {
				if v != (*f.Default)[i] {
					equal = false
					break
				}
			}
			if equal {
				shouldReplace = true
			}
		}
	}

	if f.Separator != nil {
		parts := strings.Split(value, *f.Separator)
		if shouldReplace {
			*f.Value = make([]string, 0, len(parts))
		}
		for _, part := range parts {
			// Each part, not the raw token: with a separator one argv entry
			// carries several elements, and the constraint is per element.
			if err := f.checkStringElement(part); err != nil {
				return 0, err
			}
			*f.Value = append(*f.Value, part)
		}
	} else {
		if shouldReplace {
			*f.Value = make([]string, 0, 1)
		}
		if err := f.checkStringElement(value); err != nil {
			return 0, err
		}
		*f.Value = append(*f.Value, value)
	}
	return 2, nil
}

func (c *Cmd) parseIntSliceFlag(
	args []string,
	index int,
	f *IntSliceFlag,
	flagToken string,
	numberShortsMode bool,
) (int, error) {
	if !f.Variadic {
		// Single value (see parseSliceFlag on why a bare flag errors).
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag %s requires a value", flagToken)
		}
		if err := c.checkFlagValue(args, args[index+1], flagToken, true, numberShortsMode); err != nil {
			return 0, err
		}
		return c.appendIntSliceValue(f, args[index+1])
	}

	// Variadic - consume until next flag. Negative numbers are values, not
	// flags (parseFlag treats them as positionals outside number-shorts mode),
	// so greedy collection must consume them too.
	consumed := 1
	for i := index + 1; i < len(args); i++ {
		if strings.HasPrefix(args[i], "-") && !isNegativeNumberValue(args[i], numberShortsMode) {
			break
		}
		if _, err := c.appendIntSliceValue(f, args[i]); err != nil {
			return 0, err
		}
		consumed++
	}

	return consumed, nil
}

func (c *Cmd) appendIntSliceValue(f *IntSliceFlag, value string) (int, error) {
	// Check if this is the first user-provided value and we should replace defaults
	shouldReplace := false
	if f.Default != nil {
		// Check if current value equals the default value - if so, this is the first user input
		if len(*f.Value) == len(*f.Default) {
			equal := true
			for i, v := range *f.Value {
				if v != (*f.Default)[i] {
					equal = false
					break
				}
			}
			if equal {
				shouldReplace = true
			}
		}
	}

	if f.Separator != nil {
		parts := strings.Split(value, *f.Separator)
		if shouldReplace {
			*f.Value = make([]int, 0, len(parts))
		}
		for _, part := range parts {
			val, err := strconv.Atoi(part)
			if err != nil {
				return 0, fmt.Errorf("invalid integer value for %s: %s", f.Name, part)
			}
			if err := f.checkNumberElement(float64(val), part); err != nil {
				return 0, err
			}
			*f.Value = append(*f.Value, val)
		}
	} else {
		if shouldReplace {
			*f.Value = make([]int, 0, 1)
		}
		val, err := strconv.Atoi(value)
		if err != nil {
			return 0, fmt.Errorf("invalid integer value for %s: %s", f.Name, value)
		}
		if err := f.checkNumberElement(float64(val), value); err != nil {
			return 0, err
		}
		*f.Value = append(*f.Value, val)
	}
	return 2, nil
}

func (c *Cmd) parseInt64SliceFlag(
	args []string,
	index int,
	f *Int64SliceFlag,
	flagToken string,
	numberShortsMode bool,
) (int, error) {
	if !f.Variadic {
		// Single value (see parseSliceFlag on why a bare flag errors).
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag %s requires a value", flagToken)
		}
		if err := c.checkFlagValue(args, args[index+1], flagToken, true, numberShortsMode); err != nil {
			return 0, err
		}
		return c.appendInt64SliceValue(f, args[index+1])
	}

	// Variadic - consume until next flag; negative numbers are values (see
	// parseIntSliceFlag).
	consumed := 1
	for i := index + 1; i < len(args); i++ {
		if strings.HasPrefix(args[i], "-") && !isNegativeNumberValue(args[i], numberShortsMode) {
			break
		}
		if _, err := c.appendInt64SliceValue(f, args[i]); err != nil {
			return 0, err
		}
		consumed++
	}

	return consumed, nil
}

func (c *Cmd) appendInt64SliceValue(f *Int64SliceFlag, value string) (int, error) {
	// Check if this is the first user-provided value and we should replace defaults
	shouldReplace := false
	if f.Default != nil {
		// Check if current value equals the default value - if so, this is the first user input
		if len(*f.Value) == len(*f.Default) {
			equal := true
			for i, v := range *f.Value {
				if v != (*f.Default)[i] {
					equal = false
					break
				}
			}
			if equal {
				shouldReplace = true
			}
		}
	}

	if f.Separator != nil {
		parts := strings.Split(value, *f.Separator)
		if shouldReplace {
			*f.Value = make([]int64, 0, len(parts))
		}
		for _, part := range parts {
			val, err := strconv.ParseInt(part, 10, 64)
			if err != nil {
				return 0, fmt.Errorf("invalid int64 value for %s: %s", f.Name, part)
			}
			if err := f.checkNumberElement(float64(val), part); err != nil {
				return 0, err
			}
			*f.Value = append(*f.Value, val)
		}
	} else {
		if shouldReplace {
			*f.Value = make([]int64, 0, 1)
		}
		val, err := strconv.ParseInt(value, 10, 64)
		if err != nil {
			return 0, fmt.Errorf("invalid int64 value for %s: %s", f.Name, value)
		}
		if err := f.checkNumberElement(float64(val), value); err != nil {
			return 0, err
		}
		*f.Value = append(*f.Value, val)
	}
	return 2, nil
}

func (c *Cmd) parseFloat64SliceFlag(
	args []string,
	index int,
	f *Float64SliceFlag,
	flagToken string,
	numberShortsMode bool,
) (int, error) {
	if !f.Variadic {
		// Single value (see parseSliceFlag on why a bare flag errors).
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag %s requires a value", flagToken)
		}
		if err := c.checkFlagValue(args, args[index+1], flagToken, true, numberShortsMode); err != nil {
			return 0, err
		}
		return c.appendFloat64SliceValue(f, args[index+1])
	}

	// Variadic - consume until next flag; negative numbers are values (see
	// parseIntSliceFlag).
	consumed := 1
	for i := index + 1; i < len(args); i++ {
		if strings.HasPrefix(args[i], "-") && !isNegativeNumberValue(args[i], numberShortsMode) {
			break
		}
		if _, err := c.appendFloat64SliceValue(f, args[i]); err != nil {
			return 0, err
		}
		consumed++
	}

	return consumed, nil
}

func (c *Cmd) appendFloat64SliceValue(f *Float64SliceFlag, value string) (int, error) {
	// Check if this is the first user-provided value and we should replace defaults
	shouldReplace := false
	if f.Default != nil {
		// Check if current value equals the default value - if so, this is the first user input
		if len(*f.Value) == len(*f.Default) {
			equal := true
			for i, v := range *f.Value {
				if v != (*f.Default)[i] {
					equal = false
					break
				}
			}
			if equal {
				shouldReplace = true
			}
		}
	}

	if f.Separator != nil {
		parts := strings.Split(value, *f.Separator)
		if shouldReplace {
			*f.Value = make([]float64, 0, len(parts))
		}
		for _, part := range parts {
			val, err := strconv.ParseFloat(part, 64)
			if err != nil {
				return 0, fmt.Errorf("invalid float64 value for %s: %s", f.Name, part)
			}
			if err := f.checkNumberElement(val, part); err != nil {
				return 0, err
			}
			*f.Value = append(*f.Value, val)
		}
	} else {
		if shouldReplace {
			*f.Value = make([]float64, 0, 1)
		}
		val, err := strconv.ParseFloat(value, 64)
		if err != nil {
			return 0, fmt.Errorf("invalid float64 value for %s: %s", f.Name, value)
		}
		if err := f.checkNumberElement(val, value); err != nil {
			return 0, err
		}
		*f.Value = append(*f.Value, val)
	}
	return 2, nil
}

func (c *Cmd) parseBoolSliceFlag(
	args []string,
	index int,
	f *BoolSliceFlag,
	flagToken string,
	numberShortsMode bool,
) (int, error) {
	if !f.Variadic {
		// Single value (see parseSliceFlag on why a bare flag errors).
		if index+1 >= len(args) {
			return 0, fmt.Errorf("flag %s requires a value", flagToken)
		}
		if err := c.checkFlagValue(args, args[index+1], flagToken, false, numberShortsMode); err != nil {
			return 0, err
		}
		return c.appendBoolSliceValue(f, args[index+1])
	}

	// Variadic - consume until next flag. Unlike the numeric slice parsers,
	// any "-"-prefixed token ends the collection: no valid bool value starts
	// with "-", so such a token can only be a flag or a positional.
	consumed := 1
	for i := index + 1; i < len(args); i++ {
		if strings.HasPrefix(args[i], "-") {
			break
		}
		if _, err := c.appendBoolSliceValue(f, args[i]); err != nil {
			return 0, err
		}
		consumed++
	}

	return consumed, nil
}

func (c *Cmd) appendBoolSliceValue(f *BoolSliceFlag, value string) (int, error) {
	// Check if this is the first user-provided value and we should replace defaults
	shouldReplace := false
	if f.Default != nil {
		// Check if current value equals the default value - if so, this is the first user input
		if len(*f.Value) == len(*f.Default) {
			equal := true
			for i, v := range *f.Value {
				if v != (*f.Default)[i] {
					equal = false
					break
				}
			}
			if equal {
				shouldReplace = true
			}
		}
	}

	if f.Separator != nil {
		parts := strings.Split(value, *f.Separator)
		if shouldReplace {
			*f.Value = make([]bool, 0, len(parts))
		}
		for _, part := range parts {
			val, err := strconv.ParseBool(part)
			if err != nil {
				// Try parsing as 0/1
				if part == "0" {
					val = false
				} else if part == "1" {
					val = true
				} else {
					return 0, fmt.Errorf("invalid bool value for %s: %s", f.Name, part)
				}
			}
			*f.Value = append(*f.Value, val)
		}
	} else {
		if shouldReplace {
			*f.Value = make([]bool, 0, 1)
		}
		val, err := strconv.ParseBool(value)
		if err != nil {
			// Try parsing as 0/1
			if value == "0" {
				val = false
			} else if value == "1" {
				val = true
			} else {
				return 0, fmt.Errorf("invalid bool value for %s: %s", f.Name, value)
			}
		}
		*f.Value = append(*f.Value, val)
	}
	return 2, nil
}

// getAllFlagsInRegistrationOrder returns all flag names in registration order
// (positional flags first, then non-positional flags)
func (c *Cmd) getAllFlagsInRegistrationOrder() []string {
	allFlags := make([]string, 0, len(c.positional)+len(c.nonPositional))
	allFlags = append(allFlags, c.positional...)
	allFlags = append(allFlags, c.nonPositional...)
	return allFlags
}

func initializeColorFromEnv() {
	colorValue := strings.ToLower(strings.TrimSpace(os.Getenv("RA_COLOR")))
	switch colorValue {
	case "never":
		color.NoColor = true
	case "always":
		color.NoColor = false
	case "", "auto":
		// default behavior
		// let amterp/color decide based on tty
	default:
		// invalid value - treat as auto
	}
}

func (c *Cmd) validateBeforeParsing() error {
	// Validate that all constraint references point to real arg names
	return c.validateConstraintReferences()
}

func (c *Cmd) validateConstraintReferences() error {
	// Get all valid flag names
	validFlags := make(map[string]bool)
	for name := range c.flags {
		validFlags[name] = true
	}

	// Check all requires/excludes constraints
	for _, flag := range c.flags {
		var requires *[]string
		var excludes *[]string

		switch f := flag.(type) {
		case *StringFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *IntFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *Int64Flag:
			requires = f.Requires
			excludes = f.Excludes
		case *Float64Flag:
			requires = f.Requires
			excludes = f.Excludes
		case *BoolFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *StringSliceFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *IntSliceFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *Int64SliceFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *Float64SliceFlag:
			requires = f.Requires
			excludes = f.Excludes
		case *BoolSliceFlag:
			requires = f.Requires
			excludes = f.Excludes
		}

		// Validate requires constraints
		if requires != nil {
			for _, reqName := range *requires {
				if !validFlags[reqName] {
					return NewProgrammingError(fmt.Sprintf("Undefined flag '%s'", reqName))
				}
			}
		}

		// Validate excludes constraints
		if excludes != nil {
			for _, excName := range *excludes {
				if !validFlags[excName] {
					return NewProgrammingError(fmt.Sprintf("Undefined flag '%s'", excName))
				}
			}
		}
	}

	return nil
}

func (c *Cmd) validateRequired() error {
	// A configured bypass-validation flag (e.g. --version style flags) skips
	// validation entirely - including the relational constraint pass below,
	// which previously still ran because this check sat between the passes.
	if c.hasConfiguredBypassFlag() {
		return nil
	}

	// First pass: Check relational constraints (requires/excludes)
	// These are more specific and should take precedence over generic "required flag missing" errors
	// Iterate in registration order to ensure deterministic error messages
	for _, name := range c.getAllFlagsInRegistrationOrder() {
		flag, exists := c.flags[name]
		if !exists {
			continue
		}

		// Check requires constraints for flags that are configured for relational constraints
		if c.flagConfiguredForRelationalConstraints(name) {
			var requires *[]string
			switch f := flag.(type) {
			case *StringFlag:
				requires = f.Requires
			case *IntFlag:
				requires = f.Requires
			case *BoolFlag:
				requires = f.Requires
			case *Int64Flag:
				requires = f.Requires
			case *Float64Flag:
				requires = f.Requires
			case *SliceFlag[string]:
				requires = f.Requires
			case *SliceFlag[int]:
				requires = f.Requires
			case *SliceFlag[int64]:
				requires = f.Requires
			case *SliceFlag[float64]:
				requires = f.Requires
			case *SliceFlag[bool]:
				requires = f.Requires
			}

			if requires != nil {
				for _, req := range *requires {
					if !c.flagConfiguredForRelationalConstraints(req) {
						return fmt.Errorf("Invalid args: '%s' requires '%s', but '%s' was not set", name, req, req)
					}
				}
			}
		}

		// Check exclusion constraints using the new helper
		if err := c.checkExclusion(name); err != nil {
			return err
		}
	}

	// Second pass: Check if required flags are missing
	// This runs after relational constraints so more specific errors take precedence
	// Check in registration order: positional flags first, then non-positional flags
	var missingRequired []string

	// Check positional flags first
	for _, name := range c.positional {
		if c.isFlagRequired(name) && !c.configured[name] && !c.isFlagExcludedByConfiguredFlag(name) {
			missingRequired = append(missingRequired, name)
		}
	}

	// Then check non-positional flags
	for _, name := range c.nonPositional {
		if c.isFlagRequired(name) && !c.configured[name] && !c.isFlagExcludedByConfiguredFlag(name) {
			missingRequired = append(missingRequired, name)
		}
	}

	if len(missingRequired) > 0 {
		return fmt.Errorf("Missing required arguments: [%s]", strings.Join(missingRequired, ", "))
	}

	// Third pass: how many values each list arg got. Last, so that "you did not
	// provide it" beats "you provided too few of it".
	return c.validateLengths()
}

// validateLengths checks the element-count constraints on slice flags. Only
// flags the user actually set are checked: an untouched default is the author's
// own choice, and an absent required flag has already been reported above.
func (c *Cmd) validateLengths() error {
	for _, name := range c.getAllFlagsInRegistrationOrder() {
		if !c.configured[name] {
			continue
		}
		flag, exists := c.flags[name]
		if !exists {
			continue
		}

		var err error
		switch f := flag.(type) {
		case *SliceFlag[string]:
			err = f.checkLength()
		case *SliceFlag[int]:
			err = f.checkLength()
		case *SliceFlag[int64]:
			err = f.checkLength()
		case *SliceFlag[float64]:
			err = f.checkLength()
		case *SliceFlag[bool]:
			err = f.checkLength()
		}
		if err != nil {
			return err
		}
	}
	return nil
}
func (c *Cmd) isFlagRequired(name string) bool {
	flag, exists := c.flags[name]
	if !exists {
		return false
	}

	switch f := flag.(type) {
	case *StringFlag:
		return !f.Optional && f.Default == nil
	case *IntFlag:
		return !f.Optional && f.Default == nil
	case *BoolFlag:
		// Boolean flags have implicit default of false, so never required
		return false
	case *Int64Flag:
		return !f.Optional && f.Default == nil
	case *Float64Flag:
		return !f.Optional && f.Default == nil
	case *SliceFlag[string]:
		// Variadic slice flags have implicit default of empty slice, so never required
		return !f.Variadic && !f.Optional && f.Default == nil
	case *SliceFlag[int]:
		// Variadic slice flags have implicit default of empty slice, so never required
		return !f.Variadic && !f.Optional && f.Default == nil
	case *SliceFlag[int64]:
		// Variadic slice flags have implicit default of empty slice, so never required
		return !f.Variadic && !f.Optional && f.Default == nil
	case *SliceFlag[float64]:
		// Variadic slice flags have implicit default of empty slice, so never required
		return !f.Variadic && !f.Optional && f.Default == nil
	case *SliceFlag[bool]:
		// Boolean slice flags have implicit default of empty slice, so never required
		return false
	}
	return false
}

// checkExclusion checks if a flag excludes or is excluded by another flag
func (c *Cmd) checkExclusion(flagName string) error {
	if !c.flagExplicitlySetForExclusion(flagName) {
		return nil
	}

	// Check if this flag excludes any other configured flags
	if flag, exists := c.flags[flagName]; exists {
		var excludes *[]string
		switch f := flag.(type) {
		case *StringFlag:
			excludes = f.Excludes
		case *IntFlag:
			excludes = f.Excludes
		case *BoolFlag:
			excludes = f.Excludes
		case *Int64Flag:
			excludes = f.Excludes
		case *Float64Flag:
			excludes = f.Excludes
		case *SliceFlag[string]:
			excludes = f.Excludes
		case *SliceFlag[int]:
			excludes = f.Excludes
		case *SliceFlag[int64]:
			excludes = f.Excludes
		case *SliceFlag[float64]:
			excludes = f.Excludes
		case *SliceFlag[bool]:
			excludes = f.Excludes
		}

		if excludes != nil {
			for _, excluded := range *excludes {
				if c.flagExplicitlySetForExclusion(excluded) {
					return fmt.Errorf(
						"Invalid args: '%s' excludes '%s', but '%s' was set",
						flagName,
						excluded,
						excluded,
					)
				}
			}
		}
	}

	// Check if any other configured flag excludes this flag
	for _, otherName := range c.getAllFlagsInRegistrationOrder() {
		if otherName == flagName || !c.flagExplicitlySetForExclusion(otherName) {
			continue
		}

		otherFlag, exists := c.flags[otherName]
		if !exists {
			continue
		}

		var otherExcludes *[]string
		switch f := otherFlag.(type) {
		case *StringFlag:
			otherExcludes = f.Excludes
		case *IntFlag:
			otherExcludes = f.Excludes
		case *BoolFlag:
			otherExcludes = f.Excludes
		case *Int64Flag:
			otherExcludes = f.Excludes
		case *Float64Flag:
			otherExcludes = f.Excludes
		case *SliceFlag[string]:
			otherExcludes = f.Excludes
		case *SliceFlag[int]:
			otherExcludes = f.Excludes
		case *SliceFlag[int64]:
			otherExcludes = f.Excludes
		case *SliceFlag[float64]:
			otherExcludes = f.Excludes
		case *SliceFlag[bool]:
			otherExcludes = f.Excludes
		}

		if otherExcludes != nil {
			for _, excluded := range *otherExcludes {
				if excluded == flagName {
					return fmt.Errorf(
						"Invalid args: '%s' excludes '%s', but '%s' was set",
						otherName,
						flagName,
						flagName,
					)
				}
			}
		}
	}

	return nil
}

// hasConfiguredBypassFlag returns true if any user-configured flag is marked
// BypassValidation, meaning this parse skips required/relational validation.
func (c *Cmd) hasConfiguredBypassFlag() bool {
	for name := range c.configured {
		flag, exists := c.flags[name]
		if !exists {
			continue
		}
		switch f := flag.(type) {
		case *BoolFlag:
			if f.BypassValidation {
				return true
			}
		case *StringFlag:
			if f.BypassValidation {
				return true
			}
		case *Int64Flag:
			if f.BypassValidation {
				return true
			}
		case *IntFlag:
			if f.BypassValidation {
				return true
			}
		case *Float64Flag:
			if f.BypassValidation {
				return true
			}
		case *SliceFlag[string]:
			if f.BypassValidation {
				return true
			}
		case *SliceFlag[int]:
			if f.BypassValidation {
				return true
			}
		case *SliceFlag[int64]:
			if f.BypassValidation {
				return true
			}
		case *SliceFlag[float64]:
			if f.BypassValidation {
				return true
			}
		case *SliceFlag[bool]:
			if f.BypassValidation {
				return true
			}
		}
	}
	return false
}

// flagExplicitlySetForExclusion returns true if the flag counts as "set" for
// exclusion constraints: explicitly set by the user (boolean flags: set AND
// true). Unlike requires constraints, a default value does not participate -
// a default expresses the author's fallback, not user intent, so it cannot
// conflict with anything the user actually passed.
func (c *Cmd) flagExplicitlySetForExclusion(name string) bool {
	flag, exists := c.flags[name]
	if !exists || !c.configured[name] {
		return false
	}
	if f, ok := flag.(*BoolFlag); ok {
		return f.Value != nil && *f.Value
	}
	return true
}

// flagConfiguredForRelationalConstraints returns true if the flag should be considered configured
// for the purposes of requires constraints.
// For boolean flags, this only returns true when the flag's value is true.
// For other flag types, this returns true if the flag has a value (configured or default) -
// deliberately, so a defaulted flag both triggers its own requires constraints and satisfies
// others' (see Test_RequiresWithDefaults_Scenario).
func (c *Cmd) flagConfiguredForRelationalConstraints(name string) bool {
	if flag, exists := c.flags[name]; exists {
		switch f := flag.(type) {
		case *BoolFlag:
			// For boolean flags, only consider them configured for relational constraints when true
			if f.Value != nil && *f.Value {
				return true
			}
			return false
		default:
			// For all other flag types, use the normal flagHasValue logic
			return c.flagHasValue(name)
		}
	}
	return false
}

// flagHasValue returns true if the flag has a value (either configured by user or has a default)
func (c *Cmd) flagHasValue(name string) bool {
	// First check if it was explicitly configured
	if c.configured[name] {
		return true
	}

	// Then check if it has a default value
	if flag, exists := c.flags[name]; exists {
		switch f := flag.(type) {
		case *StringFlag:
			return f.Default != nil
		case *IntFlag:
			return f.Default != nil
		case *BoolFlag:
			return f.Default != nil
		case *Int64Flag:
			return f.Default != nil
		case *Float64Flag:
			return f.Default != nil
		case *SliceFlag[string]:
			return f.Default != nil
		case *SliceFlag[int]:
			return f.Default != nil
		case *SliceFlag[int64]:
			return f.Default != nil
		case *SliceFlag[float64]:
			return f.Default != nil
		case *SliceFlag[bool]:
			return f.Default != nil
		}
	}

	return false
}

// isFlagExcludedByConfiguredFlag returns true if the given flag is excluded by any configured flag
func (c *Cmd) isFlagExcludedByConfiguredFlag(flagName string) bool {
	// Check if any configured flag excludes the given flag
	for configuredFlagName, isConfigured := range c.configured {
		if !isConfigured || configuredFlagName == flagName {
			continue
		}

		// Check if this configured flag excludes the target flag
		if flag, exists := c.flags[configuredFlagName]; exists {
			var excludes *[]string
			switch f := flag.(type) {
			case *StringFlag:
				excludes = f.Excludes
			case *IntFlag:
				excludes = f.Excludes
			case *BoolFlag:
				// For boolean flags, only consider exclusion when the flag is true
				if f.Value != nil && *f.Value {
					excludes = f.Excludes
				}
			case *Int64Flag:
				excludes = f.Excludes
			case *Float64Flag:
				excludes = f.Excludes
			case *SliceFlag[string]:
				excludes = f.Excludes
			case *SliceFlag[int]:
				excludes = f.Excludes
			case *SliceFlag[int64]:
				excludes = f.Excludes
			case *SliceFlag[float64]:
				excludes = f.Excludes
			case *SliceFlag[bool]:
				excludes = f.Excludes
			}

			if excludes != nil {
				for _, excluded := range *excludes {
					if excluded == flagName {
						return true
					}
				}
			}
		}
	}
	return false
}

// hasRequiredFlags returns true if the command has any required flags
// defaultRequiresArgs reports whether routing a bare invocation to the default
// sub-command would immediately fail for want of an argument.
func (c *Cmd) defaultRequiresArgs() bool {
	def := c.defaultCmd()
	return def != nil && def.hasRequiredFlags()
}

func (c *Cmd) hasRequiredFlags() bool {
	// Check positional flags first
	for _, name := range c.positional {
		if c.isFlagRequired(name) {
			return true
		}
	}

	// Then check non-positional flags
	for _, name := range c.nonPositional {
		if c.isFlagRequired(name) {
			return true
		}
	}

	return false
}

// hasHelpFlags checks if help flags are present in args
func (c *Cmd) hasHelpFlags(args []string) bool {
	for _, arg := range args {
		if arg == "--help" || arg == "-h" {
			return true
		}
	}
	return false
}

// createHelpError creates a help invoked error, determining if it's long or short help
func (c *Cmd) createHelpError(args []string) error {
	isLongHelp := false
	for _, arg := range args {
		if arg == "--help" {
			isLongHelp = true
			break
		}
	}

	return newHelpInvokedError(
		c,                    // cmd
		0,                    // exitCode
		true,                 // useStdout
		isLongHelp,           // isLongHelp
		false,                // isAutoHelp
		c.customUsage != nil, // useCustomUsage
	)
}