[CLI] Treat value flags followed by another flag as missing values

[cssbruno]

Priority

Medium — CLI usability, safer scripts, and clearer diagnostics.

Context

Most command parsers use the shared helper consumeValueFlag(args, index, name, allowEmptyEquals) in cmd/gowdk/flags.go. When the flag appears as --flag <value>, the helper accepts the next argument unconditionally as the value.

Current behavior by inspection:

if arg == name {
    if index+1 >= len(args) {
        return "", index, true, true
    }
    return args[index+1], index + 1, true, false
}

This means a command such as:

gowdk build --out --app .gowdk/app page.gwdk

can parse --app as the value of --out rather than reporting that --out is missing a value.

Problem

Accepting the next flag-looking token as a value creates confusing and potentially unsafe command behavior.

Consequences:

1. A typo or missing value can shift the rest of the command line.
2. The resulting error may be far from the real mistake.
3. Output paths can accidentally become strings such as --app or --bin.
4. Scripts that expect standard flag parsing behavior become harder to debug.
5. Each command that uses consumeValueFlag inherits the ambiguity.

Proposed direction

Teach value-flag parsing to reject another flag-looking token when the flag requires a value, unless the specific flag explicitly allows dash-prefixed values.

Possible model:

type valueFlagPolicy struct {
    AllowEmptyEquals bool
    AllowDashValue   bool
}

The common default should be AllowDashValue: false for path, config, env-file, module, target, address, and output flags.

Acceptance criteria

• --flag --other reports a missing value for --flag by default.
• --flag=-value remains possible only for flags that explicitly allow dash-prefixed values.
• All commands using consumeValueFlag are audited and assigned a value policy.
• Diagnostics name the specific missing flag.
• Tests cover build, check, serve, audit, test, clean, dev, and preview forwarded flags.
• Documentation examples still parse unchanged.

Non-goals

• Replacing the entire CLI parser in this issue. That is covered by the command-schema work in [CLI] Generate command parsing, help, docs, and completions from one command schema #717.

Related

• [CLI] Generate command parsing, help, docs, and completions from one command schema #717 — generate command parsing, help, docs, and completions from one command schema