punkshell/goals/G-121-bakelist-selective-bake.md

G-121 make.tcl bakelist + selective bake: list configured kits, bake by name

Status: proposed Scope: src/make.tcl (bake @values + new bakelist subcommand; SUBOPTS/SUMMARIES/HELPTEXTS/SUBGROUPS, help/workflow text); src/runtime/mapvfs.config (as read; todo-comment retirement); src/tests/shell/testsuites/punkexe/ (bakelist characterization if feasible); layout make.tcl copies via established sync channels Goal: make.tcl can report and selectively execute the configured kit matrix: bakelist lists the configured kit outputs (name, kit type, runtime with presence, vfs folder, deployed state) with optional per-kit name filtering, and bake <kitname ...> bakes and deploys exactly the named kits - bare bake unchanged (all configured kits). Both consume the PARSED mapping model, not the file format, so the G-024 toml conversion slides underneath without changing the surface. Acceptance: make.tcl bakelist under a plain tclsh and under a punk kit executable lists every kit output configured in the runtime mapping with name, kit type, runtime (present/missing), vfs folder and a deployed-state indication (bin copy absent/current/stale vs the build product), and bakelist <kitname> filters to the named entries; make.tcl bake <kitname ...> builds and deploys only the named kit(s) - a recorded verification shows the named kit's artifacts refreshing while other kits' _build/bin artifacts and punkcheck records are untouched - and an unknown name errors without building, listing the configured names; bare make.tcl bake processes the same kit set as before the change; help/workflow text documents both per the update contract and the mapvfs.config todo comment is retired to point here; a piped bakelist characterization test lands under punkexe if feasible (else the infeasibility is recorded here); project version minor-bumped with a CHANGELOG entry.

Context

Recorded as a sibling-ergonomics wish during G-104's drafting (archived 2026-07-25 - see goals/archive/G-104-maketcl-buildsuite-surface.md; also noted in archived G-098's notes and the src/runtime/mapvfs.config todo comment): "build a single configured kit by name + list configured kits". G-104 delivered the buildsuite list/info/build surface without this item - the kit wrap subsystem is a separate surface reading src/runtime/mapvfs.config.

Today a bake is all-or-nothing: iterating on one kit (e.g punk91 during the G-120 work) rebuilds/deploys every configured kit, and discovering what WOULD be baked means reading mapvfs.config's custom line format by eye. The deploy-state question ("is bin/punk91.exe current with what a bake would produce?") has no surface at all - the stale-r1-runtime incident of 2026-07-25 (see the G-112 flip evidence) was exactly an invisible kit-state divergence.

Approach

• bake ?kitname ...?: extend the existing verb's punk::args definition from @values -min 0 -max 0 to optional kit-name values; the kit-build loop filters the parsed mapping to the named outputs. Unknown names error before any build, listing the configured names. bin (which builds kits "as for bake") stays full-set - out of scope.
• bakelist ?kitname ...?: new subcommand in the informational SUBGROUP (verbs act, the informational group reports - the G-112 stage-true principle; a -list mode flag on bake was rejected for making a verb sometimes not act). Columns: kit name, type (kit|zip|zipcat), runtime name
  • presence in the runtime store, vfs folder, deployed state. Name filtering doubles as per-kit detail (punk-runtime list precedent) - no separate bakeinfo word.
• Both features consume one parsed-mapping helper so the reader swaps cleanly at G-024 time; scheme-expanded outputs (G-023) enter the same model as expansions when those land.
• Discoverability nicety (decided in the work): the bake/bakelist argdocs may enumerate configured kit names as punk::args choices when the mapping parses at definition time, degrading to plain string args otherwise.
• Piped output is ESC-free automatically (G-113 policy); keep bakelist's columns stable enough to grep.

Alternatives considered

• bake -list flag - rejected: a verb that conditionally does not act recreates the semantics-blur G-112 removed.
• Action-grouped bake list|info|build (G-104 buildsuite shape) - rejected: bare bake must keep meaning build-all, and a first positional that is either an action or a kitname is grammar mud.
• Bare kits noun subcommand - rejected: the G-112 name-selection record already rejected 'kits' as colliding with kit runtimes; bakelist is self-locating next to bake.

Notes

• Overlap survey 2026-07-25 (goals_xref paths over src/make.tcl, src/runtime/mapvfs.config, src/vfs/, punkexe suites + report review): src/make.tcl is a ubiquitous anchor (20+ goals, low scores, not substantive). Substantive relations: G-024 (owns the mapping FORMAT - this surface reads the parsed model and must survive the toml swap; its entry-level validation errors are what bakelist surfaces as per-entry state), G-023 (scheme-expanded output names join the listed/bakeable set when its generative naming lands), G-115 (sibling declaration surface for .vfs payload composition - per-kit payload detail could later join bakelist's per-kit view), G-057 (per-kit icon override would appear as per-kit detail; its acceptance already runs through the wrap steps this goal parameterizes), G-028 (deploy-failure/locked-exe naming is the acting sibling of bakelist's deployed-state reporting), G-101 (consumes mapvfs 'kit'-type entries for 8.6 containers - the lister must not assume zip-only types). Archived precedent: G-104 (list/info surface shape + the wish's recorder), G-098 (wish also noted there).