From eedcd57ad23811c78f31830a272095b43706ada1 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 25 Jul 2026 21:22:07 +1000 Subject: [PATCH] G-121 drafted (user-approved): make.tcl bakelist + selective bake New proposed goal: 'bakelist ?kitname...?' informational lister (mapping + runtime presence + deployed state; name filter doubles as per-kit detail) and 'bake ?kitname...?' selective baking with bare bake unchanged. Both defined against the parsed mapping model so the G-024 toml conversion slides underneath. Ergonomics decision record in Alternatives (bake -list and action-grouped bake rejected per the G-112 stage-true principle; bare 'kits' already rejected in the G-112 name-selection record). Overlap survey recorded: substantive relations G-024/G-023/G-115/G-057/G-028/G-101 + archived G-104/G-098 precedent. Delivers the mapvfs.config todo (comment retires when the goal lands). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 4 ++ goals/G-121-bakelist-selective-bake.md | 75 ++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 goals/G-121-bakelist-selective-bake.md diff --git a/GOALS.md b/GOALS.md index ea6245d5..8a391d90 100644 --- a/GOALS.md +++ b/GOALS.md @@ -392,3 +392,7 @@ Detail: goals/G-115-declarative-vfs-composition.md ### G-116 [proposed] Suite-built tcltls with a zig-built crypto backend: bi-family battery, prebuilt replacement path Scope: src/buildsuites/suite_tcl90/ (build_tcltls module + crypto-backend build, sources.config + build.zig.zon source records, kit-family bi payload + metadata extension, test_gate record step); src/vfs kit payloads carrying vendored tcltls binaries (current-state reference + recorded disposition only - removal stays G-004-era work); punkbin (as eventual artifact destination via the G-067 library class); consumers punk::imap4 / punk::netbox (package require tls) as verification context Detail: goals/G-116-suite-built-tcltls.md + +### G-121 [proposed] make.tcl bakelist + selective bake: list configured kits, bake by name +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 +Detail: goals/G-121-bakelist-selective-bake.md diff --git a/goals/G-121-bakelist-selective-bake.md b/goals/G-121-bakelist-selective-bake.md new file mode 100644 index 00000000..99dfd996 --- /dev/null +++ b/goals/G-121-bakelist-selective-bake.md @@ -0,0 +1,75 @@ +# 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 ` 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 ` filters to the named entries; `make.tcl bake ` 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).