Route the shell's built-in commands with Cobra

[kanushka]

Parent

#85

What to build

Every command the shell owns is routed by Cobra, and the shell's common flags work on all of them. A user can give --context or --output to any shell command, in either position around the subcommand name, and get the same result. wso2 help and wso2 <command> --help describe what actually exists, because the text is generated from the command tree rather than maintained by hand. A misspelled shell command suggests what was probably meant.

Nothing a user does today stops working. An argument the shell does not recognise still resolves as a product namespace and reaches the product module with its arguments verbatim. A flag error still reads in the shell's voice, with recovery guidance and the documented usage exit class, not in Cobra's. Built-in commands still win over any installed namespace, and asking for help still works before anything is installed and without touching the module store.

Flag semantics do not change in this ticket: the built-in command bodies keep their current argument handling behind the new routing, so the existing tests are the regression suite. Command suggestions cover shell commands only for now, and the product namespace path keeps interpreting the output flag itself, both of which are lifted by #86.

The decision is recorded as an ADR: Cobra is adopted for the shell's command UI; the shell links Cobra and pflag only and never the documentation-generation subpackage; passthrough at the namespace boundary stays hand-written pending declared command trees; and argument parsing will read a declared tree from the integrity-checked receipt, never from the unsigned remote catalog. The existing shell command framework research points at that ADR instead of standing as a recommendation against it.

Acceptance criteria

• --context and --output are declared once on the root and accepted before or after a command name, and a command that cannot act on one refuses it as a typed usage problem rather than accepting and ignoring it
• -o json, -o=json, --output json, and --output=json are all accepted
• Help output is generated from the command tree, lists every shell command, and states that product commands come from installed modules
• A misspelled shell command suggests the closest shell command
• An unknown flag, a flag missing its argument, and a malformed flag value each report a typed usage problem with recovery guidance and the usage exit class, with a test per kind
• Cobra prints neither errors nor usage itself; one exit path maps problem category to exit class
• An unrecognised first argument still resolves as a product namespace, and the module still receives its arguments unparsed
• Built-in commands still take precedence over a receipt namespace, and the existing test asserting it passes unchanged
• The existing test asserting an unknown command is a usage problem passes unchanged
• Help reads no module store and touches no filesystem state
• A test matrix covers shell flags in both positions around a subcommand name and around a product namespace, including a module's own flag following a leading shell flag
• One table-driven test asserts both interpreters of the output flag agree on the same argument list
• A boundaries test asserts the shell binary links Cobra and pflag and not the documentation-generation subpackage
• The hand-written help implementation is deleted
• ADR is added, and the shell command framework research carries a status pointer to it

Blocked by

None (can start immediately).

[kanushka]

Three of the acceptance criteria above were amended while implementing, because they were wrong as written rather than because the implementation fell short.

"--context and --output accepted on every shell command" was not achievable without a semantics change. No built-in honors --output today: version renders fixed fields and the module lifecycle commands render their own tables. Only the product namespace path acts on it. Making version accept --output json would mean implementing JSON rendering for it, which #85 rules out as a flag-semantics change reserved for a later PR. Accepting the flag and silently dropping it is worse than refusing it, since the user believes it took effect. So the flags stay declared once on the root, each command names which of them it can act on, and one it cannot act on is refused as shell.unsupported_flag with the usage exit class. Today login acts on --context and the namespace path acts on both.

"Help and version read no module store" was wrong about version. Listing installed modules is what wso2 version is for, so it reads the store by definition. The criterion now covers help only, which is the part that actually needed protecting.

The test matrix criterion was too weak, and the gap it left was a real defect. Parsing the root's flags left Cobra parsing the whole remaining argument list, so wso2 --context prod api list --env stage failed with unknown flag: --env — a module's flag rejected by the shell, which #85 calls its single most important constraint. The first version of the matrix passed because none of its cases put a module flag after a leading shell flag. Flag parsing now stops at the first non-flag argument, and the matrix covers that case.

Two smaller things found the same way. A leading shell flag before a namespace printed help instead of dispatching, because the leftover arguments reached the root's own handler and read as no command. And the two parsers of --output had already drifted: pflag accepts -o=json and -ojson, the passthrough parser matched only a bare -o, so those two spellings were being handed to the module. Both are fixed, and the agreement test now covers every spelling. The combined shorthand is claimed only when its value is an actual mode, so a module flag such as -optimize stays the module's.