From 232f2f60965805444a01834c1e296148e8c68648 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 25 Jul 2026 20:57:21 +1000 Subject: [PATCH] contextual sweep: deprecated make.tcl subcommand references (user-directed, incl. contract lines) Each site read in context, not grep-replaced; bakehouse vs bake chosen per meaning, and missing invocation arguments supplied where the reference describes an unattended flow: - G-005 Approach + Notes, G-006 Acceptance + body: 'make.tcl project' -> 'make.tcl bakehouse' (the full consumer build these goals integrate with; no flags - conceptual references on a clean checkout, not recipes). - G-057 Acceptance: 'make.tcl project' -> 'make.tcl bake' (icon embedding lives in the kit-wrap stage and must hold for a bare bake; bakehouse inherits). - G-028 Context DELIBERATELY UNCHANGED: dated 2026-07-07 incident narrative - the command actually run; history stays verbatim (alias keeps it readable). - src/runtime/mapvfs.config todo: 'vfs' -> 'bake' wish, re-annotated - G-104 achieved WITHOUT the single-kit-by-name/list-kits item (still open). - src/runtime/vendorlib_vfs.toml header: vfslibs now runs as a phase of bake (G-112 fold), not 'as part of project'. - shellexit.test + staticruntime.test rebuild comments: 'project' -> 'bake' AND stale '(interactive y confirmation)' / bare vfscommonupdate corrected to '-confirm 0' (piped y retired since G-030) - the missing-arguments class. - punk.project layout store vfs READMEs (lib + modules): 'make.tcl vfs' -> 'make.tcl bake'; modpod template twins propagated via the punkcheck layout->modpod sync (make.tcl modules run), never hand-edited. Variant-phrasing sweep confirmed non-hits: G-115 '(vfs assembly)' names the src/vfs payload tier (name retained), G-047 'make.tcl/project.new' is the dev project.new command. Archive tier + CHANGELOG history untouched. goals_lint + goals_xref refs clean. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- goals/G-005-zig-build-infrastructure.md | 4 ++-- goals/G-006-prebuilt-artifact-download.md | 4 ++-- goals/G-057-kit-icon-embedding.md | 2 +- .../punk/project-0.1/src/vfs/project.vfs/lib/README.md | 2 +- .../punk/project-0.1/src/vfs/project.vfs/modules/README.md | 2 +- .../punk/project-0.1/src/vfs/project.vfs/lib/README.md | 2 +- .../punk/project-0.1/src/vfs/project.vfs/modules/README.md | 2 +- src/runtime/mapvfs.config | 4 +++- src/runtime/vendorlib_vfs.toml | 6 ++++-- src/tests/shell/testsuites/punkexe/shellexit.test | 3 ++- src/tests/shell/testsuites/punkexe/staticruntime.test | 2 +- 11 files changed, 19 insertions(+), 14 deletions(-) diff --git a/goals/G-005-zig-build-infrastructure.md b/goals/G-005-zig-build-infrastructure.md index 2a66402c..8d7cab57 100644 --- a/goals/G-005-zig-build-infrastructure.md +++ b/goals/G-005-zig-build-infrastructure.md @@ -24,7 +24,7 @@ This goal is the primary mechanism for G-004's outcome. It is independent of and 2. **Expand to other dependencies.** Extend the zig build to cover the other native binary dependencies currently committed (twapi, tcllibc, etc.), one at a time. Each dependency gets a zig build target that produces the same artifact shape the repo currently commits. -3. **Integrate with make.tcl.** `tclsh src/make.tcl` is the existing build entry point. Wire it so that when a required binary artifact is not present, it invokes the zig build to produce it (or, per G-006, offers the download path). The integration must not require a separate manual zig step for a normal `make.tcl project` build when the zig toolchain is available. +3. **Integrate with make.tcl.** `tclsh src/make.tcl` is the existing build entry point. Wire it so that when a required binary artifact is not present, it invokes the zig build to produce it (or, per G-006, offers the download path). The integration must not require a separate manual zig step for a normal `make.tcl bakehouse` build when the zig toolchain is available. 4. **Document the zig toolchain prerequisite.** The zig toolchain is a build-time prerequisite for this path. Document how to obtain it (install instructions, version pinning). Consider auto-detection with an actionable message when zig is absent, and defer to G-006's download path or an error depending on what the user has configured. @@ -55,7 +55,7 @@ This goal is the primary mechanism for G-004's outcome. It is independent of and G-116 - is the arm's-length runtime factory this goal's direction became, sharing the pinned-zig / zig-only toolchain policy. This goal's distinct remainder: building the VENDORED native extensions (twapi, tcllibc class) and wiring missing-binary retrieval - into the normal make.tcl project build; G-116 is the living edge of that + into the normal make.tcl bakehouse build; G-116 is the living edge of that extension-build expansion list. Status note: much of this goal's Tcl-core substance has landed through the archived arc while this file stays `proposed` - the goal's currency/scope (vendored deps + make.tcl integration vs the suites' runtime-factory diff --git a/goals/G-006-prebuilt-artifact-download.md b/goals/G-006-prebuilt-artifact-download.md index 3ce2b7c4..a9c7f4ec 100644 --- a/goals/G-006-prebuilt-artifact-download.md +++ b/goals/G-006-prebuilt-artifact-download.md @@ -3,7 +3,7 @@ Status: proposed Scope: src/runtime/; src/make.tcl integration; user-config (consent flags) Goal: pre-built binary artifacts can be downloaded from a separate related binary-artifacts repository or user-configured sources, gated by explicit user consent/configuration by default. -Acceptance: a download mechanism fetches binary artifacts (the same set the zig build produces) from a configured source on demand; by default the download is gated behind explicit user consent (a config flag or interactive prompt) and does not occur silently; a user-configured source URL overrides the default binary-artifacts repo; downloaded artifacts satisfy the same build requirements as zig-built artifacts so `tclsh src/make.tcl project` succeeds with downloaded artifacts in place of built ones. +Acceptance: a download mechanism fetches binary artifacts (the same set the zig build produces) from a configured source on demand; by default the download is gated behind explicit user consent (a config flag or interactive prompt) and does not occur silently; a user-configured source URL overrides the default binary-artifacts repo; downloaded artifacts satisfy the same build requirements as zig-built artifacts so `tclsh src/make.tcl bakehouse` succeeds with downloaded artifacts in place of built ones. ## Context @@ -25,7 +25,7 @@ This goal is parallel to and independent of G-005. A user with zig uses G-005; a 3. **Source configuration.** A config value for the artifact source URL, defaulting to the separate binary-artifacts repo. A user-configured value overrides the default. Document the config key and the expected source format (URL layout, artifact naming convention). -4. **Integration with make.tcl.** When `make.tcl` needs a binary artifact that isn't present and the zig build path (G-005) is not available or not chosen, the download path is offered/followed per the consent gate. The integration must make `tclsh src/make.tcl project` succeed with downloaded artifacts in place of built ones — the artifacts are interchangeable from the build's perspective. +4. **Integration with make.tcl.** When `make.tcl` needs a binary artifact that isn't present and the zig build path (G-005) is not available or not chosen, the download path is offered/followed per the consent gate. The integration must make `tclsh src/make.tcl bakehouse` succeed with downloaded artifacts in place of built ones — the artifacts are interchangeable from the build's perspective. 5. **Artifact equivalence.** Downloaded artifacts must satisfy the same build requirements as zig-built ones (same file shape, same location, same version). If a downloaded artifact differs in a way the build cares about (e.g. different Tcl9 patchlevel), the build must detect and reject it rather than producing a subtly broken system. diff --git a/goals/G-057-kit-icon-embedding.md b/goals/G-057-kit-icon-embedding.md index abbe93a1..40446a30 100644 --- a/goals/G-057-kit-icon-embedding.md +++ b/goals/G-057-kit-icon-embedding.md @@ -3,7 +3,7 @@ Status: proposed Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punk1.ico (project default, existing); src/vfs/*.vfs (override placement convention); src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism); TEMP_REFERENCE/tcl-sfe (read-only reference); helper proc location decided in the work (make.tcl inline vs punk::mix lib) Goal: Windows kit/zipkit builds produce executables carrying an embedded icon chosen at build time - defaulting to the project icon src/runtime/punk1.ico, overridable per kit by its .vfs folder - by replacing the icon resources in the built executable using the twapi-based mechanism demonstrated in tcl-sfe (TEMP_REFERENCE/tcl-sfe, by twapi author and Tcl core member Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, applied so the appended vfs payload stays intact (icon the stub before appending, or sfe-style split/update/reattach). -Acceptance: a Windows `make.tcl project` build produces kit executables whose embedded icon resources are the project default punk1.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; twapi unavailable or non-Windows platform skips the icon step with a notice and the build otherwise completes unchanged; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution. +Acceptance: a Windows `make.tcl bake` build produces kit executables whose embedded icon resources are the project default punk1.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; twapi unavailable or non-Windows platform skips the icon step with a notice and the build otherwise completes unchanged; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution. ## Context diff --git a/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md b/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md index 7281f2c5..b11d3903 100644 --- a/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md +++ b/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md @@ -4,4 +4,4 @@ pkgIndex.tcl-based libraries to embed in the runtime kit built from this vfs fol This layout ships no library snapshot. Populate this folder with the libraries your kit runtime needs (for example by copying from a punk shell distribution or your -project's built lib folders) before building a kit with 'make.tcl vfs'. +project's built lib folders) before building a kit with 'make.tcl bake'. diff --git a/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md b/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md index 33deb979..7fe6269a 100644 --- a/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md +++ b/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md @@ -4,4 +4,4 @@ Tcl .tm modules to embed in the runtime kit built from this vfs folder. This layout ships no module snapshot. Populate this folder with the modules your kit runtime needs (for example by copying from a punk shell distribution or your -project's built modules folders) before building a kit with 'make.tcl vfs'. +project's built modules folders) before building a kit with 'make.tcl bake'. diff --git a/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md b/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md index 7281f2c5..b11d3903 100644 --- a/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md +++ b/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/lib/README.md @@ -4,4 +4,4 @@ pkgIndex.tcl-based libraries to embed in the runtime kit built from this vfs fol This layout ships no library snapshot. Populate this folder with the libraries your kit runtime needs (for example by copying from a punk shell distribution or your -project's built lib folders) before building a kit with 'make.tcl vfs'. +project's built lib folders) before building a kit with 'make.tcl bake'. diff --git a/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md b/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md index 33deb979..7fe6269a 100644 --- a/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md +++ b/src/project_layouts/vendor/punk/project-0.1/src/vfs/project.vfs/modules/README.md @@ -4,4 +4,4 @@ Tcl .tm modules to embed in the runtime kit built from this vfs folder. This layout ships no module snapshot. Populate this folder with the modules your kit runtime needs (for example by copying from a punk shell distribution or your -project's built modules folders) before building a kit with 'make.tcl vfs'. +project's built modules folders) before building a kit with 'make.tcl bake'. diff --git a/src/runtime/mapvfs.config b/src/runtime/mapvfs.config index c11b6923..458a23c1 100644 --- a/src/runtime/mapvfs.config +++ b/src/runtime/mapvfs.config @@ -65,7 +65,9 @@ tclsfe-x64.exe {punk9wintk903.vfs punk91 zip} #_beta convention: wrap freshly suite-built runtimes as *_beta kits even BEFORE they have passed the # punk test suites - so new-runtime behaviour can be trialled interactively. Drop _beta on acceptance. # (punk905_beta trialled and PROMOTED to punk905 2026-07-21.) -#todo: 'make.tcl vfs' enhancement - build a single configured kit by name + list configured kits (G-104) +#todo: 'make.tcl bake' enhancement - build a single configured kit by name + list configured kits +# (sibling-ergonomics wish recorded in G-104, achieved 2026-07-25 WITHOUT this item - +# see goals/archive/G-104-maketcl-buildsuite-surface.md; still open) #5 tclsh905.exe {punk9wintk905.vfs punk905 zip} diff --git a/src/runtime/vendorlib_vfs.toml b/src/runtime/vendorlib_vfs.toml index e56187a0..deb75d2c 100644 --- a/src/runtime/vendorlib_vfs.toml +++ b/src/runtime/vendorlib_vfs.toml @@ -2,8 +2,10 @@ # # Declares which vendored platform-library package folders (paths relative to src/) are # installed into which kit vfs lib trees (paths relative to src/vfs/). Processed by -# 'tclsh src/make.tcl vfslibs' - and automatically as part of 'tclsh src/make.tcl project' - -# with punkcheck-tracked provenance (records in src/vfs/.punkcheck, outside kit payloads). +# 'tclsh src/make.tcl vfslibs' - and automatically as a phase of 'tclsh src/make.tcl bake' +# (and therefore of 'bakehouse'; G-112 folded the phase in so a bake cannot ship stale +# binary libs) - with punkcheck-tracked provenance (records in src/vfs/.punkcheck, +# outside kit payloads). # # Participation is per-package per-kit by design: kit vfs package sets intentionally differ # (e.g. twapi versions vary per kit), so nothing is blanket-copied and a vendorlib drop does diff --git a/src/tests/shell/testsuites/punkexe/shellexit.test b/src/tests/shell/testsuites/punkexe/shellexit.test index a4fbb91e..ce6f5753 100644 --- a/src/tests/shell/testsuites/punkexe/shellexit.test +++ b/src/tests/shell/testsuites/punkexe/shellexit.test @@ -20,7 +20,8 @@ package require tcltest #then /bin/punkshell902. Tests are skipped (constraint punkexeavailable) if none found. # #NOTE: the tests exercise the BUILT executable - after changing punk::repl or app-punkshell source, rebuild -#with 'make.tcl packages', then 'make.tcl vfscommonupdate' (interactive y confirmation), then 'make.tcl project' +#with 'make.tcl packages', then 'make.tcl vfscommonupdate -confirm 0' (unattended; the REPLACE confirmation +#aborts fast on non-interactive stdin - piped y is retired), then 'make.tcl bake' #or these tests will run against a stale binary. # #WARNING for interactive runs: a regression in the eof/error termination path causes the spawned executable diff --git a/src/tests/shell/testsuites/punkexe/staticruntime.test b/src/tests/shell/testsuites/punkexe/staticruntime.test index af842cc4..72c2ce7b 100644 --- a/src/tests/shell/testsuites/punkexe/staticruntime.test +++ b/src/tests/shell/testsuites/punkexe/staticruntime.test @@ -17,7 +17,7 @@ package require tcltest #sha1sums.txt) - retrieve to bin/runtime// and rebuild. # #NOTE: tests exercise the BUILT executable - after changing punk_main.tcl or the seeding -#modules, rebuild with 'make.tcl modules', 'make.tcl vfscommonupdate', 'make.tcl project' +#modules, rebuild with 'make.tcl modules', 'make.tcl vfscommonupdate -confirm 0', 'make.tcl bake' #or these tests will run against a stale binary. namespace eval ::testspace {