diff --git a/CHANGELOG.md b/CHANGELOG.md index ea519600..2c39f25e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ 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.12.25] - 2026-07-14 + +- G-030 follow-up (user review): make.tcl's constructed punk::args definitions adopt the G-045 authoring mechanisms - @cmd -help bodies converted to block-form values with a bare @normalize per definition, fixing the constructed-definition indent leak (first Description line rendered less indented than continuations; the braced option fragments never leaked because literal block-shaped parts get file-style normalization). Added a define-time capability probe (get_spec on representative ids) so a stale punk::args that accepts the text but cannot resolve a mechanism degrades to the plain fallback immediately. AGENTS infrastructure for future documentation work: new "punk::args definition authoring ergonomics" subsection in src/modules/AGENTS.md (constructed-def @normalize + block form, -unindentedfields, -& record continuation, container quoting rules, explicit @form -synopsis for script-level ids, the optional-choice error-quality workaround), cross-referenced from src/AGENTS.md with ::punkboot::argdoc named as the in-tree exemplar. Layout make.tcl copies followed via the punkcheck channel. + ## [0.12.24] - 2026-07-14 - G-030 (achieved): make.tcl dogfoods punk::args. All 15 subcommands are punk::args-declared ((script)::punkboot definitions with single-source summaries, shared option fragments and explicit @form -synopsis lines): bare `make.tcl`/`-help` render tabled usage with grouped subcommand summaries, `make.tcl help ?subcommand?` / ` -help` show per-subcommand definitions, invalid flags and unknown subcommands raise punk::args usage errors (exit 1) with unambiguous-prefix resolution. New `-confirm 0|1` prompt policy on every confirmation point (bootsupport minor-staleness gate, vfscommonupdate REPLACE, kit-type mismatch): default prompts only on an interactive terminal and aborts fast with guidance on non-interactive stdin (the piped-`y` agent workflow is retired - use `-confirm 0`; the old vfscommonupdate decline half-abort now exits 1). punk::args joined the bootstrap-tracked staleness set (parsing contract only - the punk::ansi/textblock rendering stack degrades instead: minimal errorstyle/plain help when unhealthy, and full scan-based fallback dispatch when punk::args itself is unavailable; PUNKBOOT_PLAIN=1 forces the degraded mode). Bootsupport snapshot refreshed (args 0.5.0->0.12.0 plus punk/lib/ns/repl/tclcore moduledoc) and layout make.tcl/bootsupport copies followed via the punkcheck channel. Docs: src/AGENTS.md, src/bootsupport/AGENTS.md, src/modules/AGENTS.md, src/tests/shell/AGENTS.md. Dogfooding finding recorded in the goal file: punk::args 0.12.0 reports a generic overflow error where 0.5.0 reported a pointed choiceviolation for optional-choice mismatches (worked around with required leaders; candidate punk::args error-selection improvement). diff --git a/goals/archive/G-030-maketcl-punkargs.md b/goals/archive/G-030-maketcl-punkargs.md index d1c50a80..88171b58 100644 --- a/goals/archive/G-030-maketcl-punkargs.md +++ b/goals/archive/G-030-maketcl-punkargs.md @@ -177,6 +177,37 @@ usage as its first surface. here; possible future punk::args nicety: fall back to @cmd -name for synopsis rendering). +### Follow-up 2026-07-14 (same day, post-achievement): G-045 mechanisms adopted + +User review spotted @cmd -help Description blocks rendering with the first line +indented less than continuations - the constructed-definition indent leak G-045 +characterized (head-form multi-line values interpolated via [list] carry +make.tcl's source indentation as data; the composed @cmd record line starts at +column 0 so no whole-block base trim applies, and the renderer's max-4 undent +leaves the residue). Notably the braced shared option fragments did NOT leak - +as literal block-shaped parts they received file-style normalization, which is +why argument help columns were aligned while @cmd help was not. + +Fix per G-045's preferred style (increment 4): HELPTEXTS and the inline +shell/help/toplevel help values converted to block form (first value line +whitespace-only) with a bare @normalize in every constructed definition +(head-form values, e.g the option fragments, are contractually untouched). +Added a capability probe inside the guarded block - punk::args::get_spec on +representative ids forces resolution at define time, so a stale punk::args that +accepts the raw text but cannot resolve a mechanism (e.g pre-@normalize +snapshots) degrades to the plain fallback immediately instead of erroring at +first parse. Verified flush Description rendering for toplevel/subcommand/ +shell/help usage; dispatch, degraded mode and error paths re-verified. + +AGENTS infrastructure: src/modules/AGENTS.md "Documentation And Comments" +gained a "punk::args definition authoring ergonomics" subsection pointing +future documentation work at the G-045 mechanisms (@normalize + block form for +constructed defs, -unindentedfields, -& continuation, container quoting rules, +the explicit @form -synopsis lesson and the optional-choice error-quality +workaround from this goal); src/AGENTS.md's make.tcl bullet cross-references it +and names ::punkboot::argdoc as an in-tree constructed-def exemplar. +(G-045 achieved 2026-07-12 - goals/archive/G-045-punkargs-authoring-ergonomics.md) + ### Deferred / out of scope - The kit-type-mismatch confirmation cannot be triggered without a mismatched diff --git a/punkproject.toml b/punkproject.toml index d7b52db7..bc821e1f 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,4 +1,4 @@ [project] name = "punkshell" -version = "0.12.24" +version = "0.12.25" license = "BSD-2-Clause" diff --git a/src/AGENTS.md b/src/AGENTS.md index 4b380226..371e3dc1 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -67,7 +67,7 @@ Recovery after a wrong path guess: - All build/promotion commands (`project`, `packages`, `modules`, `libs`, `vfs`, `vfslibs`, `bin`, `bootsupport`, `vfscommonupdate`) warn similarly when this project's own `src/` has uncommitted fossil/git changes (dirt outside `src/` is ignored). Warn-only by default; pass `-dirty-abort` to make the check aborting. For evaluating uncommitted source without a build, prefer ` src` / ` src shell`. The check is `punkboot::utils::vcs_dirty_warnings` (optional scope argument) loaded guardedly from bootsupport - if the snapshot is stale/missing the check degrades to a skip notice (but `-dirty-abort` then aborts rather than silently losing the requested strictness). - Provenance warnings (dirty-src gate + vendorupdate source-project check) print with a plain column-0 `PROVENANCE-WARNING:` token (grep for it in captured build output) and are recapped at the end of the run via make.tcl's wrapped `::exit`. Interactive terminal runs get a 3-second ctrl-c grace countdown before a dirty build proceeds; piped/agent runs skip it. `tclsh src/make.tcl check` reports the current src provenance status and what the build commands would do. - Use `tclsh src/make.tcl vfscommonupdate` to rebuild `_vfscommon.vfs`. The REPLACE confirmation prompts on an interactive terminal; unattended/agent runs must pass `-confirm 0` (with the default `-confirm 1` and a piped/closed stdin, make.tcl aborts fast with guidance instead of reading stdin - do not pipe `y`). -- make.tcl subcommands and flags are punk::args-declared (G-030): `tclsh src/make.tcl help ?subcommand?` or ` -help` shows tabled usage; invalid arguments produce punk::args usage errors. The dispatch degrades to plain scan/help when the bootsupport punk::args (or its rendering stack) is stale or unavailable; `PUNKBOOT_PLAIN=1` forces the degraded mode for troubleshooting. +- make.tcl subcommands and flags are punk::args-declared (G-030): `tclsh src/make.tcl help ?subcommand?` or ` -help` shows tabled usage; invalid arguments produce punk::args usage errors. The dispatch degrades to plain scan/help when the bootsupport punk::args (or its rendering stack) is stale or unavailable; `PUNKBOOT_PLAIN=1` forces the degraded mode for troubleshooting. The `::punkboot::argdoc` definitions are constructed (string-built) and use the G-045 authoring mechanisms — block-form help values + `@normalize`, explicit `@form -synopsis` — see src/modules/AGENTS.md "punk::args definition authoring ergonomics" before editing them or authoring similar definitions. - Uncommitted `make.tcl`-generated outputs may be batched into one commit, regardless of how many `make.tcl` invocations produced them. This covers punkcheck-managed build outputs that are VCS-tracked: `src/bootsupport/`, `_vfscommon.vfs/modules` + `/lib`, and declared per-kit `*.vfs/lib_tcl/` subfolders. (Root `modules/`, `lib/`, `modules_tcl/`, `lib_tcl/` are gitignored and never committed.) Each module's old→new version rename is atomic; a regeneration reflects one build-output refresh, not independent hand-edits. This is a carve-out from generic "split aggressively" commit guidance for punkcheck-managed build outputs only — it does not cover user-curated VFS content (`_config/`, per-kit `*.vfs/` outside declared `lib_tcl` subfolders, `_aside/`, `mkzipfix.vfs`, `_vfscommon.vfs/doc`), which commits separately per its own concerns. - Use `punk make.tcl project` or `punk902z make.tcl project` inside Punk shell when building binaries through Punk. - Binary images are platform-specific; build on each target platform rather than expecting a cross-platform flag. diff --git a/src/make.tcl b/src/make.tcl index b46d54cf..4fa7b856 100644 --- a/src/make.tcl +++ b/src/make.tcl @@ -1503,49 +1503,64 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO shell "Run the punk shell using bootsupport libraries" help "Show usage for make.tcl or one of its subcommands" } + #@cmd -help bodies for the constructed definitions below. Authored BLOCK-FORM + #(first value line whitespace-only) so the @normalize directive in each + #definition re-bases the embedded source indentation - the G-045 mechanism for + #string-built definitions, which get no automatic whole-block indent + #normalization (head-form values here would leak this file's indentation into + #the rendered Description column). variable HELPTEXTS { project - "Run the full project build - includes src/vfs/* checks and builds. + " + Run the full project build - includes src/vfs/* checks and builds. Builds/copies .tm modules and pkgIndex.tcl based libraries from src to /modules, /lib etc, propagates declared vendored platform-libraries into kit vfs trees (as for vfslibs), then scans src/runtime and src/vfs folders to build kit/zipkit executables and installs them to /bin." packages - "Build (or copy if build not required) both .tm and pkgIndex.tcl based + " + Build (or copy if build not required) both .tm and pkgIndex.tcl based packages from src to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." modules - "Build (or copy if build not required) .tm modules from src/modules, + " + Build (or copy if build not required) .tm modules from src/modules, src/vendormodules etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." libs - "Build (or copy if build not required) pkgIndex.tcl based libraries from + " + Build (or copy if build not required) pkgIndex.tcl based libraries from src/lib, src/vendorlib etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." vfs - "Scan src/vfs and src/runtime folders and build kit/zipkit executables + " + Scan src/vfs and src/runtime folders and build kit/zipkit executables into /bin. Does not first rebuild modules/libs - use 'make.tcl project' for the full pipeline." vfslibs - "Propagate declared vendored platform-library packages into kit vfs + " + Propagate declared vendored platform-library packages into kit vfs lib_tcl trees. Declarations (per-package per-kit, with superseded-version removal) live in src/runtime/vendorlib_vfs.toml. Also runs automatically as part of 'make.tcl project'." bin - "Install executables from src/bin to /bin, then check vfs + " + Install executables from src/bin to /bin, then check vfs folders and build kit/zipkit executables as for the vfs subcommand." vendorupdate - "Update the src/vendormodules based on src/vendormodules/include_modules.config. + " + Update the src/vendormodules based on src/vendormodules/include_modules.config. Update the src/vendorlib based on src/vendorlib/config.toml (todo)." bootsupport - "Update the src/bootsupport modules as well as the project-layout + " + Update the src/bootsupport modules as well as the project-layout src/bootsupport modules if those folders exist. Bootsupport modules are pulled from locations specified in include_modules.config files within each src/bootsupport subdirectory. @@ -1553,20 +1568,24 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO /modules, /lib etc. Bootsupport modules are available to make.tcl." vfscommonupdate - "Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. + " + Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. Before calling this (followed by 'make.tcl project') - you can test using '(.exe) dev' - this will load modules from your /modules, /lib paths instead of from the kit/zipkit. Replacing the _vfscommon.vfs contents requires confirmation - see -confirm." info - "Show the name and base folder of the project to be built." + " + Show the name and base folder of the project to be built." check - "Show module/library paths and any potentially problematic packages for + " + Show module/library paths and any potentially problematic packages for running this script. Also reports bootsupport staleness and the src provenance status (what the build/promotion commands would do)." projectversion - "Advisory check: verify CHANGELOG.md matches punkproject.toml and warn + " + Advisory check: verify CHANGELOG.md matches punkproject.toml and warn if src/ has changes since the last project-version bump." } #shared option fragments composed into the per-subcommand definitions below @@ -1634,6 +1653,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } set defparts [list] lappend defparts "@id -id (script)::punkboot::$sub" + lappend defparts "@normalize" ;#G-045 block-form value re-basing for constructed definitions lappend defparts "@cmd -name [list "make.tcl $sub"] -summary [list [dict get $SUMMARIES $sub]] -help [list [dict get $HELPTEXTS $sub]]" lappend defparts "@form -synopsis [list [join $synparts { }]]" lappend defparts "@opts" @@ -1645,8 +1665,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot::shell"\ + "@normalize"\ "@cmd -name [list "make.tcl shell"] -summary [list [dict get $SUMMARIES shell]] -help [list\ - "Run the punk shell (repl) using bootsupport libraries. + " + Run the punk shell (repl) using bootsupport libraries. All arguments after the shell subcommand are passed through to the repl untouched (they are not parsed or validated by make.tcl)."]"\ {@form -synopsis "make.tcl shell ?arg ...?"}\ @@ -1655,8 +1677,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "Arguments passed through to the punk repl."} punk::args::define\ "@id -id (script)::punkboot::help"\ + "@normalize"\ "@cmd -name [list "make.tcl help"] -summary [list [dict get $SUMMARIES help]] -help [list\ - "Show tabled usage for make.tcl as a whole, or for a single subcommand. + " + Show tabled usage for make.tcl as a whole, or for a single subcommand. Equivalent to 'make.tcl -help'."]"\ {@form -synopsis "make.tcl help ?subcommand?"}\ "@values -min 1 -max 1"\ @@ -1670,8 +1694,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot"\ + "@normalize"\ "@cmd -name make.tcl -summary {punkshell project build tool (punk boot)} -help [list\ - "punk boot: make any tclkits and modules in /src folders and place + " + punk boot: make any tclkits and modules in /src folders and place them and associated data files/scripts in the parent folder of src - e.g in 'bin' and 'modules' folders at the same level as 'src'. @@ -1684,6 +1710,14 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "@leaders -min 1 -max 1"\ "subcommand -type string -optional 0 -choicecolumns 1 -choicegroups [list $SUBGROUPS] -choicelabels [list $SUMMARIES] -help\ {Use 'make.tcl help ' or 'make.tcl -help' for details of a subcommand.}" + #capability probe: force resolution of representative definitions now, inside + #the guarded block - a stale punk::args that accepted the raw text but cannot + #resolve a mechanism used here (e.g pre-@normalize snapshots) degrades to the + #plain fallback immediately instead of erroring at first parse/usage. + punk::args::get_spec (script)::punkboot + punk::args::get_spec (script)::punkboot::project + punk::args::get_spec (script)::punkboot::help + punk::args::get_spec (script)::punkboot::shell unset -nocomplain sub optvars defparts ov } } _defserr]} { diff --git a/src/modules/AGENTS.md b/src/modules/AGENTS.md index 3e3f574f..f2e706a9 100644 --- a/src/modules/AGENTS.md +++ b/src/modules/AGENTS.md @@ -334,6 +334,18 @@ return - Update relevant docs or usage notes when behavior changes. - Mention environment variables or flags required to run new features. +#### punk::args definition authoring ergonomics (G-045 achieved 2026-07-12 - goals/archive/G-045-punkargs-authoring-ergonomics.md) + +Before writing or generating punk::args definitions, know the mechanisms punk::args >= 0.8.x provides — reach for these instead of re-inventing indent hacks: + +- **File-style (braced-literal) definitions get whole-block indent normalization automatically** — they render independently of the code block's indentation. **Constructed (string-built) definitions do not**: any multi-line value interpolated via `[list ...]`/`format`/`string map` carries its source indentation as data. The tell-tale symptom is a rendered Description/help block whose **first line is indented differently from its continuation lines** (the renderer strips at most 4 leading spaces from continuations). +- **`@normalize`** (bare directive, like `@dynamic`) is the fix for constructed definitions: author multi-line values in **block form** (newline immediately after the opening quote/brace, so the first value line is whitespace-only; content lines uniformly indented) and the resolver re-bases them (first content line fully unindented, continuations to +4, deeper relative indents preserved, whitespace-only trailing line dropped). Head-form values (content on the first line) are contractually untouched, so `@normalize` is safe to add to a definition composed of both styles. In-tree exemplars: `::punk::helptopic::define_docs` (punk.tm) and make.tcl's `::punkboot::argdoc`. +- **`-unindentedfields {-help}`** (on argument lines and the `@cmd` directive) supports left-margin authoring as an alternative; supported and pinned by tests, but the preferred style for constructed defs is indented block form + `@normalize` (G-045 increment 2 decision). +- **`-&` record continuation** (unquoted trailing token) continues a record across lines *inside constructed strings*, where backslash-newline is consumed by the building code's own quoting; brace a literal `{-&}` to escape. Byte-identical assembly to the backslash equivalent. +- **Container quoting rules** (braced values fully literal; double-quoted values get Tcl backslash semantics with `$`/`[]` still literal; `\$\{...\}` for a literal placeholder) are documented in the `punk::args::define` -help — consult it rather than experimenting. +- **Script-level/constructed ids want an explicit `@form -synopsis`**: the auto-generated synopsis currently renders the definition id (e.g `(script)::punkboot::modules`), not `@cmd -name` — supply the real invocation string (G-030 lesson). +- For choice-restricted leaders/values in dispatch-style definitions, prefer `-optional 0` when the calling code only parses when a word is present: as of punk::args 0.12.0 a non-matching word for an *optional* choice arg falls through to a generic overflow error instead of a pointed choiceviolation (regression vs 0.5.0, recorded in goals/archive/G-030-maketcl-punkargs.md). + ## Verification - VS Code Tcl lint diagnostics are clean for modified `.tm` files when available. diff --git a/src/project_layouts/custom/_project/punk.basic/src/make.tcl b/src/project_layouts/custom/_project/punk.basic/src/make.tcl index b46d54cf..4fa7b856 100644 --- a/src/project_layouts/custom/_project/punk.basic/src/make.tcl +++ b/src/project_layouts/custom/_project/punk.basic/src/make.tcl @@ -1503,49 +1503,64 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO shell "Run the punk shell using bootsupport libraries" help "Show usage for make.tcl or one of its subcommands" } + #@cmd -help bodies for the constructed definitions below. Authored BLOCK-FORM + #(first value line whitespace-only) so the @normalize directive in each + #definition re-bases the embedded source indentation - the G-045 mechanism for + #string-built definitions, which get no automatic whole-block indent + #normalization (head-form values here would leak this file's indentation into + #the rendered Description column). variable HELPTEXTS { project - "Run the full project build - includes src/vfs/* checks and builds. + " + Run the full project build - includes src/vfs/* checks and builds. Builds/copies .tm modules and pkgIndex.tcl based libraries from src to /modules, /lib etc, propagates declared vendored platform-libraries into kit vfs trees (as for vfslibs), then scans src/runtime and src/vfs folders to build kit/zipkit executables and installs them to /bin." packages - "Build (or copy if build not required) both .tm and pkgIndex.tcl based + " + Build (or copy if build not required) both .tm and pkgIndex.tcl based packages from src to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." modules - "Build (or copy if build not required) .tm modules from src/modules, + " + Build (or copy if build not required) .tm modules from src/modules, src/vendormodules etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." libs - "Build (or copy if build not required) pkgIndex.tcl based libraries from + " + Build (or copy if build not required) pkgIndex.tcl based libraries from src/lib, src/vendorlib etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." vfs - "Scan src/vfs and src/runtime folders and build kit/zipkit executables + " + Scan src/vfs and src/runtime folders and build kit/zipkit executables into /bin. Does not first rebuild modules/libs - use 'make.tcl project' for the full pipeline." vfslibs - "Propagate declared vendored platform-library packages into kit vfs + " + Propagate declared vendored platform-library packages into kit vfs lib_tcl trees. Declarations (per-package per-kit, with superseded-version removal) live in src/runtime/vendorlib_vfs.toml. Also runs automatically as part of 'make.tcl project'." bin - "Install executables from src/bin to /bin, then check vfs + " + Install executables from src/bin to /bin, then check vfs folders and build kit/zipkit executables as for the vfs subcommand." vendorupdate - "Update the src/vendormodules based on src/vendormodules/include_modules.config. + " + Update the src/vendormodules based on src/vendormodules/include_modules.config. Update the src/vendorlib based on src/vendorlib/config.toml (todo)." bootsupport - "Update the src/bootsupport modules as well as the project-layout + " + Update the src/bootsupport modules as well as the project-layout src/bootsupport modules if those folders exist. Bootsupport modules are pulled from locations specified in include_modules.config files within each src/bootsupport subdirectory. @@ -1553,20 +1568,24 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO /modules, /lib etc. Bootsupport modules are available to make.tcl." vfscommonupdate - "Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. + " + Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. Before calling this (followed by 'make.tcl project') - you can test using '(.exe) dev' - this will load modules from your /modules, /lib paths instead of from the kit/zipkit. Replacing the _vfscommon.vfs contents requires confirmation - see -confirm." info - "Show the name and base folder of the project to be built." + " + Show the name and base folder of the project to be built." check - "Show module/library paths and any potentially problematic packages for + " + Show module/library paths and any potentially problematic packages for running this script. Also reports bootsupport staleness and the src provenance status (what the build/promotion commands would do)." projectversion - "Advisory check: verify CHANGELOG.md matches punkproject.toml and warn + " + Advisory check: verify CHANGELOG.md matches punkproject.toml and warn if src/ has changes since the last project-version bump." } #shared option fragments composed into the per-subcommand definitions below @@ -1634,6 +1653,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } set defparts [list] lappend defparts "@id -id (script)::punkboot::$sub" + lappend defparts "@normalize" ;#G-045 block-form value re-basing for constructed definitions lappend defparts "@cmd -name [list "make.tcl $sub"] -summary [list [dict get $SUMMARIES $sub]] -help [list [dict get $HELPTEXTS $sub]]" lappend defparts "@form -synopsis [list [join $synparts { }]]" lappend defparts "@opts" @@ -1645,8 +1665,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot::shell"\ + "@normalize"\ "@cmd -name [list "make.tcl shell"] -summary [list [dict get $SUMMARIES shell]] -help [list\ - "Run the punk shell (repl) using bootsupport libraries. + " + Run the punk shell (repl) using bootsupport libraries. All arguments after the shell subcommand are passed through to the repl untouched (they are not parsed or validated by make.tcl)."]"\ {@form -synopsis "make.tcl shell ?arg ...?"}\ @@ -1655,8 +1677,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "Arguments passed through to the punk repl."} punk::args::define\ "@id -id (script)::punkboot::help"\ + "@normalize"\ "@cmd -name [list "make.tcl help"] -summary [list [dict get $SUMMARIES help]] -help [list\ - "Show tabled usage for make.tcl as a whole, or for a single subcommand. + " + Show tabled usage for make.tcl as a whole, or for a single subcommand. Equivalent to 'make.tcl -help'."]"\ {@form -synopsis "make.tcl help ?subcommand?"}\ "@values -min 1 -max 1"\ @@ -1670,8 +1694,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot"\ + "@normalize"\ "@cmd -name make.tcl -summary {punkshell project build tool (punk boot)} -help [list\ - "punk boot: make any tclkits and modules in /src folders and place + " + punk boot: make any tclkits and modules in /src folders and place them and associated data files/scripts in the parent folder of src - e.g in 'bin' and 'modules' folders at the same level as 'src'. @@ -1684,6 +1710,14 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "@leaders -min 1 -max 1"\ "subcommand -type string -optional 0 -choicecolumns 1 -choicegroups [list $SUBGROUPS] -choicelabels [list $SUMMARIES] -help\ {Use 'make.tcl help ' or 'make.tcl -help' for details of a subcommand.}" + #capability probe: force resolution of representative definitions now, inside + #the guarded block - a stale punk::args that accepted the raw text but cannot + #resolve a mechanism used here (e.g pre-@normalize snapshots) degrades to the + #plain fallback immediately instead of erroring at first parse/usage. + punk::args::get_spec (script)::punkboot + punk::args::get_spec (script)::punkboot::project + punk::args::get_spec (script)::punkboot::help + punk::args::get_spec (script)::punkboot::shell unset -nocomplain sub optvars defparts ov } } _defserr]} { diff --git a/src/project_layouts/custom/_project/punk.project-0.1/src/make.tcl b/src/project_layouts/custom/_project/punk.project-0.1/src/make.tcl index b46d54cf..4fa7b856 100644 --- a/src/project_layouts/custom/_project/punk.project-0.1/src/make.tcl +++ b/src/project_layouts/custom/_project/punk.project-0.1/src/make.tcl @@ -1503,49 +1503,64 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO shell "Run the punk shell using bootsupport libraries" help "Show usage for make.tcl or one of its subcommands" } + #@cmd -help bodies for the constructed definitions below. Authored BLOCK-FORM + #(first value line whitespace-only) so the @normalize directive in each + #definition re-bases the embedded source indentation - the G-045 mechanism for + #string-built definitions, which get no automatic whole-block indent + #normalization (head-form values here would leak this file's indentation into + #the rendered Description column). variable HELPTEXTS { project - "Run the full project build - includes src/vfs/* checks and builds. + " + Run the full project build - includes src/vfs/* checks and builds. Builds/copies .tm modules and pkgIndex.tcl based libraries from src to /modules, /lib etc, propagates declared vendored platform-libraries into kit vfs trees (as for vfslibs), then scans src/runtime and src/vfs folders to build kit/zipkit executables and installs them to /bin." packages - "Build (or copy if build not required) both .tm and pkgIndex.tcl based + " + Build (or copy if build not required) both .tm and pkgIndex.tcl based packages from src to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." modules - "Build (or copy if build not required) .tm modules from src/modules, + " + Build (or copy if build not required) .tm modules from src/modules, src/vendormodules etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." libs - "Build (or copy if build not required) pkgIndex.tcl based libraries from + " + Build (or copy if build not required) pkgIndex.tcl based libraries from src/lib, src/vendorlib etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." vfs - "Scan src/vfs and src/runtime folders and build kit/zipkit executables + " + Scan src/vfs and src/runtime folders and build kit/zipkit executables into /bin. Does not first rebuild modules/libs - use 'make.tcl project' for the full pipeline." vfslibs - "Propagate declared vendored platform-library packages into kit vfs + " + Propagate declared vendored platform-library packages into kit vfs lib_tcl trees. Declarations (per-package per-kit, with superseded-version removal) live in src/runtime/vendorlib_vfs.toml. Also runs automatically as part of 'make.tcl project'." bin - "Install executables from src/bin to /bin, then check vfs + " + Install executables from src/bin to /bin, then check vfs folders and build kit/zipkit executables as for the vfs subcommand." vendorupdate - "Update the src/vendormodules based on src/vendormodules/include_modules.config. + " + Update the src/vendormodules based on src/vendormodules/include_modules.config. Update the src/vendorlib based on src/vendorlib/config.toml (todo)." bootsupport - "Update the src/bootsupport modules as well as the project-layout + " + Update the src/bootsupport modules as well as the project-layout src/bootsupport modules if those folders exist. Bootsupport modules are pulled from locations specified in include_modules.config files within each src/bootsupport subdirectory. @@ -1553,20 +1568,24 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO /modules, /lib etc. Bootsupport modules are available to make.tcl." vfscommonupdate - "Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. + " + Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. Before calling this (followed by 'make.tcl project') - you can test using '(.exe) dev' - this will load modules from your /modules, /lib paths instead of from the kit/zipkit. Replacing the _vfscommon.vfs contents requires confirmation - see -confirm." info - "Show the name and base folder of the project to be built." + " + Show the name and base folder of the project to be built." check - "Show module/library paths and any potentially problematic packages for + " + Show module/library paths and any potentially problematic packages for running this script. Also reports bootsupport staleness and the src provenance status (what the build/promotion commands would do)." projectversion - "Advisory check: verify CHANGELOG.md matches punkproject.toml and warn + " + Advisory check: verify CHANGELOG.md matches punkproject.toml and warn if src/ has changes since the last project-version bump." } #shared option fragments composed into the per-subcommand definitions below @@ -1634,6 +1653,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } set defparts [list] lappend defparts "@id -id (script)::punkboot::$sub" + lappend defparts "@normalize" ;#G-045 block-form value re-basing for constructed definitions lappend defparts "@cmd -name [list "make.tcl $sub"] -summary [list [dict get $SUMMARIES $sub]] -help [list [dict get $HELPTEXTS $sub]]" lappend defparts "@form -synopsis [list [join $synparts { }]]" lappend defparts "@opts" @@ -1645,8 +1665,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot::shell"\ + "@normalize"\ "@cmd -name [list "make.tcl shell"] -summary [list [dict get $SUMMARIES shell]] -help [list\ - "Run the punk shell (repl) using bootsupport libraries. + " + Run the punk shell (repl) using bootsupport libraries. All arguments after the shell subcommand are passed through to the repl untouched (they are not parsed or validated by make.tcl)."]"\ {@form -synopsis "make.tcl shell ?arg ...?"}\ @@ -1655,8 +1677,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "Arguments passed through to the punk repl."} punk::args::define\ "@id -id (script)::punkboot::help"\ + "@normalize"\ "@cmd -name [list "make.tcl help"] -summary [list [dict get $SUMMARIES help]] -help [list\ - "Show tabled usage for make.tcl as a whole, or for a single subcommand. + " + Show tabled usage for make.tcl as a whole, or for a single subcommand. Equivalent to 'make.tcl -help'."]"\ {@form -synopsis "make.tcl help ?subcommand?"}\ "@values -min 1 -max 1"\ @@ -1670,8 +1694,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot"\ + "@normalize"\ "@cmd -name make.tcl -summary {punkshell project build tool (punk boot)} -help [list\ - "punk boot: make any tclkits and modules in /src folders and place + " + punk boot: make any tclkits and modules in /src folders and place them and associated data files/scripts in the parent folder of src - e.g in 'bin' and 'modules' folders at the same level as 'src'. @@ -1684,6 +1710,14 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "@leaders -min 1 -max 1"\ "subcommand -type string -optional 0 -choicecolumns 1 -choicegroups [list $SUBGROUPS] -choicelabels [list $SUMMARIES] -help\ {Use 'make.tcl help ' or 'make.tcl -help' for details of a subcommand.}" + #capability probe: force resolution of representative definitions now, inside + #the guarded block - a stale punk::args that accepted the raw text but cannot + #resolve a mechanism used here (e.g pre-@normalize snapshots) degrades to the + #plain fallback immediately instead of erroring at first parse/usage. + punk::args::get_spec (script)::punkboot + punk::args::get_spec (script)::punkboot::project + punk::args::get_spec (script)::punkboot::help + punk::args::get_spec (script)::punkboot::shell unset -nocomplain sub optvars defparts ov } } _defserr]} { diff --git a/src/project_layouts/custom/_project/punk.shell-0.1/src/make.tcl b/src/project_layouts/custom/_project/punk.shell-0.1/src/make.tcl index b46d54cf..4fa7b856 100644 --- a/src/project_layouts/custom/_project/punk.shell-0.1/src/make.tcl +++ b/src/project_layouts/custom/_project/punk.shell-0.1/src/make.tcl @@ -1503,49 +1503,64 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO shell "Run the punk shell using bootsupport libraries" help "Show usage for make.tcl or one of its subcommands" } + #@cmd -help bodies for the constructed definitions below. Authored BLOCK-FORM + #(first value line whitespace-only) so the @normalize directive in each + #definition re-bases the embedded source indentation - the G-045 mechanism for + #string-built definitions, which get no automatic whole-block indent + #normalization (head-form values here would leak this file's indentation into + #the rendered Description column). variable HELPTEXTS { project - "Run the full project build - includes src/vfs/* checks and builds. + " + Run the full project build - includes src/vfs/* checks and builds. Builds/copies .tm modules and pkgIndex.tcl based libraries from src to /modules, /lib etc, propagates declared vendored platform-libraries into kit vfs trees (as for vfslibs), then scans src/runtime and src/vfs folders to build kit/zipkit executables and installs them to /bin." packages - "Build (or copy if build not required) both .tm and pkgIndex.tcl based + " + Build (or copy if build not required) both .tm and pkgIndex.tcl based packages from src to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." modules - "Build (or copy if build not required) .tm modules from src/modules, + " + Build (or copy if build not required) .tm modules from src/modules, src/vendormodules etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." libs - "Build (or copy if build not required) pkgIndex.tcl based libraries from + " + Build (or copy if build not required) pkgIndex.tcl based libraries from src/lib, src/vendorlib etc to their corresponding locations under . This does not scan src/runtime and src/vfs folders to build kit/zipkit executables." vfs - "Scan src/vfs and src/runtime folders and build kit/zipkit executables + " + Scan src/vfs and src/runtime folders and build kit/zipkit executables into /bin. Does not first rebuild modules/libs - use 'make.tcl project' for the full pipeline." vfslibs - "Propagate declared vendored platform-library packages into kit vfs + " + Propagate declared vendored platform-library packages into kit vfs lib_tcl trees. Declarations (per-package per-kit, with superseded-version removal) live in src/runtime/vendorlib_vfs.toml. Also runs automatically as part of 'make.tcl project'." bin - "Install executables from src/bin to /bin, then check vfs + " + Install executables from src/bin to /bin, then check vfs folders and build kit/zipkit executables as for the vfs subcommand." vendorupdate - "Update the src/vendormodules based on src/vendormodules/include_modules.config. + " + Update the src/vendormodules based on src/vendormodules/include_modules.config. Update the src/vendorlib based on src/vendorlib/config.toml (todo)." bootsupport - "Update the src/bootsupport modules as well as the project-layout + " + Update the src/bootsupport modules as well as the project-layout src/bootsupport modules if those folders exist. Bootsupport modules are pulled from locations specified in include_modules.config files within each src/bootsupport subdirectory. @@ -1553,20 +1568,24 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO /modules, /lib etc. Bootsupport modules are available to make.tcl." vfscommonupdate - "Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. + " + Update the src/vfs/_vfscommon.vfs from compiled src/modules and src/lib etc. Before calling this (followed by 'make.tcl project') - you can test using '(.exe) dev' - this will load modules from your /modules, /lib paths instead of from the kit/zipkit. Replacing the _vfscommon.vfs contents requires confirmation - see -confirm." info - "Show the name and base folder of the project to be built." + " + Show the name and base folder of the project to be built." check - "Show module/library paths and any potentially problematic packages for + " + Show module/library paths and any potentially problematic packages for running this script. Also reports bootsupport staleness and the src provenance status (what the build/promotion commands would do)." projectversion - "Advisory check: verify CHANGELOG.md matches punkproject.toml and warn + " + Advisory check: verify CHANGELOG.md matches punkproject.toml and warn if src/ has changes since the last project-version bump." } #shared option fragments composed into the per-subcommand definitions below @@ -1634,6 +1653,7 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } set defparts [list] lappend defparts "@id -id (script)::punkboot::$sub" + lappend defparts "@normalize" ;#G-045 block-form value re-basing for constructed definitions lappend defparts "@cmd -name [list "make.tcl $sub"] -summary [list [dict get $SUMMARIES $sub]] -help [list [dict get $HELPTEXTS $sub]]" lappend defparts "@form -synopsis [list [join $synparts { }]]" lappend defparts "@opts" @@ -1645,8 +1665,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot::shell"\ + "@normalize"\ "@cmd -name [list "make.tcl shell"] -summary [list [dict get $SUMMARIES shell]] -help [list\ - "Run the punk shell (repl) using bootsupport libraries. + " + Run the punk shell (repl) using bootsupport libraries. All arguments after the shell subcommand are passed through to the repl untouched (they are not parsed or validated by make.tcl)."]"\ {@form -synopsis "make.tcl shell ?arg ...?"}\ @@ -1655,8 +1677,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "Arguments passed through to the punk repl."} punk::args::define\ "@id -id (script)::punkboot::help"\ + "@normalize"\ "@cmd -name [list "make.tcl help"] -summary [list [dict get $SUMMARIES help]] -help [list\ - "Show tabled usage for make.tcl as a whole, or for a single subcommand. + " + Show tabled usage for make.tcl as a whole, or for a single subcommand. Equivalent to 'make.tcl -help'."]"\ {@form -synopsis "make.tcl help ?subcommand?"}\ "@values -min 1 -max 1"\ @@ -1670,8 +1694,10 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO } punk::args::define\ "@id -id (script)::punkboot"\ + "@normalize"\ "@cmd -name make.tcl -summary {punkshell project build tool (punk boot)} -help [list\ - "punk boot: make any tclkits and modules in /src folders and place + " + punk boot: make any tclkits and modules in /src folders and place them and associated data files/scripts in the parent folder of src - e.g in 'bin' and 'modules' folders at the same level as 'src'. @@ -1684,6 +1710,14 @@ if {[info exists ::env(PUNKBOOT_PLAIN)] && [string is true -strict $::env(PUNKBO "@leaders -min 1 -max 1"\ "subcommand -type string -optional 0 -choicecolumns 1 -choicegroups [list $SUBGROUPS] -choicelabels [list $SUMMARIES] -help\ {Use 'make.tcl help ' or 'make.tcl -help' for details of a subcommand.}" + #capability probe: force resolution of representative definitions now, inside + #the guarded block - a stale punk::args that accepted the raw text but cannot + #resolve a mechanism used here (e.g pre-@normalize snapshots) degrades to the + #plain fallback immediately instead of erroring at first parse/usage. + punk::args::get_spec (script)::punkboot + punk::args::get_spec (script)::punkboot::project + punk::args::get_spec (script)::punkboot::help + punk::args::get_spec (script)::punkboot::shell unset -nocomplain sub optvars defparts ov } } _defserr]} {