punkshell/src/scriptapps/AGENTS.md

src/scriptapps — Entry-Point Scripts for Punk Apps

Purpose

Standalone Tcl scripts that serve as entry points for Punk applications and utilities. Includes wrapper generators, runtime fetchers, build helpers, and test scripts for external languages.

Ownership

• Shared between maintainer and agents. Agents may edit when asked but should preserve the existing entry-point contract of each script.
• The wrappers/ subdirectory contains TOML configuration and generated wrapper scripts.

Local Contracts

• Scripts here are invoked directly by the user or by build tools, not loaded as packages.
• Wrapper configs (.toml files) define how scripts are packaged as platform executables.
• <name>_wrap.toml scriptsets are the SOURCE of the generated polyglot .cmd scripts in <projectroot>/bin, and bin-deployed scriptsets live in the bin/ subfolder here (e.g bin/runtime.ps1 + bin/runtime.bash + bin/runtime_wrap.toml -> <projectroot>/bin/runtime.cmd via punk::mix::commandset::scriptwrap::multishell runtime -askme 0, run from src/scriptapps/bin, alongside the getzig.* scriptset). Fixes to a bin/*.cmd polyglot are made in the scriptset sources and re-wrapped - never in the output file. Regenerate and commit the bin output together with payload changes: src/tests/modules/punk/mix/testsuites/scriptwrap/multishell.test pins the runtime scriptset round-trip byte-identical against bin/runtime.cmd.
• The spud/ directory holds the spud build tool's app scripts.
• The tools/ directory holds miscellaneous build and deployment utilities.

Work Guidance

• When adding a new script app, follow the naming pattern: <name>.tcl with optional <name>_wrap.toml.
• Test scripts for non-Tcl languages (bash, PowerShell, Perl, Python) live in test_bash/, test_pwsh/, etc.
• The bin/ subdirectory is not the same as the project root bin/; it holds app-specific launchers.

Verification

• Existing scripts run without import errors in the project environment.

Child DOX Index

• wrappers/ — TOML wrapper configs and generated wrappers
• spud/ — Spud build tool app scripts
• tools/ — Build and deployment utilities
• bin/ — App-specific launchers