punkbin/AGENTS.md

punkbin — punkshell binary artifact repository

Purpose

Pinned binary artifacts for the punkshell project (github/gitea: jn/shellspy - the project is punkshell; "shellspy" is a legacy repo name): per-platform Tcl runtime executables used as the basis for building punkshell kits/zipkits, plus selected build tools. This repository exists so that build and test environments can retrieve exact, checksummed runtime binaries instead of depending on moving upstream releases (e.g. beta runtimes such as tclsfe-x64.exe from github.com/apnadkarni/tcl-sfe) or on binaries that exist only on one developer machine.

This artifact repository is specific to the punkshell project.

Ownership

• Owned by the punkshell project maintainer.
• Agents may add artifacts and update checksums when the punkshell project work calls for it (e.g. preserving a runtime that punkshell tests depend on) - report additions in the completion summary.
• Agents must not modify or delete existing binaries; superseding a runtime means adding the new file, not overwriting the old one.

Local Contracts

• Layout: one folder per platform (win32-x86_64/, linux-x86_64/, linux-arm/, macosx/, freebsd-arm64/, ...), optional tools/ subfolders for build tooling (e.g. zig archives). src/ holds maintenance scripts for this repository itself. Platform folder names follow the punkshell canonical platform names (punk::platform module / help platforms in the punk shell).
• platforms.txt at the repo root lists the platform folders this repo serves (one name per line; # comments and blanks ignored) - the discovery manifest for raw-file consumers that have no directory-listing capability (punk-runtime.cmd platforms -remote, and third-party mirrors using the same layout should carry the same file). Regenerated by src/build_sha1sums.tcl.
• defaults.txt at the repo root is the CURATED per-platform recommended default fetch runtime (<platform> <runtimename> per line; # comments/blanks ignored) consulted by punk-runtime.cmd fetch when no runtime name is given. Hand-edited, never generated - it records a release DECISION. The release process: publish the artifact (add, git add, run src/build_sha1sums.tcl), then point the platform's defaults.txt line at it IN THE SAME CHANGE-SET - the script validates entries (warns on unknown platforms or missing artifact files) so drift between the halves is caught. A platform with no line has no recommendation (punk-runtime tells the user to name a runtime explicitly). Mirrors may curate their own recommendations.
• Every platform folder (and tool subfolder) carries a sha1sums.txt with one <sha1> *<filename> line per artifact (binary-mode marker *).
• sha1sums.txt (and platforms.txt) are regenerated with tclsh src/build_sha1sums.tcl from the repo root. The script only sums git-tracked files - git add a new artifact BEFORE running it. It reports NEW/SAME/CHANGED per file; a CHANGED line for an existing artifact is a red flag (artifacts are immutable - investigate, don't commit).
• Binaries are deliberately committed here - this repo is the exception to the punkshell source repo's no-committed-binaries direction (shellspy G-004): the source repo points at this one (G-006 retrieval direction) instead of carrying binaries itself.
• Runtime expectations (see README.md): self-contained Tcl interpreters usable as kit bases; punk runtimes load Tk as an extension (no separate Tk runtime). Runtimes with statically-linked packages (e.g. tclsfe-x64.exe: Thread, twapi, sqlite3, tdbc) are supported by punkshell boot as of shellspy G-058.

Work Guidance

• Adding a runtime: copy it into the platform folder, git add it, run tclsh src/build_sha1sums.tcl, verify the NEW line's checksum, commit with a message recording provenance (upstream URL/version/build source).
• Consumers: the punkshell project retrieves runtimes into its bin/runtime/<platform>/ via bin/runtime.cmd or manual copy; punkshell's src/runtime/mapvfs.config maps runtimes to vfs payloads.
• Do not push on an agent's initiative - the remote is the project's upstream artifact store; the maintainer controls what is published.

Verification

• tclsh src/build_sha1sums.tcl reports SAME for every pre-existing artifact and NEW only for intended additions.

Child DOX Index

(None - flat platform folders with artifacts, checksums and README.md; src/ is a single maintenance script.)