punkshell/goals/G-089-scriptlib-kits-and-modes.md

G-089 Scriptlib in kits + packagemode-aware lib: resolution

Status: proposed Scope: src/make.tcl, src/vfs/ (kit vfs payloads), src/modules/punk/path-999999.0a1.0.tm, src/vfs/_config/punk_main.tcl, scriptlib/ Goal: built kits carry an internal scriptlib (baked by make.tcl into the kit vfs at app/scriptlib, curated - test fixtures/logs excluded) so a standalone punk binary has working lib: scripts, and scriptlib precedence follows the same mental model as the module path blocks: kit-internal-wins applies to the default 'internal' launch only, src/dev package modes put the project's live scriptlib first (un-masking edits during development), and a proj:-prefixed launch (G-033) additionally resolves lib: against the visited project's scriptlib. Acceptance: a kit built with the baked scriptlib, relocated outside any source tree, runs ' script lib:' for a baked script; from /bin the default launch runs the kit copy while 'src' mode runs an edited live /scriptlib copy of the same name (proven by differing markers); cookfs kits either resolve their internal scriptlib too or are explicitly documented as excluded; the packagemode reaches scriptlib_resolve via a boot-provided hint rather than being re-derived; with G-033 implemented, 'proj:' adds the cwd-project's scriptlib to the search (deferred to G-033 if that lands later, recorded here).

Context

Findings from the 2026-07-18 lib: extensionless work (punk::path 0.3.0):

• The kit-internal branch of punk::path::scriptlib_resolve (<zipfs-root>/app/scriptlib, or <exepath>/scriptlib for a mounted tclkit) has never been exercised: no .vfs layout contains a scriptlib/ folder and src/make.tcl never references scriptlib. lib: works today only because the repo's executables sit in <projectroot>/bin, making <exedir-parent>/scriptlib the repo's scriptlib/. A standalone installed binary currently has NO working lib: source at all.
• The documented "internal scripts are deliberately NOT overridable" policy was intended for the default launch behaviour only (user direction 2026-07-18), not as an absolute - once kits carry a baked scriptlib, an unconditional kit-first rule would mask live scriptlib/ edits in the dev workflow (exe in <projectroot>/bin) until the next rebuild. The packagemode dash-list is already the user's precedence dial for module paths; scriptlib should ride the same mental model.
• Nothing currently records the chosen packagemode anywhere punk::path can see - punk_main consumes arg0 and rearranges paths but exposes no mode hint to the runtime layer. A small boot-interface addition is needed (candidate: a ::punkboot:: or punk::config "running" value seeded at boot).
• scriptlib_resolve checks only the zipfs root and the exepath-as-directory (tclkit) cases for the kit-internal dir; cookfs kits (e.g punk9cook) mount elsewhere (//cookfstemp:/... style roots tracked by punk_main's internal_paths) and would miss a baked scriptlib.
• The bake itself: a punkcheck-managed copy of scriptlib/ into the target vfs during make, curated - _punktest/ fixtures, *.log, and other non-shippable content excluded. Baking policy per kit class (dev-built vs release/standalone) is an open decision within this goal.
• Visitor semantics follow G-033's decisions: proj: is an explicit opt-in (no silent cwd rebind), and kit-first remains the canonical robust default for ties in visitor mode - the visited project's scriptlib joins the search after kit-internal under proj:internal-..., with block order controlling precedence as for module paths.
• Out of scope: app-shellspy's do_script_process keeps its own simpler lib: mapping (external-interpreter semantics, any extension); the script/shell subcommands are the surfaces this goal covers.

Notes

• Related goals: G-033 (proj: scope prefix - the visitor root discovery this goal's proj: scriptlib clause rides on; its notes already flag that proj:... script benefits), G-018/G-019 (installable/trimmed kits), G-015 (achieved - script subcommand, goals/archive/G-015-script-subcommand-piped-stdin.md).
• lib:<name>.kit dispatch (restored in punkshell 0.14.0 via punk::path 0.3.0's known-extensions fix) has no committed test fixture - a .kit archive would violate the no-new-binaries rule (G-004); if kit-dispatch coverage is wanted, generate a throwaway kit at test time or defer until G-005/G-006 tooling exists.