punkshell/goals/archive/G-015-script-subcommand-piped-stdin.md

G-015 Punk executable script subcommand: reliable non-interactive piped/script execution

Status: achieved 2026-07-07 Scope: src/vfs/_config/punk_main.tcl, src/lib/app-punkshell/punkshell.tcl (script path or a leaner dedicated app package) Goal: <punkexe> script [<scriptname>] [<args>...] executes a script file or piped stdin content (scriptname optional when input is piped) in an interp preloaded with the basic punk modules and aliases a punk shell provides by default, and always terminates with the script's success/failure as its exit code - without the shell subcommand's shellfilter channel transforms/logging stacks and without ever dropping into an interactive shell - so agents can reliably make piped script calls to punk executables. Acceptance: piping commands to <punkexe> script runs them and terminates at stdin EOF with no trailing exit required, exit code 0 on success; a failing piped command terminates the process with a nonzero exit code and the error on stderr, never landing in an interactive shell regardless of console availability or PUNK_PIPE_EOF; <punkexe> script <file> [<args>...] executes the file with conventional ::argv0/::argv and propagates its error status the same way; the script path installs none of the shell subcommand's shellfilter stacks/transforms and the launch plumbing itself emits nothing on stdout/stderr (the current stub's stderr diagnostics removed) so exec-style callers see only the script's own output; the motivating example works with no package require boilerplate: piping dev projects.work *<name>* to <punkexe> script emits the matching-project table and exits 0, because the script interp carries the default punk shell module/alias environment.

Context

Agents (and exec-style callers generally) currently have no reliable way to run a one-shot command against a punk executable. The working pattern is to pipe repl input into the default shell path, e.g. (powershell):

'dev projects.work *tomlish*;exit' | punk902z

This is fragile in two ways:

1. The trailing exit is load-bearing: without it, stdin EOF triggers the app-punkshell eof handling, whose default heuristic policy attempts to reopen the console (CONIN$ / /dev/tty) and drop into an interactive repl. When a console exists but no human is watching (typical agent/CI harness), that is a permanent hang. PUNK_PIPE_EOF=exit mitigates, but callers must know to set it.
2. If any command before the exit errors, the repl keeps consuming input and the exit line may never run as intended - the session can still land interactive, and the process exit code does not reflect the failure.

Meanwhile the script subcommand in the punk_main.tcl dispatch (src/vfs/_config/punk_main.tcl ~1163) is an incomplete stub: it prints stderr diagnostics ("main.tcl launching script with args: ...") and sets ::tcl_interactive, but never actually executes anything. Note also the dispatch default (~1090): any first argument that is not a recognised mode/subcommand is reclassified as script, so completing this path also completes the bare <punkexe> <somefile> form.

The shell subcommand path (app-punkshell) wraps the session in shellfilter channel stacks (punkshellout/punkshellerr with file/syslog logging targets, plus ansiwrap on stderr in places). Those transforms exist for interactive-shell ergonomics and logging; for a one-shot script call they add overhead, alter output, and risk stderr chatter - which matters because Tcl exec treats any stderr output as command failure by default (see the comment block in punk_main.tcl's punk subcommand case).

Approach

• Decided 2026-07-07: a leaner dedicated app package (not a mode of app-punkshell). Rationale: the acceptance is defined by absence (no shellfilter stacks, no logging side effects, no interactive fallback) which a package that never loads that machinery guarantees by construction; app-punkshell's load-time behaviour (shellfilter stacks with syslog/file targets writing punkshell_out.log/punkshell_err.log into the caller's cwd, logging threads) is wrong for one-shot calls; and isolation caps the blast radius of shell-path machinery (the 2026-07-06 silent-stdout failure lived in exactly the code reuse would couple to). Duplication mitigation: the substantive shared piece - the definition of the default punk shell module/alias environment - is factored into a shared module-level definition (punk::aliascore as the seed) consumed by both app packages; launcher control flow is deliberately not shared (share definitions via modules, not control flow). This package shape also previews the G-031 registration model (subcommand -> small handler package), as app-tomlish demonstrated.

• <punkexe> script <file> [<args>...] - execute the file with conventional ::argv0/::argv semantics, exit with its status.

• ... | <punkexe> script - read the whole of stdin as the script when no scriptname is supplied and stdin is piped/redirected; terminate at EOF, never reopening a console. The scriptname form must still work with piped stdin present (the script may itself want to read stdin) - "with or without a trailing scriptname".

• No shellfilter stacks/transforms on the script path; plain channels.

• No launcher output of its own on stdout or stderr (remove the stub diagnostics); the script's own output is the only output.

• Errors: report on stderr, exit nonzero. Success: exit 0 (or the script's own explicit exit code). No interactive fallback on this subcommand under any eof/error condition - PUNK_PIPE_EOF and console availability are irrelevant here by design.

• The script interp loads the basic punk modules and aliases that are available by default in an interactive punk shell, so commands like dev projects.work work in a piped one-liner with no package require boilerplate. This is deliberately not the leanest environment for basic scripts - fast/bare script execution is the future province of an expanded tclsh subcommand, out of scope here. The exact recommended one-liner gets documented under G-017.

Alternatives considered

• Hardening the shell/repl pipe path instead (PUNK_PIPE_EOF, error-aborts-input)
  • insufficient alone: the shell path's channel transforms and repl semantics are wrong for exec-style callers even when eof/error policy is fixed; a dedicated clean path is simpler than making the interactive path dual-purpose.
• Requiring agents to set PUNK_PIPE_EOF=exit and keep the trailing exit - rejected as the durable answer: it leaves exit codes meaningless on mid-script errors and depends on every caller knowing the incantation.
• A bare interp (no punk modules/aliases preloaded) for the script path - rejected for this subcommand: the point is that shell-default commands (dev projects.work etc.) work as piped one-liners; lean bare-script execution belongs to a later expansion of the tclsh subcommand.

Notes

• Achieved-status detail (restored 2026-07-11; this text originally rode the Status: line as a parenthetical and was dropped when the 2026-07-11 two-tier index restructure normalised detail-file Status lines to the bare index form): implemented as src/lib/app-punkscript; verified on punk902z/tcl9 and punksys/tcl8.6 kits: piped success/error/exit-code cases, file form with args and stdin passthrough, and the motivating dev projects.work *tomlish* one-liner - table emitted, exit 0, no boilerplate. Stdin form additionally echoes the script's final result when non-empty, giving return-value commands one-liner ergonomics; file form keeps pure script semantics. Terminal-stdin-with-no-args yields a usage error by design - spot-check from a real console typed session remains a manual item.
• Result-shape observation (2026-07-07): shellrun::runx -tcl returns a dict keyed {result stdout stderr} with NO exitcode key, unlike the exec-mode result (exitinfo with exitcode) - callers doing dict get $result exitcode error. Possibly by design for in-process eval, but the script-path work here should document (or normalise) the result shapes agents will consume.
• The eof policy machinery (PUNK_PIPE_EOF exit/interactive/heuristic) in app-punkshell (~punkshell.tcl 466-507) stays as-is for the shell subcommand; this goal does not change interactive-shell behaviour.
• Related later goal: G-016 extends what the motivating projects.work call can find; G-017 documents the agent-facing invocation pattern once this lands.