punkshell/goals/G-032-launcher-punkargs.md

G-032 Kit launcher dogfoods punk::args: tabled help and parsed subcommands

Status: proposed Scope: src/vfs/_config/ (default dispatch), src/lib/app-punkshell and sibling app packages as touched Goal: the default launch dispatch defines its subcommands via punk::args - <punkexe> -help and argument errors render the tabled usage enumerating built-in and project-registered subcommands with summaries, and subcommand options parse through punk::args so projects can declare complex arguments - with the G-030 degradation rules (boot never fails and help degrades to plain text when punk::args or the ANSI rendering stack is unavailable). Acceptance: <punkexe> -help renders tabled usage listing all subcommands including project-registered ones, each with a summary; at least one built-in subcommand's options are declared and parsed via punk::args with tabled usage errors on invalid input (the G-015 script subcommand or the G-025 version-report subcommand are the natural candidates); a project-registered subcommand's help appears by registration alone - no edits to the shared dispatch; with punk::args or the rendering stack unloadable, boot proceeds and help degrades to a plain subcommand list; verified on both a zipfs-based and a non-zipfs kit where both remain supported.

Context

The kit launcher is, alongside make.tcl (G-030), the first surface a user or agent meets - and it should showcase the ecosystem's own argument tooling the way the tomlish cmdline app already does (tabled usage on -help/no-args). Today the dispatch in punk_main.tcl is a bare switch on the first argument with no help output at all: an unknown first argument silently becomes a script attempt, and there is no way to discover the subcommands (tclsh/shellspy/punk/shell/script) or the package-mode tokens without reading the source.

Builds on G-031's registration model: the thin project main declares subcommands with optional punk::args definition ids; the shared dispatch renders and parses from those declarations - so a project's subcommands appear in -help by registration alone.

Approach

• punk::args definitions for the top-level dispatch (subcommand enumeration with @cmd summaries, package-mode leader documented) and per-subcommand options. <punkexe> -help, <punkexe> help <subcommand>, and <subcommand> -help all render tabled usage.
• The packagemode leader's help text is pre-drafted in G-033's detail file (block semantics, ordering-as-tie-break rule, the proj: scope prefix with the kit-first proj:internal-src canonical example) - use that as the source text, noting the proj: portions go live only when G-033 implements the prefix.
• Parse errors on declared subcommands produce punk::args usage errors (tabled), not silent fallthrough. The unknown-first-arg -> script reclassification survives only where it does not swallow obvious mistakes - the exact rule is an implementation decision to record here (candidates: reclassify only when the argument names an existing file, else usage error).
• Degradation per the G-030 rules: the kit normally bundles punk::args and the rendering stack, but src/dev modes and damaged kits must not brick the launcher - guarded lazy require; parsing degrades to the current switch semantics and help to a plain subcommand list when punk::args (or the ANSI stack, independently) is unavailable.
• Exit-code and output-cleanliness expectations follow G-015: help to stdout exit 0; usage errors to stderr nonzero; no launcher chatter on the app's channels.

Alternatives considered

• Help text maintained by hand in the dispatch - rejected: the same hand-maintained-help drift make.tcl has (G-030), and project-registered subcommands would need dispatch edits to become discoverable.
• Requiring punk::args at boot - rejected: same repair-path reasoning as G-030 and the punkboot::utils guarded-require rule.

Notes

• Related: G-031 (registration model this renders from - soft prerequisite; could proceed on the monolith but shouldn't), G-030 (make.tcl counterpart and the shared degradation doctrine), G-015 (script subcommand options are a natural first parsed subcommand; exit-code semantics), G-025 (version-report subcommand born punk::args-defined), G-013 (the debugrepl activation review mentions proper-command conversions that would slot into the same pattern).
• Archived-goal references in this file: G-015 achieved 2026-07-07 (goals/archive/G-015-script-subcommand-piped-stdin.md); G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md) - the make.tcl counterpart shipped: follow its shipped decisions (-confirm 0|1 prompt policy, explicit @form -synopsis, track-parsing-degrade-rendering split, required-choice leaders for pointed choiceviolation errors).