punkshell/goals/archive/G-077-punkexe-dash-e-oneliner.md

G-077 punk executable -e one-liner support: make the tclsh-agent instinct work

Status: achieved 2026-08-04 Scope: src/vfs/_config/punk_main.tcl (top-level arg dispatch); src/lib/app-punkscript/punkscript.tcl (script subcommand arg forms); src/tests/shell/testsuites/punkexe/scriptexec.test Goal: <punkexe> -e <script> ?args...? and <punkexe> script -e <script> ?args...? execute the given Tcl code as a one-liner (args after the script land in ::argv, ::argv0 = -e, non-interactive), so the -e reflex agents carry over from perl/python/node works on punk kits instead of erroring - while stock-tclsh misparse behaviour (argv-swallow + stdin read) is never reproduced. Acceptance: punksys -e {puts hi} and punk902z script -e {puts hi} print hi and exit 0 with and without piped stdin present (the one-liner may itself read stdin); a -e with no following script argument is a usage error, never an interactive fall-through; error in the one-liner prints errorInfo to stderr and exits 1 (matching the script subcommand's file form); scriptexec.test covers the above against the built executable.

Context

Agents and harnesses habitually try tclsh -e "script" (the one-liner reflex from perl/python/node). Stock tclsh has no such flag: only -encoding name is recognised, and any other leading-dash argument is not treated as a script file - all arguments land in $argv and tclsh reads commands from stdin instead (hangs at an interactive prompt on a console; silently ignores the supposed one-liner when stdin is piped). Root AGENTS.md User Preferences documents the pitfall and a claude-harness PreToolUse hook (.claude/settings.json) denies such invocations with corrective guidance.

The punk kits currently fail fast instead (punk script: script file not found: '-e') but offer no one-liner form. This goal makes the instinct work on punk executables, removing the failure class for the kits entirely. app-punkscript's existing stdin form already provides the execution scaffolding (argv0/argv setup, errorInfo-to-stderr, exit-code discipline).

Notes

• G-118 relationship (recorded 2026-07-24 after overlap review; achieved 2026-07-25 - see goals/archive/G-118-tclsh-subcommand-review.md): G-118 settled the stock leading-dash fallthrough this goal must not disturb - <punkexe> tclsh -e ... deliberately keeps stock's -e misparse (stock parity is the tclsh subcommand's contract); the one-liner instinct is served only at the top level and via script -e. Its item-10 definitions state this boundary in the tclsh @cmd help (punk::args::moduledoc::punkexe, id (script)::punkexe::tclsh) - when this goal lands the top-level/script -e forms, update that boundary text to point at the live forms.
• G-032 (archived) shipped the dispatch surface this goal extends - see goals/archive/G-032-launcher-punkargs.md: a top-level -e today falls under the unknown-first-argument rule (no such file -> tabled usage refusal on stderr, exit 1
  • no more silent script attempt), and help flags as first argument are intercepted on unknownfirst=script kits. Landing -e means carving it out ahead of that refusal in the boot core's selection block (and updating the moduledoc (script)::punkexe help text + the refusal hint, which currently suggests ' script '). The (script)::punkexe::script definition is dispatch-rendered now - declare the -e form there so help stays true.
• Related: G-038 (piped-session continuity) - adjacent piped-stdin semantics: its Acceptance pins the script subcommand's existing behaviour unchanged; this goal adds a new arg form to that subcommand without altering the existing file/stdin forms, and its own Acceptance covers -e with piped stdin present.
• Related: G-131 (boot payload autodetection) - same-file neighbour: both edit src/vfs/_config/punk_main.tcl, but distinct blocks (its container detection vs this goal's arg-dispatch selection block) - coordinate edits.
• Activation freshness survey 2026-08-04 (goals_xref score G-077, run at the proposed->active flip on user command): G-163/G-162/G-141/G-158 are punkexe-test-dir / path-sibling neighbours only, judged not related in substance (G-141 and G-158 already record the same judgement from their side); G-042/G-017/G-067/G-021 term-only overlap, not related.

Progress

• 2026-08-04: activated on explicit user command and landed complete in one increment:
  • app-punkscript 1.0 -> 1.1 (src/lib/app-punkscript/punkscript.tcl + pkgIndex.tcl): the '-e