# bin/ ## Purpose Built punk shell executables (kits with the punk boot layer), assorted build/experiment tooling, and plain runtime kits under `runtime/`. Executables here are build outputs - agents do not hand-edit binaries. ### Generated polyglot .cmd scripts - never edit in place The `.cmd` scripts here (e.g `runtime.cmd`) are punk MULTISHELL polyglots GENERATED by `punk::mix::commandset::scriptwrap::multishell` from scriptset sources under `src/scriptapps/bin/` (the home for bin-deployed scriptsets, e.g `runtime.*` alongside `getzig.*`) or `src/scriptapps/` itself (e.g `tclargs.*`, `dtplite.*`): payload scripts (`.ps1`, `.bash`, `.tcl`, ...) plus a `_wrap.toml` config, spliced into the `punk.multishell.cmd` template. The polyglot structure is deliberately fragile (mutual shell-hiding tricks, LF-only endings, cmd.exe's 512-byte label-scanner constraints) - a hand-edit can silently break one of the participating shells. When asked to "fix bin/.cmd": 1. Edit the payload/config sources under `src/scriptapps/bin/` (never the output file). 2. Re-wrap from the scriptset's folder: cd `src/scriptapps/bin` then `punk::mix::commandset::scriptwrap::multishell -askme 0` (output defaults to `/bin`; requires Thread + the punk::mix modules, e.g a punk shell or a tclsh with project module paths). 3. The wrapper runs `checkfile` (the 512-byte label/boundary validator) automatically - heed ERROR output; "possibly bogus target" warnings are normal for polyglots. Payload growth can push a TEMPLATE label beyond the payloads (e.g `:exit_multishell`) across a 512-byte boundary: fix by resizing the byte-alignment spacer comment at the end of the affected payload (see the `(512B spacer)` comment in `runtime.bash`) and re-wrapping until checkfile is ERROR-free. 4. Commit source AND regenerated output together: the scriptwrap test suite pins that a re-wrap of the runtime scriptset reproduces `bin/runtime.cmd` byte for byte (`src/tests/modules/punk/mix/testsuites/scriptwrap/multishell.test` scriptwrap_runtime_cmd_roundtrip_no_drift), so drift in either direction fails tests. `bin/dtplite.cmd` is pinned the same way (`src/tests/shell/testsuites/binscripts/dtplite.test` dtplite_cmd_roundtrip_no_drift). ### dtplite (`dtplite.cmd`) `bin/dtplite.cmd` wraps tcllib's dtplite doctools processor (payload `src/scriptapps/dtplite.tcl`, tclsh nextshell on all platforms). It exists so the punk repl's unknown-handler can resolve the bare `dtplite` command via PATH - `dev doc.validate` (punk::mix::commandset::doc) depends on it. The payload falls back to the project-vendored tcllib (`src/vendorlib_tcl9//tcllib*`) when the invoking tclsh has no dtplite package installed. ## Local Contracts ### Launch package modes (built punk shells) The first argument to a built punk shell may be a dash-delimited package mode composed of tokens from `dev`, `os`, `src`, `internal` (e.g. `punksys src`, `punk902z dev-os`). `internal` is the default and is always appended when absent. A first argument that is not a valid mode list is treated as a subcommand instead. Implementation: `src/vfs/_config/punk_main.tcl` (search `all_package_modes`). `src` mode is the one that matters for verifying working-tree changes: - Discovers the project root from the executable's location (exe in `bin/` -> parent directory), not from the cwd - it works from any working directory as long as the executable resides in the project's `bin/`. - Prepends `src/modules`, `src/modules_tcl`, `src/bootsupport/modules{,_tcl}` and `src/vendormodules{,_tcl}` to the module path, sets `package prefer latest` so dev-numbered `999999.0a1.0` source modules beat kit-stamped snapshots on unversioned `package require`, and registers `#modpod` modules from `src/modules` (startup notice: `src mode: registered N #modpod modules from .../src/modules`). - Consequence: `punksys src` / `punk902z src` exercises current working-tree source with no kit rebuild; a plain launch (`punksys`) exercises the module snapshots baked into the kit at build time. `package present ` reporting `999999.0a1.0` (vs a release version like `0.7.1`) tells you which set a session is running - runbooks with version expectations must state the intended launch mode. ### Runtime fetch/selection (`runtime.cmd`) `bin/runtime.cmd {fetch|list|use|run}` manages the plain runtimes under `bin/runtime//` (retrieved from the punkbin artifact repo with sha1 verification against its `sha1sums.txt` - both the powershell payload on windows and the bash payload on unix verify; a fetch whose checksum fails leaves only a `.tmp`). `list -remote` compares local runtimes against the server's sha1sums (Same version / UPDATE AVAILABLE / not-listed, plus remote-only entries; the bash payload falls back to a cached sha1sums.txt with a warning when the server is unreachable). The artifact server base url is overridable via `PUNKBIN_URL` (mirrors/testing) in both payloads. Which runtime `run` launches is the per-machine "active" selection in `bin/runtime//active.toml` (constrained single-key toml `active = ""`, written by `runtime.cmd use `, marked in `list`, VCS-ignored via the existing `bin/*` globs). Resolution order for `run`: `PUNK_ACTIVE_RUNTIME` env override, then `active.toml`, then a sole installed candidate - with multiple runtimes and no selection it errors listing candidates rather than guessing. The first `fetch` sets the active runtime only when none is recorded. ### Interactive verification shells - Interactive console/repl verification should cover both Tcl generations - behaviour can differ materially (e.g. the Tcl 8.6 windows console channel driver vs the Tcl 9 rewrite). Use a Tcl 8.6-based punk shell (`punksys.exe`) and a current Tcl 9-based punk shell (named for the Tcl release it embeds, e.g. `punk902z.exe` at the time of writing - ask the user which is current rather than assuming). `info patchlevel` in-session confirms the runtime. - `runtime/win32-x86_64/` holds plain tclkits/tclsh runtimes without the punk boot layer - use these for clean-environment probes isolating Tcl-level behaviour from punk (they may lack extensions such as twapi; add an external lib dir to `auto_path` when a probe needs one). ## Work Guidance ## Verification None - build outputs; behaviour is verified via `src/tests/` and interactive runbooks. ## Child DOX Index - `runtime/win32-x86_64/` - plain runtime kits (no child AGENTS.md needed; covered by this file's contracts)