jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
813 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: 66df76c82e
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '66df76c82e'
${ noResults }
punkshell/goals/G-004-no-committed-binaries.md

4.9 KiB
Raw Blame History

G-004 No executable binaries committed to the repository

Status: proposed Scope: repo-wide (bin/, src/vfs/, src/vendorlib/, src/vendormodules/, src/bootsupport/) Goal: the committed repository contains no executable binaries; zip-based .tm modules are allowed but not if they embed executables. Acceptance: a scan of the committed tree finds no executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O); any zip-based .tm modules present contain no embedded executables; the binary artifacts previously committed are retrievable via G-005 (build from source) or G-006 (pre-built download) so their removal does not break builds.

Context

The ultimate aim is that the committed repository contains no executable binaries. This is a hygiene and reproducibility goal: binaries in version control are opaque to review, bloat the repo, and make the build non-reproducible from source. Today the repo violates this — binary libraries are committed in the VFS folders (src/vfs/), src/vendorlib/, src/vendormodules/, and src/bootsupport/. These are present because there is currently no automated way to rebuild or retrieve them; removing them before an alternative exists would break builds on a clean checkout.

Zip-based .tm modules are a permitted exception to the "no binaries" rule because they are module archives, not executables — but a zip-based .tm that embeds an executable (e.g. a native shared library packaged inside the module) is not permitted. The distinction is content, not file extension.

This goal is the integrating outcome of two enabling goals:

  • G-005 provides the build-from-source path (zig build of Tcl9 and other dependencies).
  • G-006 provides the pre-built download path with consent gating.

Both must be in place before the committed binaries can be removed without breaking builds, so G-004 sequences after both.

A standing repo-wide rule in root AGENTS.md (User Preferences) already directs agents not to commit new executable binaries, while explicitly not hassling the developer about existing vendor/vfs binaries committed pending this goal's achievement.

Approach

  1. Inventory. Identify every executable binary currently committed across bin/, src/vfs/, src/vendorlib/, src/vendormodules/, and src/bootsupport/. Classify each by what it is (Tcl9 shared lib, twapi, other native extension) and which goal path (G-005 build / G-006 download) will replace it.

  2. Verify alternatives work. Before removing any binary, confirm the corresponding G-005 build or G-006 download produces an artifact that satisfies the build. Removal without a working replacement breaks clean-checkout builds — the acceptance explicitly requires the alternative retrieval to work.

  3. Remove. Delete the committed binaries from the tree. Update .gitignore / .fossil-settings/ignore-glob if needed to prevent re-addition.

  4. Add a scan to verification. Add a scan step (script or make.tcl target) that checks the committed tree for executable binaries and fails if any are found, so regressions are caught. The scan must recognise the zip-based .tm exception: a .tm that is a zip is allowed; a .tm (or any zip) containing an embedded executable is not.

  5. DOX update. Once achieved, the AGENTS.md "no binaries" user-preference note can be simplified from "agents must not; existing violations pending" to "agents must not; scan enforced" — but the rule itself stays.

Alternatives considered

  • Delete binaries now, document manual fetch. Rejected: no automated retrieval, so every contributor hand-fetches. The intended system (G-005/G-006) exists precisely to avoid this.
  • Allow committed binaries permanently. Rejected: this is the explicit ultimate aim the user stated. Not a real alternative.
  • Permit zip-based .tm with embedded executables. Rejected: the user's wording is explicit — "those zip-based .tm modules that contain executables should also not be directly checked in." The content matters, not the extension.
  • Fold G-005 and G-006 into this goal. Rejected: the build system and download system are each large bodies of work with their own acceptance, and they're independently useful before all binaries are removed. Bundling would make G-004 uncheckable until two large systems are built, and would grow past a one-line-safe summary.

Notes

  • Depends on G-005 and G-006. Sequence G-005 ∥ G-006, then G-004.
  • The scan in step 4 should distinguish "executable binary" from "zip archive" and from "zip archive containing an executable." A naive extension-based check is insufficient; content inspection (file magic, zip listing) is required.
  • The AGENTS.md user-preference rule is the transition guard: it stops agents from adding new binaries during the G-005/G-006 development period while the developer's existing vendor/vfs binary commits are known and intentional.
  • No persisted prior chat on this topic was found in project sessions; the motivation is the user's stated ultimate aim.