cli: let flags be written anywhere on the line

[ale-rinaldi]

Replaces #10, which GitHub closed automatically when its base branch was deleted on merge. Same work, retargeted to main and integrated with everything that landed since.

Answers "can't flags be position-independent?" — yes, everywhere, not just before the subcommand.

What was wrong

dwshell dispatched on os.Args[1], so a flag could only follow its subcommand. The failure mode was not an error:

$ dwshell --config /x list
dwshell: authentication required: run `dwshell login`   # took "list" for a machine name
$ dwshell --json list
flag provided but not defined: -json

The first is the bad one: it did not complain, it quietly did something else.

What it does now

Arguments are partitioned into flags and positionals before anything is dispatched, so the command is the first positional wherever it sits — at the top level and inside both account <verb> and agent <verb>. Everything after a bare -- is positional, so an agent or path starting with a dash can still be passed.

The hazard, and the guard

Telling a flag's value from a positional requires knowing which flags consume a following token, and that registry is the risk: a value flag missing from it makes dwshell take the value for a command name and quietly do the wrong thing.

TestValueFlagsMatchesTheFlagsActuallyRegistered walks the package's own source with go/ast and holds the registry to what is actually registered, in both directions. It has already earned its place three times:

• it rejected two entries added from memory that no command registered;
• it surfaced a pre-existing gap — --user was missing, harmless only because login is dispatched by name;
• during this integration it required --description and --group, the agent flags, which would otherwise have been silently wrong.

Integration with agent management

Merging the two feature branches needed real work, not just conflict resolution:

• --account added to every agent subcommand, and threaded through agentSession
• duplicated extractPositional and confirm helpers, defined independently on both branches, reduced to one
• cmdAgentManage still dispatched on args[0], so dwshell agent --account … group … answered unknown agent subcommand "--account". Caught by live testing after the build was already green — the same fix cmdAccount had.

Verification

Live, against a copy of a real configuration, with all four features together:

form	result
--account … agent create … --json	creates, prints the code
agent --account … group … <bad group>	error listing existing groups
agent rm … --yes --account …	deletes
--account … GHE -c "uname -s"	Linux
--json list, list --json	identical
shell list for a machine named like a command	still resolves as a machine
--, help, version, unknown flag	unchanged

gofmt, go vet, go test -race ./... green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MvidAFW9a2r4hTgHPW9ywG