From 935f597c0bccdfef6a1af4a1afd02e9c5829e590 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 7 Jul 2026 15:37:57 +1000 Subject: [PATCH] script subcommand: core-command doc parity (i list works in piped scripts) app-punkscript loads punk::args::moduledoc::tclcore (catch-guarded, mirroring the punk::repl code-interp setup) so core Tcl commands are documented in script runs as at the repl: `''i list'' | punkexe script` now renders the doc table instead of "Undocumented command". Cost ~40ms; kit script startup ~0.33s. REVIEW note added: the default-punk-shell package set is now expressed in app-punkscript AND the repl codethread setup - consolidation into one shared definition is the G-015-noted follow-on. punk::packagepreference 0.1.1: moduledoc auto-load success notice moved stdout -> stderr (stdout must stay machine-clean for script/exec contexts; the failure branch already used stderr). Verified on both generations (punk902z, punksys): i list doc table on stdout, notice on stderr, timing unchanged. Build-order footnote: lib changes need make.tcl libs before vfscommonupdate - the modules-only first rebuild shipped a stale app-punkscript payload. Project version 0.3.1. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- CHANGELOG.md | 5 +++++ punkproject.toml | 2 +- src/lib/app-punkscript/punkscript.tcl | 7 +++++++ src/modules/punk/packagepreference-999999.0a1.0.tm | 4 +++- src/modules/punk/packagepreference-buildversion.txt | 3 ++- .../_vfscommon.vfs/lib/app-punkscript/punkscript.tcl | 7 +++++++ ...epreference-0.1.0.tm => packagepreference-0.1.1.tm} | 10 ++++++---- 7 files changed, 31 insertions(+), 7 deletions(-) rename src/vfs/_vfscommon.vfs/modules/punk/{packagepreference-0.1.0.tm => packagepreference-0.1.1.tm} (98%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0952917e..97d06f8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ 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.3.1] - 2026-07-07 + +- `script` subcommand: core-command documentation parity with the interactive shell — app-punkscript now loads `punk::args::moduledoc::tclcore` (catch-guarded, ~40ms) so e.g. `'i list' | punkexe script` renders the doc table instead of "Undocumented command". Verified on both generations; kit startup ~0.33s. +- punk::packagepreference 0.1.1: the moduledoc auto-load success notice moved from stdout to stderr — stdout must stay clean for script/exec contexts (the failure branch already used stderr). + ## [0.3.0] - 2026-07-07 - ` script` completed (goal G-015 achieved): runs a script file (`script ?args?`, conventional ::argv0/::argv) or the whole of piped stdin (` | script` — no trailing `exit` needed) in the default punk shell module/alias environment, so one-liners like `dev projects.work *name*` work with no boilerplate. Honest exit codes (0 success, 1 error with errorInfo on stderr, script's own `exit` honoured); no shellfilter transforms or logging side effects; never falls into an interactive shell. Implemented as the lean `app-punkscript` package; the stdin form echoes the script's final result when non-empty. Verified on both Tcl generations (punk902z, punksys). diff --git a/punkproject.toml b/punkproject.toml index 0393c330..f2853bf9 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,3 +1,3 @@ [project] name = "punkshell" -version = "0.3.0" +version = "0.3.1" diff --git a/src/lib/app-punkscript/punkscript.tcl b/src/lib/app-punkscript/punkscript.tcl index 1d7dbc31..a76c3ab2 100644 --- a/src/lib/app-punkscript/punkscript.tcl +++ b/src/lib/app-punkscript/punkscript.tcl @@ -36,6 +36,13 @@ apply {{} { package require punk package require punk::aliascore punk::aliascore::init + #documentation parity with the interactive shell: core-command docs so e.g + #'i list' works in piped scripts as it does at the repl (mirrors the + #punk::repl code-interp setup - highly desirable, not critical). + #REVIEW: the 'default punk shell environment' package set is now expressed + #here AND in punk::repl's codethread setup - consolidation into one shared + #definition is the G-015-noted follow-on (G-031 territory). + catch {package require punk::args::moduledoc::tclcore} set arglist $::argv if {[llength $arglist]} { diff --git a/src/modules/punk/packagepreference-999999.0a1.0.tm b/src/modules/punk/packagepreference-999999.0a1.0.tm index 7cc16ef0..ff58a76b 100644 --- a/src/modules/punk/packagepreference-999999.0a1.0.tm +++ b/src/modules/punk/packagepreference-999999.0a1.0.tm @@ -321,7 +321,9 @@ tcl::namespace::eval punk::packagepreference { if {[catch {thread::id} threadid]} { set threadid "unknown-threadid" } - puts stdout "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid" + #notice goes to stderr: stdout must stay clean for script/exec contexts + #(e.g the punk executable's 'script' subcommand - machine-consumed output) + puts stderr "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid" } } #--------------------------------------------------------------- diff --git a/src/modules/punk/packagepreference-buildversion.txt b/src/modules/punk/packagepreference-buildversion.txt index f47d01c8..b0df4036 100644 --- a/src/modules/punk/packagepreference-buildversion.txt +++ b/src/modules/punk/packagepreference-buildversion.txt @@ -1,3 +1,4 @@ -0.1.0 +0.1.1 #First line must be a semantic version number #all other lines are ignored. +#0.1.1 - moduledoc auto-load success notice moved from stdout to stderr (stdout must stay clean for script/exec contexts e.g the punk 'script' subcommand; failure branch already used stderr) diff --git a/src/vfs/_vfscommon.vfs/lib/app-punkscript/punkscript.tcl b/src/vfs/_vfscommon.vfs/lib/app-punkscript/punkscript.tcl index 1d7dbc31..a76c3ab2 100644 --- a/src/vfs/_vfscommon.vfs/lib/app-punkscript/punkscript.tcl +++ b/src/vfs/_vfscommon.vfs/lib/app-punkscript/punkscript.tcl @@ -36,6 +36,13 @@ apply {{} { package require punk package require punk::aliascore punk::aliascore::init + #documentation parity with the interactive shell: core-command docs so e.g + #'i list' works in piped scripts as it does at the repl (mirrors the + #punk::repl code-interp setup - highly desirable, not critical). + #REVIEW: the 'default punk shell environment' package set is now expressed + #here AND in punk::repl's codethread setup - consolidation into one shared + #definition is the G-015-noted follow-on (G-031 territory). + catch {package require punk::args::moduledoc::tclcore} set arglist $::argv if {[llength $arglist]} { diff --git a/src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.0.tm b/src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.1.tm similarity index 98% rename from src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.0.tm rename to src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.1.tm index 38b1f3fd..8ad1d774 100644 --- a/src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.0.tm +++ b/src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.1.tm @@ -8,7 +8,7 @@ # (C) 2024 # # @@ Meta Begin -# Application punk::packagepreference 0.1.0 +# Application punk::packagepreference 0.1.1 # Meta platform tcl # Meta license # @@ Meta End @@ -18,7 +18,7 @@ # doctools header # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ #*** !doctools -#[manpage_begin punkshell_module_punk::packagepreference 0 0.1.0] +#[manpage_begin punkshell_module_punk::packagepreference 0 0.1.1] #[copyright "2024"] #[titledesc {punkshell package/module loading}] [comment {-- Name section and table of contents description --}] #[moddesc {package/module load}] [comment {-- Description at end of page heading --}] @@ -321,7 +321,9 @@ tcl::namespace::eval punk::packagepreference { if {[catch {thread::id} threadid]} { set threadid "unknown-threadid" } - puts stdout "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid" + #notice goes to stderr: stdout must stay clean for script/exec contexts + #(e.g the punk executable's 'script' subcommand - machine-consumed output) + puts stderr "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid" } } #--------------------------------------------------------------- @@ -487,7 +489,7 @@ namespace eval ::punk::args::register { package provide punk::packagepreference [tcl::namespace::eval punk::packagepreference { variable pkg punk::packagepreference variable version - set version 0.1.0 + set version 0.1.1 }] return