punkshell/CHANGELOG.md

Changelog

All notable changes to the punkshell project version are documented here. The latest ## [X.Y.Z] header must match the version field in punkproject.toml. Entries are newest-first; one bullet per notable change. See the root AGENTS.md "Project Versioning" section for the bump policy.

[0.53.0] - 2026-08-05

• Single help mechanism (user direction; boot core 0.5.0, moduledoc::punkexe 0.6.0, moduledoc::punkboot 0.3.0): all -help/--help flag interception is withdrawn from the kit launcher and make.tcl - the leading help word is the one help entry (the punkshell i <cmd> ... idiom). <punkexe> help <subcommand> ?arg ...? now accepts and ignores trailing words, so help can simply be prepended to an existing command line (previously help tclsh somefile somearg confusingly fell back to the top-level table). Help flags are ordinary arguments everywhere: a leading -help earns the unknown-first-argument refusal (whose stderr usage answers it, exit 1), tclsh -help regains full stock dash parity (the sole-argument carve-out is gone), buildinfo -help is refused like any argument (exit 2), the experimental shellspy processor's own -help/--help handling is reachable again, and make.tcl <subcommand> ... -help fails whatever punk::args gate it meets (e.g. bakelist -help = the same choice-gate rejection as bakelist nonexistant) with the usage error itself carrying the documentation. launcherhelp.test and maketclhelp.test re-pinned to the revised contract.

[0.52.0] - 2026-08-04

• G-165 driver-invariant kit assembly: every make.tcl zip-kit bake now emits an ARCHIVE-relative kit regardless of the driving interpreter (legacy file-relative mkimg in 8.7/9.0.0, fixed mkimg in 9.0.1+, or no mkimg at all). Zip-kit assembly uses a single writer layer - punk::zip::mkzip (0.4.0), punkzip-accelerated when bin/punkzip resolves via the new write-path seam (mirroring the G-126 read-path accelerator), the pure-Tcl floor otherwise - with the runtime prefix concatenated outside the writer; tcl::zipfs::mkimg is retired from the pipeline. Four-driver acceptance on the reference machine (8.7a6, 9.0.3, native 8.6, msys2 8.6): identical member sets and CRCs, offsetstyle=archive, no BAKE-WARNINGs. File-relative kits remain available only as an explicit per-kit offsetstyle = "file" declaration in src/runtime/mapvfs.toml (the G-134 carve-out as configuration; the pin now warns only on undeclared file-relative output and exempts declared kits - specimen: [kit.punkfiledemo]).
• punkzip 2.4.0 re-vendored (G-165 enabling changes, upstream commit 2599127): build gains -b root-strip (mkzip -base semantics) and repeatable -x entry-name exclusion (Tcl string match syntax).
• make.tcl bake/bakehouse -force flag: re-assemble kits whose inputs are unchanged (bypasses the 'no change detected' skip).
• punkkit-stamp.toml is now written with pinned LF translation - the default text translation followed the driving interpreter (crlf vs lf), making the stamp's bytes driver-dependent (caught by the four-driver parity run).

[0.51.2] - 2026-08-04

• punk::tcltestrun 0.4.2 (G-161 follow-on, landed at user direction): the closing-banner prefix match no longer treats the test NAME as a glob pattern - string match "$line_inner*" meant a name containing glob metacharacters (* ? backslash) never matched its own opening text, so the closing banner failed to close the failure section and every later event including the summary line was swallowed (the G-161 wedge class; latent, unexercised in the corpus). The check is now an exact byte prefix compare (string equal -length) - identical semantics for ordinary names. Pinned by new parsetestrun-globname-7.0/7.1 in the parser suite (8/8 green: tclsh90 both modes, tclsh86).

[0.51.1] - 2026-08-04

