punkshell/goals/archive/G-104-maketcl-buildsuite-surface.md

G-104 make.tcl buildsuite surface: list / info / build

Status: achieved 2026-07-25 Scope: src/make.tcl (buildsuite subcommand group); src/buildsuites/*/ (suite self-description contract: an 'info'/describe affordance per suite - suite.tcl action or manifest record); documentation (make.tcl help text, src/buildsuites README/AGENTS) Goal: an ergonomic make.tcl surface for defined buildsuite builds: 'make.tcl buildsuite list' discovers the suites under src/buildsuites (excluding _build and non-suite dirs) with one-line descriptions; 'make.tcl buildsuite info ' surfaces the configured detail for review - source records from sources.config (urls/refs/pins), the pinned zig, the product set, doc pointers; 'make.tcl buildsuite build ?args?' runs the suite's driver forwarding suite options (e.g -tclbranch, -refresh, -target when G-105 lands). Suites stay SELF-describing so copy-and-tweak trees (G-096 workflow) appear in list/info automatically without make.tcl edits. Acceptance: list shows suite_tcl90 (and any copied tree) with descriptions sourced from the suites themselves; info renders the sources.config-derived table plus zig pin and products for a named suite; build forwards arguments and streams driver output, exiting with the driver's status; the surface works when make.tcl runs under a plain tclsh and under punk kit executables; help text documents the group; the self-description contract is documented where suite authors will find it (src/buildsuites docs) and holds for a tree created by copying suite_tcl90.

Context

User requirement 2026-07-20: "an ergonomic way to run a defined buildsuite build - nice-to-have is a way to list possible builds and considering there is a fair bit of configured info for each, a way to retrieve/review info about a particular buildsuite. Presuming surface will be a subcommand or group of subcommands in make.tcl."

Design lean: make.tcl stays a THIN front - discovery by directory scan, description and info answered by the suite itself (a 'suite.tcl info' action emitting a stable record, or a small manifest the driver also reads). That keeps copied/retargeted trees first-class citizens and survives the G-102 driver-shape migration (achieved 2026-07-21: suite.tcl remains as the fossil dev wrapper delegating to the recipe's zig steps, with 'zig build stage|bootstrap' as the no-tclsh flow - whatever fronts these keeps answering the same contract; make.tcl need not know which shape a suite uses).

Sibling ergonomics note: the earlier-recorded make.tcl 'vfs' wishes (build a single configured kit by name + list configured kits from mapvfs.config - noted in mapvfs.config comments and archived G-098 (achieved 2026-07-20) notes) are a separate subsystem (kit wrapping) but the same ergonomic family - a candidate to execute alongside this goal.

Relationships: G-096 (achieved 2026-07-20 - suite.tcl driver + copy-and-tweak workflow this fronts), G-102 (achieved 2026-07-21 - driver shape settled; the info/build contract holds), G-103 (achieved 2026-07-22 - see goals/archive/G-103-runtime-kit-family.md; family products appear in info output), G-105 (target dimension forwarded when it exists).

Progress

• 2026-07-25 surface landed (punkshell 0.23.0, written directly in the G-112 stage-true vocabulary): make.tcl gains the buildsuite group (list/info/build) as a declared passthrough beside shell (driver args forwarded untouched in both the punk::args and degraded-fallback dispatch paths). Self-description contract settled on the MANIFEST option: sources.config gains description/product/doc/zigpin records parsed by BOTH suite.tcl (strict; its pinned-zig default now reads the zigpin record - single source of truth) and make.tcl (tolerant - a malformed/absent manifest lists with the problem as its description instead of breaking discovery). Discovery = directory scan for a suite.tcl driver, _build excluded (samplesuite1 auto-excluded). Contract documented in src/buildsuites/README.md (new) + AGENTS.md (new, indexed from src/AGENTS.md); make.tcl help/plain-help document the group.
• Verified 2026-07-25: list shows suite_tcl90 with its sources.config-derived description; info renders the sources table + zig pin (present) + products + doc pointers; build forwards args and exits with the driver's status (unknown-option run exit 1 streamed; unknown suite/action exit 2; list exit 0); works under native tclsh90 AND punk91-kit-hosted (script-mode launcher selection via the static-capture marker from archived G-058 - see goals/archive/G-058-static-runtime-packages.md); a throwaway COPY of suite_tcl90 with an edited description appeared in list/info automatically and was removed after the check. suite.tcl direct CLI re-verified (usage-error path through the new config-load position).
• Acceptance close 2026-07-25 (achieved flip): every acceptance clause is verified - list (suite_tcl90 + a copied tree, descriptions sourced from the suites), info (sources.config table + zig pin + products), build forwarding/ streaming/exit-status (the driver genuinely executed and its status propagated - the unknown-option probe run; a full pipeline run through the surface was gold-plating beyond the criterion and arrives naturally with the G-099 suite_tcl86 builds), plain tclsh + punk kit hosting, help text, and the contract documented in src/buildsuites/README.md + AGENTS.md where suite authors will find it. Window doc sweep complete.

Notes

• Activation freshness 2026-07-25: goals_xref.tcl score G-104 re-run at the proposed->active flip - G-099/G-105/G-112 relations already recorded; new Related recorded from the re-run: G-108 (debug buildsuite tier) - its -dbg suite variants ride the same suite.tcl driver this surface's build action forwards to, and appear in list/info via the same self-description contract (no make.tcl edits by construction). Activated together with G-112 + G-113 as one make.tcl-surface window.
• 2026-07-21 (user-approved pairing): G-112 (stage-true subcommand rename) edits the same make.tcl subcommand surface - SUBOPTS/SUMMARIES/HELPTEXTS tables, help/workflow output. Ordering: G-112 lands first, or the two run together as one make.tcl-surface window, so this goal's buildsuite group and workflow text are written once in the renamed vocabulary (the sibling-ergonomics 'vfs' wishes above become 'bake'-named under G-112). Mirror note in G-112.
• G-099 relationship (recorded 2026-07-24 after overlap review): suite_tcl86 is the second suite this surface must list/info/build without make.tcl edits - the self-description contract (suite.tcl info action or manifest record) is shaped so a forked/new suite satisfies it by construction.