4.2 KiB
G-030 make.tcl dogfoods punk::args: tabled usage, declared subcommands, prompt-free flags
Status: proposed Scope: src/make.tcl (dispatch, help, prompts), src/bootsupport/AGENTS.md + src/modules/AGENTS.md (bootstrap-tracked staleness contract), src/modules/punk/args-999999.0a1.0.tm (only as consumed) Acceptance: as in root GOALS.md index (canonical).
Context
make.tcl is the first surface a developer meets in a punkshell-derived project,
but its command handling predates the ecosystem's own tooling: a hand-built
help text, a bare known_commands list, ad-hoc argument handling per
subcommand, and interactive y/n prompts (vfscommonupdate's REPLACE
confirmation, the project-build confirmations, bootsupport staleness prompts).
Eating our own dogfood - punk::args definitions per subcommand with the tabled
usage rendering - both showcases the ecosystem where it is most visible and
makes the parsing declarative.
The prompts are the practical payoff: agent-driven builds currently pipe y
into stdin (fragile, undiscoverable - observed 2026-07-07 while rebuilding
tomlish.exe). With punk::args parsing, prompt-free operation is just another
declared option per subcommand, and non-interactive stdin without the flag can
fail fast with usage instead of hanging on a read or half-aborting.
Precedents already in-tree: src/tests/runtests.tcl parses via punk::args ((script)::runtests definition), and the tomlish cmdline app presents tabled usage as its first surface.
Approach
- One PUNKARGS definition per subcommand (@cmd -summary/-help + opts), plus a
top-level definition enumerating subcommands - replacing punkboot_gethelp
and the hand-maintained help strings.
make.tcl,make.tcl -help, and per-subcommand help all render through punk::args::usage. - Prompt policy: interactive stdin -> prompt as today (default); flag supplied (e.g. -confirm 0 / -y, naming decision recorded here) -> proceed without prompting; non-interactive stdin without the flag -> usage error, fast. The bootsupport staleness prompt keeps its abort/prompt/proceed classification but gains the same flag route.
- Degradation is a hard requirement (the 2026-07-06/07 incidents are the
cautionary tale: a stale bundled fileutil disabled the very make.tcl step
needed to fix it). The boot phase stays self-contained; punk::args is
guarded-lazily required post-boot (the punkboot::utils pattern documented in
src/bootsupport/AGENTS.md); when unavailable, dispatch and the repair
commands (check, bootsupport, modules) keep working with plain-text fallback
help. Note the tabled rendering also pulls punk::ansi/textblock/punk::char -
exactly the modules whose same-version staleness broke shellfilter this week
- so rendering must degrade independently of parsing (punk::args plain output when the ANSI stack is unhealthy).
- Staleness tracking: punk::args joins the bootstrap-tracked buildversion set (currently punkcheck, punk::repo, punk::mix, punk::tdl) with the same bump-at-least-minor-on-call-site-API-change discipline; whether the rendering stack is also tracked or left to degrade is an implementation decision to record here (initial lean: track punk::args only - it is the parsing contract; rendering degrades).
- Layout copies of make.tcl follow through the existing punkcheck-tracked sync (custom/_project) and the G-012/G-027 channels for the rest - noted in completion reports, never hand-synced.
Alternatives considered
- Ad-hoc -y flags bolted onto the current hand parsing - rejected: solves the agent problem but leaves the first-surface help un-showcased and the parsing divergent from the ecosystem's own conventions.
- Requiring punk::args at boot (no fallback) - rejected: make.tcl must be able to repair the very bootsupport snapshot it loads punk::args from.
Notes
- Related: G-015 (agents driving punk tooling non-interactively), G-024 (mapvfs toml errors deserve the same declared-argument quality), G-025 (the version-report subcommand should be born punk::args-defined), G-027 (pull updates deliver the improved make.tcl to derived projects).
- Observation parked here from the same session: runtests/make.tcl-adjacent tooling that returns result dicts should document their key shape (see the runx -tcl exitcode note in G-015's detail).