• punk::args 0.15.1 (G-164): the G-152 form-viability verdict's valmin-reservation false negative is cured. When the reservation seats a word that literally names a declared required option into a required value slot at end-of-input, and the resulting optionmissing stands in the viability probe (a value word consumed), the probe re-parses with the stolen word(s) consumed as the options they name and classes the form viable (incomplete) on pure end-of-input exhaustion. i hash -t now marks the test form "(viable - needs more arguments)" (show_or_set/rehash/delete/help stay not viable) and i hash -d marks delete viable - the 0.51.0 known issue is resolved. Runtime seating is unchanged: the trailing-flag-as-value rule is load-bearing and pinned unchanged, as is the runtime optionmissing ("missing flags") path; a stolen word naming a value-TAKING required option stays conservative (invalid). Options still missing after the re-seating are ordinary exhaustion in the re-probe. Verdict contract documentation updated in the parse/parse_status argdoc. Pins: formviability.test +7 tests (17/17), cmdhelp.test GAP pin cmdhelp_GAP_multiform_flagled_testform_false_notviable flipped to cmdhelp_multiform_flagled_testform_viable (45/45); args + ns subtrees green apart from the 2 pre-existing nsprimitives environment failures on this box.

[0.51.0] - 2026-08-04

• i <command> ?word ...? form narrowing for flat multi-form commands (G-150): punk::auto_exec::hash's declaration is now selection-sound - its show_or_set name value carries -regexprefail {^-}, so a bare punk::args parse of a flag-led line selects the flag form uniquely instead of reporting an ambiguous match with show_or_set (which swallowed flag-like words as plain names). i hash -r now renders only the rehash form's usage and i hash -d <name> only the delete form, driven by the declaration through cmdhelp's existing G-041 advisory-parse candidacy (no hash-handler involvement); no-word, ambiguous and no-match lines keep the whole-command render. hash's runtime behaviour is unchanged - a dash-led name now needs an explicit flag form at the declaration level too (accepted cost). cmdhelp's subcommand help documents the narrowing contract. Modules: auto_exec 0.1.1, ns 0.9.2 (documentation-only). Pins: 8 new tests in ns/testsuites/ns/cmdhelp.test (narrowing on -r/-d, bare-parse selection incl -t/plain/empty lines, the dash-led-name noformmatch cost, no-word and ambiguity whole-render fallbacks, unknown-flag noformmatch fallback, runtime-unchanged hash behaviour).
• hash declaration/handler refinements (user direction, same batch): the help form dropped -anyopts so --help must lead, and trailing words of any shape are consumed as ignored values - dash-led words included, via the new punk::args @values -flagvalues 1 capability (punk::args 0.15.0, added for this: an unmatched dash-led word in option position seats as a trailing value instead of raising invalidoption; opt-in, off by default). A flag-led line (e.g. -t) no longer marks the help form viable via adhoc-option seating (the old "help (viable)" pointer for i hash -t was wrong). Known issue in the remaining verdict: the test form also reports "(not viable)" for i hash -t - a false negative, since hash -t foo is valid; the valmin reservation seats the lone -t as the required name value, after which the G-152 position guard lets the required-flag optionmissing stand. The intended refinement is an alternative- allocation re-probe in the G-152 probe layer (re-probe with the stolen word consumed as the option it literally names), NOT a runtime seating change - the trailing-flag-as-value rule is load-bearing and pinned unchanged. GAP-pinned in cmdhelp.test. Also the handler's multi-name -t missing-name branch now prints "hash: : not found" (was an undefined-variable error "can't read hash"). Pins: args flagvalues.test (9) + cmdhelp.test (45/45 green).

[0.50.1] - 2026-08-04

• commandstack 0.7.1 (G-160 follow-on, landed at user direction): the reload contract - known_renamers and debug are now info-exists guarded like the rest of the module state (all_stacks, renamer_command_tokens, token_implementations), so a module re-source refreshes proc definitions only and no longer resets them while stacks/tokens survive. Previously the reset stranded live stacks: the removal forms gate on known_renamers membership, so the surviving records' renamers became unknown and removal errored. Contract documented in commandstack::help; pinned by commandstack_reload_preserves_state (suite 41/41 on tclsh90 9.0.3 and punk86 8.6; packagepreference consumer suites 6/6 on both). Minted as modules/commandstack-0.7.1.tm; bootsupport/vfscommon promotion left to the next promotion cycle (as with 0.6.0/0.7.0).

[0.50.0] - 2026-08-04

• punk executable -e one-liner support (G-077, achieved): ` -e