[CLI] Generate command parsing, help, docs, and completions from one command schema

[cssbruno]

Priority

Medium-high — usability, documentation accuracy, and CLI maintenance cost.

Context

cmd/gowdk/main.go defines a large top-level command table, while nested command help is still handled with command-specific switches. Command usage strings are manually duplicated across code and documentation. Several project flags are parsed independently across commands.

Problem

The CLI surface is now large enough that manual command definitions are becoming a usability and correctness risk.

Current symptoms:

• many top-level commands and nested command families share flags but parse them separately;
• help text, CLI reference documentation, and parser behavior can drift;
• nested help is special-cased rather than derived from a recursive command tree;
• shell completions cannot be generated from the same source of truth;
• new flags require coordinated edits in multiple files.

This is separate from #671, which proposes shared compilation orchestration. Even with a shared service, the CLI needs one declarative command schema.

Proposed direction

Define a recursive command specification that owns:

• command names and aliases;
• positional arguments;
• supported flags;
• common project/build/audit flag groups;
• validation rules;
• usage text;
• JSON/human output availability;
• shell completion metadata;
• generated docs snippets.

The command parser, gowdk --help, nested help, docs/reference/cli.md, and completions should be generated from this schema.

Acceptance criteria

• Top-level and nested command help are generated from one recursive command model.
• Common flags such as --config, --env-file, --module, --target, --json, and --ssr are defined once.
• docs/reference/cli.md is generated or checked against the command schema.
• Shell completion generation can consume the same schema.
• Tests verify that parser behavior and generated help stay aligned.
• Adding a new command or flag requires one schema edit plus handler implementation.

Related

• Extract shared project compilation orchestration from the CLI #671 — Extract shared project compilation orchestration from the CLI