diff --git a/GOALS.md b/GOALS.md index d1b9a0c4..db5fdc8c 100644 --- a/GOALS.md +++ b/GOALS.md @@ -333,3 +333,7 @@ Detail: goals/G-087-thin-project-layouts.md ### G-088 [proposed] textblock table footer block + bottom-edge subtitle (arg_error examples marker) Scope: src/modules/textblock-999999.0a1.0.tm (class::table options and bottom border assembly), src/modules/punk/args-999999.0a1.0.tm (arg_error usage-table examples marker), src/tests/modules/punk/args/testsuites/args/examples.test + textblock table coverage Detail: goals/G-088-textblock-table-footer-subtitle.md + +### G-089 [proposed] Scriptlib in kits + packagemode-aware lib: resolution (visitor scriptlib via proj:) +Scope: src/make.tcl, src/vfs/ (kit vfs payloads), src/modules/punk/path-999999.0a1.0.tm, src/vfs/_config/punk_main.tcl, scriptlib/ +Detail: goals/G-089-scriptlib-kits-and-modes.md diff --git a/goals/G-089-scriptlib-kits-and-modes.md b/goals/G-089-scriptlib-kits-and-modes.md new file mode 100644 index 00000000..09795425 --- /dev/null +++ b/goals/G-089-scriptlib-kits-and-modes.md @@ -0,0 +1,58 @@ +# 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` + (`/app/scriptlib`, or `/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 `/bin`, making + `/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 `/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:.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.