diff --git a/CHANGELOG.md b/CHANGELOG.md index cff81839..af9df474 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to Entries are newest-first; one bullet per notable change. See the root `AGENTS.md` "Project Versioning" section for the bump policy. +## [0.55.1] - 2026-08-05 + +- G-149 follow-on landed: make.tcl's multi-form definitions (tool, buildsuite) + adopt '@cmd -formhint' - 'make.tcl help tool' / 'help buildsuite' now label + each form's synopsis line with the actionable dry-run-help invocation plus a + trailing ellipsis ('make.tcl help tool build ...' rendered with U+2026) + instead of the repl-oriented ' i -form N ...' default, which is unreachable + for make.tcl's (script) ids. The ellipsis honestly marks that help accepts + the form's own command line after the action (the dry-run continuation). + The labels also render on dispatch usage errors, where they are the + discovery route to per-action help - the reason the column is configured + rather than suppressed. Renders via the promoted bootsupport punk::args + 0.17.0; degrades harmlessly (default labels) under older snapshots in + generated projects. Layout make.tcl copies and the templates modpod synced + via the established channels. + ## [0.55.0] - 2026-08-05 - G-149 achieved: punk::args configurable multi-form synopsis hint labels diff --git a/goals/archive/G-149-punkargs-formhint-labels.md b/goals/archive/G-149-punkargs-formhint-labels.md index 8a5237cd..ce0a1c00 100644 --- a/goals/archive/G-149-punkargs-formhint-labels.md +++ b/goals/archive/G-149-punkargs-formhint-labels.md @@ -66,4 +66,4 @@ Verification evidence: ## Follow-ons -Follow-on: make.tcl adopts the mechanism for its (script)::punkboot definitions (e.g a 'make.tcl help ' hint phrasing via @cmd -formhint) after a bootsupport promotion carrying punk::args 0.17.0- (maketclhelp.test formhints pin updates with it) => open +Follow-on: make.tcl adopts the mechanism for its (script)::punkboot definitions (e.g a 'make.tcl help ' hint phrasing via @cmd -formhint) after a bootsupport promotion carrying punk::args 0.17.0- (maketclhelp.test formhints pin updates with it) => landed 2026-08-05 (make.tcl tool+buildsuite @cmd -formhint " make.tcl help %formname% " - trailing ellipsis marks the dry-run continuation help accepts after the action (user direction: a hint without it misrepresents the line as complete); template kept over empty-string suppression because the labels also render on dispatch usage errors, where they are the discovery route to per-action help; punkshell 0.55.1; maketclhelp.test formhints pins flipped + buildsuite hint pin added (utf-8 byte-triple matching - the harness reads the pipe binary); layout make.tcl copies + templates modpod + bootsupport templates synced same unit) diff --git a/punkproject.toml b/punkproject.toml index 77e19bf6..a41bf6c2 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,6 +1,6 @@ [project] name = "punkshell" -version = "0.55.0" +version = "0.55.1" license = "BSD-2-Clause" url = "https://www.gitea1.intx.com.au/jn/punkshell" #packager: declared identity for published artifacts (declarative, not proof - diff --git a/src/bootsupport/modules/punk/mix/templates-0.2.0.tm b/src/bootsupport/modules/punk/mix/templates-0.2.0.tm index 3882931a..4dfdbed0 100644 Binary files a/src/bootsupport/modules/punk/mix/templates-0.2.0.tm and b/src/bootsupport/modules/punk/mix/templates-0.2.0.tm differ diff --git a/src/make.tcl b/src/make.tcl index 5c350a1e..2e8b3cf9 100644 --- a/src/make.tcl +++ b/src/make.tcl @@ -3707,6 +3707,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::buildsuite" @cmd -name "make.tcl buildsuite" -& -summary "${[dict get $SUMMARIES buildsuite]}" -& + -formhint " make.tcl help buildsuite %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS buildsuite]}} @form -form {list info build} @@ -3737,6 +3738,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::tool" @cmd -name "make.tcl tool" -& -summary "${[dict get $SUMMARIES tool]}" -& + -formhint " make.tcl help tool %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS tool]}} @form -form {list info build test} diff --git a/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/make.tcl b/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/make.tcl index 5c350a1e..2e8b3cf9 100644 --- a/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/make.tcl +++ b/src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/project_layouts/vendor/punk/project-0.1/src/make.tcl @@ -3707,6 +3707,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::buildsuite" @cmd -name "make.tcl buildsuite" -& -summary "${[dict get $SUMMARIES buildsuite]}" -& + -formhint " make.tcl help buildsuite %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS buildsuite]}} @form -form {list info build} @@ -3737,6 +3738,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::tool" @cmd -name "make.tcl tool" -& -summary "${[dict get $SUMMARIES tool]}" -& + -formhint " make.tcl help tool %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS tool]}} @form -form {list info build test} diff --git a/src/project_layouts/vendor/punk/basic/src/make.tcl b/src/project_layouts/vendor/punk/basic/src/make.tcl index 5c350a1e..2e8b3cf9 100644 --- a/src/project_layouts/vendor/punk/basic/src/make.tcl +++ b/src/project_layouts/vendor/punk/basic/src/make.tcl @@ -3707,6 +3707,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::buildsuite" @cmd -name "make.tcl buildsuite" -& -summary "${[dict get $SUMMARIES buildsuite]}" -& + -formhint " make.tcl help buildsuite %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS buildsuite]}} @form -form {list info build} @@ -3737,6 +3738,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::tool" @cmd -name "make.tcl tool" -& -summary "${[dict get $SUMMARIES tool]}" -& + -formhint " make.tcl help tool %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS tool]}} @form -form {list info build test} diff --git a/src/project_layouts/vendor/punk/project-0.1/src/make.tcl b/src/project_layouts/vendor/punk/project-0.1/src/make.tcl index 5c350a1e..2e8b3cf9 100644 --- a/src/project_layouts/vendor/punk/project-0.1/src/make.tcl +++ b/src/project_layouts/vendor/punk/project-0.1/src/make.tcl @@ -3707,6 +3707,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::buildsuite" @cmd -name "make.tcl buildsuite" -& -summary "${[dict get $SUMMARIES buildsuite]}" -& + -formhint " make.tcl help buildsuite %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS buildsuite]}} @form -form {list info build} @@ -3737,6 +3738,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO @id -id "(script)::punkboot::tool" @cmd -name "make.tcl tool" -& -summary "${[dict get $SUMMARIES tool]}" -& + -formhint " make.tcl help tool %formname% \u2026" -& -help -& {${[dict get $HELPTEXTS tool]}} @form -form {list info build test} diff --git a/src/tests/shell/testsuites/punkexe/maketclhelp.test b/src/tests/shell/testsuites/punkexe/maketclhelp.test index 50162804..6c752393 100644 --- a/src/tests/shell/testsuites/punkexe/maketclhelp.test +++ b/src/tests/shell/testsuites/punkexe/maketclhelp.test @@ -14,7 +14,13 @@ package require tcltest #option-position unknown flags), and buildsuite keeps its passthrough #driver-args contract (forms serve help/synopsis only). #Pins: -# - 'help tool' / 'help buildsuite': per-action synopsis lines with i -form hints +# - 'help tool' / 'help buildsuite': per-action synopsis lines with actionable +# 'make.tcl help ...' hint labels, ellipsis (U+2026) +# marking the dry-run continuation help accepts after the action (G-149 +# @cmd -formhint adoption 2026-08-05 - the repl-oriented ' i -form N ...' +# default is not actionable for (script) ids and no longer renders here; the +# hints also render on dispatch usage errors, where they are the discovery +# route to per-action help) # and the action -choicelabels in the choices area; ESC-free (G-113 piped policy) # - 'help tool build': the build form's own argument table (-test opt + toolname); # 'help buildsuite build': suitename-required diagnosis carrying the form's rows @@ -154,7 +160,14 @@ namespace eval ::testspace { } #added 2026-08-01 (agent, G-143) - test maketcl_help_tool_multiform {piped 'make.tcl help tool': exit 0, ESC-free, one synopsis line per action with i -form hints and the action choicelabel} -constraints {tclshavailable} -body { + #formhints pin updated 2026-08-05 (agent, G-149): the tool definition adopts + #'@cmd -formhint' with template ' make.tcl help tool %formname%' plus a + #trailing U+2026 ellipsis (punk::args 0.17.0), so the per-form hint labels + #are the actionable dry-run-help invocations, one per action, with the + #ellipsis honestly marking that help accepts the form's own command line + #after the action (the G-143 dry-run); the repl-oriented ' i -form N ...' + #default no longer renders. + test maketcl_help_tool_multiform {piped 'make.tcl help tool': exit 0, ESC-free, one synopsis line per action with 'make.tcl help tool ' hint labels and the action choicelabel} -constraints {tclshavailable} -body { set r [maketcl_run {help tool}] set out [dict get $r output] set result [list] @@ -164,10 +177,15 @@ namespace eval ::testspace { lappend result syninfo [regexp {make\.tcl tool info toolname \[toolname\]\.\.\.} $out] lappend result synbuild [regexp {make\.tcl tool build \[-test \] \[toolname\]\.\.\.} $out] lappend result syntest [regexp {make\.tcl tool test \[toolname\]\.\.\.} $out] - lappend result formhints [regexp { i -form 0 } $out] + #U+2026 (the hints' dry-run-continuation marker) as its utf-8 byte triple: + #maketcl_run reads the pipe -translation binary, so multibyte chars arrive + #byte-wise (built with format so this source stays ASCII) + set ell [format %c%c%c 0xe2 0x80 0xa6] + lappend result formhints [expr {[regexp " make\\.tcl help tool list $ell" $out] && [regexp " make\\.tcl help tool build $ell" $out]}] + lappend result olddefaulthint [regexp { i -form 0 } $out] lappend result choicelabel [regexp {Discover the tools with version, zig floor, install state} $out] set result - } -result {timedout 0 exitcode 0 esc 0 synlist 1 syninfo 1 synbuild 1 syntest 1 formhints 1 choicelabel 1} + } -result {timedout 0 exitcode 0 esc 0 synlist 1 syninfo 1 synbuild 1 syntest 1 formhints 1 olddefaulthint 0 choicelabel 1} #added 2026-08-01 (agent, G-143) test maketcl_help_tool_build_form {'make.tcl help tool build' renders the build form's argument table (-test opt, toolname, build choicelabel)} -constraints {tclshavailable} -body { @@ -222,7 +240,10 @@ namespace eval ::testspace { } -result {timedout 0 exitcode 0 synbuild 1 accepted 1 landed 1 timedout2 0 exitcode2 1 gate2 1 timedout2b 0 exitcode2b 0 accepted2b 1 timedout3 0 exitcode3 1 noform3 1 synindiag3 1 timedout4 0 exitcode4 1 noform4 1} #added 2026-08-01 (agent, G-143) - test maketcl_help_buildsuite_multiform {piped 'make.tcl help buildsuite': exit 0, one synopsis line per action} -constraints {tclshavailable} -body { + #formhints pin added 2026-08-05 (agent, G-149): buildsuite adopts + #'@cmd -formhint' with the ' make.tcl help buildsuite %formname%' + trailing + #U+2026 ellipsis template, like tool above. + test maketcl_help_buildsuite_multiform {piped 'make.tcl help buildsuite': exit 0, one synopsis line per action with 'make.tcl help buildsuite ' hint labels} -constraints {tclshavailable} -body { set r [maketcl_run {help buildsuite}] set out [dict get $r output] set result [list] @@ -231,8 +252,11 @@ namespace eval ::testspace { lappend result synlist [regexp {make\.tcl buildsuite list} $out] lappend result syninfo [regexp {make\.tcl buildsuite info suitename} $out] lappend result synbuild [regexp {make\.tcl buildsuite build suitename \[driverarg\]\.\.\.} $out] + set ell [format %c%c%c 0xe2 0x80 0xa6] ;#U+2026 as utf-8 bytes (binary-read pipe - see tool test) + lappend result formhints [expr {[regexp " make\\.tcl help buildsuite list $ell" $out] && [regexp " make\\.tcl help buildsuite build $ell" $out]}] + lappend result olddefaulthint [regexp { i -form 0 } $out] set result - } -result {timedout 0 exitcode 0 esc 0 synlist 1 syninfo 1 synbuild 1} + } -result {timedout 0 exitcode 0 esc 0 synlist 1 syninfo 1 synbuild 1 formhints 1 olddefaulthint 0} #added 2026-08-01 (agent, G-143); updated 2026-08-02 (agent) - pure dry-run: the #build form requires a suitename, so the bare action word yields the punk::args