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 LIVE as of G-033's achievement (2026-07-28, goals/archive/G-033-proj-mode-cwd-project.md): the drafted text (block semantics, ordering-as-tie-break rule, the proj: scope prefix with the kit-first proj:internal-src canonical example) now sits as the packagemode leader in punk::args::moduledoc::punkexe 0.1.1's (script)::punkexe definition. This goal's remaining lane is the rendering/parse wiring that consumes it.
• 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).
• G-118 item 10 relationship (recorded 2026-07-24 after overlap review; G-118 achieved 2026-07-25 - see goals/archive/G-118-tclsh-subcommand-review.md): G-118 DELIVERED the launch-subcommand-family documentation as G-032-COMPATIBLE punk::args definitions - this goal's source material now exists in punk::args::moduledoc::punkexe (src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm): (script)::punkexe top-level (subcommand enumeration with choicelabels, package-mode leader documented in help text, default reclassification described) + per-subcommand (script)::punkexe::tclsh (full contract, multi-form) and summary-level script/shell/punk/shellspy. The -help rendering, subcommand option parsing, registration integration and degradation wiring stay here - this goal wires the dispatch to render/parse from those ids (punk::args 0.12.7+ resolves the (script)::* id family through update_definitions/usage). Also: G-118 item 4 shipped a file-exists pre-check in the tclsh subcommand (clean not-found + exit 1)
  • precedent for this goal's open unknown-first-arg reclassification rule (reclassify-only-when-file-exists candidate).
• 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).