From ccd08a3942d0799ac98a6f806736da1f5b333eed Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 21 Jul 2026 19:08:02 +1000 Subject: [PATCH] punk::mix::base: manual -> magic version scheme (completion); AGENTS manual-versioning list updated Completes the user's conversion of punk::mix::base from manual versioning to the magic-version mechanism: header Meta block + magic provide block in base-999999.0a1.0.tm, version history relocated to the new base-buildversion.txt (0.1.2 - same version, mechanism-only change). The file RENAME itself landed one commit early (ab3e1a45) via the staged index riding an unrelated commit - net effect is the repo's preferred move-then-edit sequence, recorded here for clarity. src/modules/AGENTS.md: punk::libunknown is now the only manually versioned module; base noted as converted 2026-07-21. Bootsupport syncs from the rebuild ride along: base-0.1.2.tm restamped from the converted source; libunknown comment catch-up (runtime.cmd -> punk-runtime.cmd reference). Conversion verified: make.tcl modules builds base-0.1.2.tm from the magic-versioned source under Tcl 9.0.3 and 8.7a6 (the original build failure was the unrelated pre-c971e6c7c4 zipfs mkzip dotfile defect, fixed by cli 0.5.2's fallback in ab3e1a45). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- src/bootsupport/modules/punk/libunknown-0.2.1.tm | 2 +- src/bootsupport/modules/punk/mix/base-0.1.2.tm | 7 ++++--- src/modules/AGENTS.md | 4 ++-- src/modules/punk/mix/base-999999.0a1.0.tm | 9 +++++---- src/modules/punk/mix/base-buildversion.txt | 5 +++++ 5 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 src/modules/punk/mix/base-buildversion.txt diff --git a/src/bootsupport/modules/punk/libunknown-0.2.1.tm b/src/bootsupport/modules/punk/libunknown-0.2.1.tm index c0d92a16..84d84eb8 100644 --- a/src/bootsupport/modules/punk/libunknown-0.2.1.tm +++ b/src/bootsupport/modules/punk/libunknown-0.2.1.tm @@ -184,7 +184,7 @@ tcl::namespace::eval ::punk::libunknown { proc zipfs_tm_UnknownHandler {original name args} { #------------------------------ #shortcircuit for builtin static libraries which have no 'package provide' info - review - #This occurs for example when running 'bin\runtime.cmd run src\make.tcl shell' with punk902z.exe + #This occurs for example when running 'bin\punk-runtime.cmd run src\make.tcl shell' with punk902z.exe # #------------------------------ set loaded [lsearch -inline -index 1 -nocase [info loaded] $name] diff --git a/src/bootsupport/modules/punk/mix/base-0.1.2.tm b/src/bootsupport/modules/punk/mix/base-0.1.2.tm index 48c8597e..b91bdca2 100644 --- a/src/bootsupport/modules/punk/mix/base-0.1.2.tm +++ b/src/bootsupport/modules/punk/mix/base-0.1.2.tm @@ -1,10 +1,11 @@ +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'deck make' or src/make.tcl to update from -buildversion.txt +# @@ Meta Begin +# Application punk::mix::base 0.1.2 +# @@ Meta End package provide punk::mix::base [namespace eval punk::mix::base { variable version set version 0.1.2 }] -#version history (manually versioned module - real version is the filename/provide value) -#0.1.2 - fix: cksum_path hung forever on files on non-native (vfs-mounted e.g //zipfs:/) filesystems - the tcllib -file digest modes read via fileevent+vwait and vfs channels never deliver fileevents. Files on non-native filesystems are now slurped and digested in data mode (new cksum_data_command per algorithm incl new cksum_adler32_data/cksum_crc_data helpers; exec-based sha3 returns an unsupported_algorithm_for_vfs_path error for vfs paths). Needed for punkcheck::install from module-carried //zipfs:/ layout payloads (G-087 stage 3). -#0.1.1 - fix: get_template_basefolders no-handler warning used 'put' instead of 'puts'; missing-handler path now warns and returns an empty dict instead of erroring on an unset variable package require punk::path package require punk::lib ;#format_number etc diff --git a/src/modules/AGENTS.md b/src/modules/AGENTS.md index d292917e..52e2f195 100644 --- a/src/modules/AGENTS.md +++ b/src/modules/AGENTS.md @@ -15,7 +15,7 @@ Source of truth for all editable Punk project modules. This is where agents shou - Module filenames use the literal suffix `-999999.0a1.0.tm`. - Corresponding `-buildversion.txt` files hold the real version number. -- The exceptions are `punk::libunknown` and `punk::mix::base`, which are manually versioned: the real `major.minor.patch` version lives in the filename (e.g `libunknown-.tm`, `mix/base-.tm`) and there is no buildversion.txt. The same bump rules apply as for buildversion-tracked modules (see "Versioning And Releases"); the mechanics differ — see the manual-versioning bullet there. +- The exception is `punk::libunknown`, which is manually versioned: the real `major.minor.patch` version lives in the filename (e.g `libunknown-.tm`) and there is no buildversion.txt. The same bump rules apply as for buildversion-tracked modules (see "Versioning And Releases"); the mechanics differ — see the manual-versioning bullet there. (`punk::mix::base` was converted from manual to the magic-version scheme 2026-07-21.) - `#modpod-*` directories contain internal files packed into `.tm` archives during build; do not flatten or edit them without understanding the modpod format. - `_build/` directory holds build intermediates and should not be manually edited. - Always declare dependencies explicitly using `package require ` near file tops. @@ -321,7 +321,7 @@ return This keeps the changelog discoverable alongside the version number without requiring a separate CHANGES file. - **Bootstrap-tracked files only** — `punkcheck-buildversion.txt`, `punk/repo-buildversion.txt`, `punk/mix-buildversion.txt` (the top-level `punk::mix` file only; `punk::mix::util`, `punk::mix::cli`, and `punk/mix/commandset/*` version independently and are not covered by this check), `punk/tdl-buildversion.txt`, and `punk/args-buildversion.txt` (added by G-030: make.tcl dogfoods punk::args for dispatch/help; only the parsing contract is tracked — the punk::ansi/textblock rendering stack degrades instead): bump at least **minor** whenever a call site inside that file is updated to use a new API, even if the file's own interface is unchanged. `src/make.tcl` reads only these five files to classify bootsupport staleness (major=abort, minor=prompt, patch=silent-proceed); under-bumping one of them to patch when the call-site change is more significant causes `make.tcl` to mis-classify and either wrongly proceed without prompting or wrongly abort. See `src/bootsupport/AGENTS.md` "Bootsupport Staleness Handling" for the full contract. - **All other modules** (including `punk::mix` submodules): call-site updates follow ordinary judgement from the Patch/Minor/Major rules above — a behavior-preserving call-site change is a patch (or no bump if genuinely a no-op); reserve minor for changes that add capability to the module's *own* API. `src/make.tcl` does not read these versions, so there is no automated consequence, but keep the changelog accurate since it is the only record of the module's real semantic version. -- **Manually versioned modules** (currently `punk::libunknown` and `punk::mix::base`): the real `major.minor.patch` version is the filename suffix and the `package provide` block value; there is no `-buildversion.txt` and the build does not stamp a version. The Patch/Minor/Major bump rules above apply identically — an agent changing such a module bumps by (1) renaming the file (`git mv`) to the new version, (2) updating the `# Application ` Meta line, the doctools `manpage_begin` version and the provide-block `set version` (where each exists - punk::mix::base has only the provide block), and (3) appending a changelog comment line to the version-history block in the module header (it substitutes for the buildversion.txt changelog). Before the first bump of such a module, verify nothing requires it by exact version or hardcoded filename (for punk::libunknown: punk_main.tcl and punk::repl glob `libunknown-*.tm` and pick the highest by vcompare, bootsupport's include_modules.config lists it by name only, and all requires are unversioned - verified 2026-07-11; for punk::mix::base: all requires unversioned, bootsupport include_modules.config lists it by name only - verified 2026-07-17). New modules should use the magic version mechanism instead. +- **Manually versioned modules** (currently `punk::libunknown` only; `punk::mix::base` converted to the magic scheme 2026-07-21): the real `major.minor.patch` version is the filename suffix and the `package provide` block value; there is no `-buildversion.txt` and the build does not stamp a version. The Patch/Minor/Major bump rules above apply identically — an agent changing such a module bumps by (1) renaming the file (`git mv`) to the new version, (2) updating the `# Application ` Meta line, the doctools `manpage_begin` version and the provide-block `set version` (where each exists), and (3) appending a changelog comment line to the version-history block in the module header (it substitutes for the buildversion.txt changelog). Before the first bump of such a module, verify nothing requires it by exact version or hardcoded filename (for punk::libunknown: punk_main.tcl and punk::repl glob `libunknown-*.tm` and pick the highest by vcompare, bootsupport's include_modules.config lists it by name only, and all requires are unversioned - verified 2026-07-11). New modules should use the magic version mechanism instead. - Modules with the magic version number must not appear in output paths such as `/modules`. - When referencing ranges, use bounded specs such as `1.2.3-2.0.0`. - Convert loose versions to bounded form in module metadata; helper utilities exist in boot modules for this purpose. diff --git a/src/modules/punk/mix/base-999999.0a1.0.tm b/src/modules/punk/mix/base-999999.0a1.0.tm index 48c8597e..aab7a735 100644 --- a/src/modules/punk/mix/base-999999.0a1.0.tm +++ b/src/modules/punk/mix/base-999999.0a1.0.tm @@ -1,10 +1,11 @@ +# Maintenance Instruction: leave the 999999.xxx.x as is and use 'deck make' or src/make.tcl to update from -buildversion.txt +# @@ Meta Begin +# Application punk::mix::base 999999.0a1.0 +# @@ Meta End package provide punk::mix::base [namespace eval punk::mix::base { variable version - set version 0.1.2 + set version 999999.0a1.0 }] -#version history (manually versioned module - real version is the filename/provide value) -#0.1.2 - fix: cksum_path hung forever on files on non-native (vfs-mounted e.g //zipfs:/) filesystems - the tcllib -file digest modes read via fileevent+vwait and vfs channels never deliver fileevents. Files on non-native filesystems are now slurped and digested in data mode (new cksum_data_command per algorithm incl new cksum_adler32_data/cksum_crc_data helpers; exec-based sha3 returns an unsupported_algorithm_for_vfs_path error for vfs paths). Needed for punkcheck::install from module-carried //zipfs:/ layout payloads (G-087 stage 3). -#0.1.1 - fix: get_template_basefolders no-handler warning used 'put' instead of 'puts'; missing-handler path now warns and returns an empty dict instead of erroring on an unset variable package require punk::path package require punk::lib ;#format_number etc diff --git a/src/modules/punk/mix/base-buildversion.txt b/src/modules/punk/mix/base-buildversion.txt new file mode 100644 index 00000000..b9e800bd --- /dev/null +++ b/src/modules/punk/mix/base-buildversion.txt @@ -0,0 +1,5 @@ +0.1.2 +#First line must be a semantic version number +#all other lines are ignored. +#0.1.2 - fix: cksum_path hung forever on files on non-native (vfs-mounted e.g //zipfs:/) filesystems - the tcllib -file digest modes read via fileevent+vwait and vfs channels never deliver fileevents. Files on non-native filesystems are now slurped and digested in data mode (new cksum_data_command per algorithm incl new cksum_adler32_data/cksum_crc_data helpers; exec-based sha3 returns an unsupported_algorithm_for_vfs_path error for vfs paths). Needed for punkcheck::install from module-carried //zipfs:/ layout payloads (G-087 stage 3). +#0.1.1 - fix: get_template_basefolders no-handler warning used 'put' instead of 'puts'; missing-handler path now warns and returns an empty dict instead of erroring on an unset variable