From 0540c3c19b72a47bd6142981dfc896b3387fb40f Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 7 Jul 2026 19:43:20 +1000 Subject: [PATCH] add goals G-033 (proj cwd-project mode) and G-034 (8.6 shell modpod mount) G-033: an explicit `proj` package-mode token lets an installed (visitor) punkshell binary detect the punk project containing the cwd - walking up to the nearest VCS repo root, the marker punk::repo::is_project_root already uses - and set up source/dev library resolution against THAT project, so `punkshell proj shell` explores a project interactively even when the project builds no shell-capable binary (or no binary at all). History check recorded: cwd project-structure detection was never active in the boot modes (src/dev are exe-relative; os is shallow cwd-only), but the runtime detector find_project already exists and dev commands use it - so the marker question (VCS repo root, not punkproject.toml which tomlish lacks) is already answered; this aligns boot modes with it. Explicit token gates it per user decision (no silent rebind on cd); boot chicken-and-egg (find_project is in punk::repo, not loadable at the package-mode phase) handled by a lean inline VCS-root walk-up or post-boot deferral. Reuses the existing src-mode path machinery, parameterised on the detected root. Not gated on the module.templates/punk::cap plugin machinery. G-034: zip-based #modpod modules (e.g. punk::mix::templates) fail to mount in the shell subcommand's code interp on Tcl 8.6 - `dev module.templates` errors with `invalid command name vfs::RegisterMount` / no template providers - while the same call works via the script subcommand / main interp (reproduced 2026-07-07). The code interp lacks the vfs::zip library that supplies zip mounting for pre-zipfs Tcl. Tcl 9 (zipfs) unaffected. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 11 ++++ goals/G-033-proj-mode-cwd-project.md | 85 ++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 goals/G-033-proj-mode-cwd-project.md diff --git a/GOALS.md b/GOALS.md index 30c01257..ebbb1e6d 100644 --- a/GOALS.md +++ b/GOALS.md @@ -240,3 +240,14 @@ Scope: src/vfs/_config/ (default dispatch), src/lib/app-punkshell and sibling ap Detail: goals/G-032-launcher-punkargs.md Goal: the default launch dispatch defines its subcommands via punk::args - ` -help` and argument errors render the tabled usage enumerating built-in and project-registered subcommands with summaries, and subcommand options parse through punk::args so projects can declare complex arguments - with the G-030 degradation rules (boot never fails and help degrades to plain text when punk::args or the ANSI rendering stack is unavailable). Acceptance: ` -help` renders tabled usage listing all subcommands including project-registered ones, each with a summary; at least one built-in subcommand's options are declared and parsed via punk::args with tabled usage errors on invalid input (the G-015 script subcommand or the G-025 version-report subcommand are the natural candidates); a project-registered subcommand's help appears by registration alone - no edits to the shared dispatch; with punk::args or the rendering stack unloadable, boot proceeds and help degrades to a plain subcommand list; verified on both a zipfs-based and a non-zipfs kit where both remain supported. + +### G-033 [proposed] `proj` package-mode: visitor binary detects the cwd's project and explores it +Scope: src/vfs/_config/punk_main.tcl (package-mode dispatch and boot-time root discovery), src/modules/punk/repo-999999.0a1.0.tm (find_project / is_project_root - reuse or lean boot mirror), bin/AGENTS.md (mode docs) +Detail: goals/G-033-proj-mode-cwd-project.md +Goal: an explicit `proj` package-mode token lets an installed ("visitor") punkshell binary - one not built from the project - detect the punk project containing the current working directory (walking up to the nearest VCS repo root, the marker punk::repo::is_project_root already uses) and set up source/dev library resolution against THAT project, so a user can run e.g. `punkshell proj shell` from anywhere inside a project (which need not build its own shell-capable binary, or any binary at all) and explore it interactively; the token gates the behaviour so no `cd` silently rebinds a normal launch. +Acceptance: ` proj shell` launched from within a punk project's tree (the binary not belonging to that project) discovers the project root by walking up from cwd to the nearest VCS repo root and adds that project's src/modules, src/bootsupport/modules and src/vendormodules to the module path and src/lib to auto_path (the existing src-mode path machinery, parameterised on the cwd-detected root), so the session loads the project's dev-versioned modules; the detection marker matches punk::repo::is_project_root (a git or fossil repo root, not reliance on punkproject.toml); with no project found by walking up from cwd, `proj` warns and proceeds as `internal` with no false rebind; it works for a project that builds no executable of its own (proven against tomlish or a modules-only project); exe-relative `src`/`dev` discovery is unchanged for a binary that IS in a project's bin/; `proj` composes with the built-vs-source selectors (at least a documented default - proj implying source-tree resolution - with proj+dev / proj+src semantics recorded). + +### G-034 [proposed] Zip-based #modpod modules mount in the shell code-interp on Tcl 8.6 +Scope: src/modules/punk/mix/ (modpod mount path), vfs::zip availability in the repl code interp, src/modules/punk/cap/ (templates capability handler) +Goal: zip-based `#modpod` modules (e.g. `punk::mix::templates`) mount and their punk::cap handlers register in the `shell` subcommand's code interp on Tcl 8.6, matching the `script`/main-interp context - so `dev module.templates` and other `punk.templates`-capability consumers work in an interactive 8.6 shell instead of failing with `invalid command name vfs::RegisterMount`. +Acceptance: `dev module.templates` in an interactive 8.6 punk shell (`shell` subcommand) lists the template providers with no `failed to load ZIP archive-based module` / `invalid command name vfs::RegisterMount` / `Unable to register any template providers` / `invalid command name ::punk::cap::handlers::templates::api_punk.templates` errors, matching the `script`-subcommand output on the same binary (verified 2026-07-07: script works, shell fails); root cause fixed (the code interp lacks the vfs::zip library that provides vfs::RegisterMount for pre-zipfs Tcl, present in the main interp - restore it to the code interp or use an alternative modpod mount path there); Tcl 9 (built-in zipfs) behaviour is unchanged. diff --git a/goals/G-033-proj-mode-cwd-project.md b/goals/G-033-proj-mode-cwd-project.md new file mode 100644 index 00000000..cc3cb17d --- /dev/null +++ b/goals/G-033-proj-mode-cwd-project.md @@ -0,0 +1,85 @@ +# G-033 `proj` package-mode: visitor binary detects the cwd's project and explores it + +Status: proposed +Scope: src/vfs/_config/punk_main.tcl (package-mode dispatch and boot-time root discovery), src/modules/punk/repo-999999.0a1.0.tm (find_project / is_project_root - reuse or lean boot mirror), bin/AGENTS.md (mode docs) +Acceptance: as in root GOALS.md index (canonical). + +## Context + +The earlier intent (recalled 2026-07-07): an installed punkshell binary sitting +in PATH - possibly a downloaded binary, not built from the project - should be +able to detect when the cwd is inside a punkshell project and set up the +appropriate source/dev library resolution for it, so the user can explore that +project interactively via the `shell` subcommand. The project being worked on +might not build a shell-capable binary, or might build no executable at all +(e.g. a modules-only project like a library). + +History check: this was **never active** in the full sense. `src` mode is new +(checkin 3d2d098d) and discovers the project root **exe-relative** (backtrack +from the executable's `bin/`) - it assumes the binary belongs to the project. +`dev` mode is likewise exe-relative. `os` mode is the only cwd-relative piece, +and only shallowly (adds `[pwd]` and cwd-relative `modules`/`modules_tcl` +ad-hoc `.tm` sources - no walk-up, no `src/` structure). The comments in +punk_main.tcl name "the info nameofexecutable or info script or pwd relative +paths" as design axes, so the *intent* seeded `os` mode, but cwd project- +structure detection was never built into the boot modes. + +Crucially, the cwd-relative detector **already exists at the runtime layer**: +`punk::repo::find_project` walks up from cwd via `is_project_root`, and `dev` +commands (module.templates, module.new, ...) already use it. So the marker +question is answered: `is_project_root` defines a project as a **VCS repo root** +(git or fossil) that is not an excluded location - deliberately NOT relying on +`punkproject.toml` (its own comment notes that file also appears in layout +templates, and tomlish has no punkproject.toml yet but IS a fossil root). This +goal aligns the boot-time package modes with that existing runtime detection. + +## Approach + +- New explicit token `proj` in the package-mode list (dev/os/src/internal/proj). + Explicit gate = no `cd` silently rebinds a normal launch; the visitor + behaviour is opt-in. +- On `proj`: walk up from `[pwd]` to the nearest VCS repo root (the + `is_project_root` marker) and use that as the project root, then feed it into + the **existing src-mode path machinery** (which is already parameterised on a + root variable - adds src/modules, src/modules_tcl, src/bootsupport/modules, + src/vendormodules to the tm path, src/lib to auto_path, registers #modpod + modules, sets package prefer latest). The only new part is cwd-relative + *discovery*; the setup is reused. +- Boot chicken-and-egg: `find_project`/`is_project_root` live in `punk::repo`, + which is not loadable at the early package-mode phase (punk_main.tcl avoids + package requires there by design). Options, decision to record: (a) a lean + inline VCS-root walk-up in punk_main mirroring is_project_root (fossil: + _FOSSIL_/.fslckout/.fos; git: .git) using only Tcl builtins; (b) defer proj + setup to a post-boot phase where punk::repo is available. (a) matches how the + src-mode #modpod scan already inlines logic at boot. +- Composition: decide `proj` + built-vs-source selectors. Natural default: + `proj` alone implies source-tree resolution (like src) against the detected + root; `proj-dev` selects built `modules/` output; document the matrix. +- No-project case: `proj` from a non-project cwd warns and proceeds as + `internal` - never a false rebind. +- Exe-relative `src`/`dev` for a binary that IS in a project bin/ stays + unchanged; `proj` is the visitor-binary path. + +## Alternatives considered + +- Automatic cwd-detection with no token - rejected (user decision 2026-07-07): + silently rebinding the module world on `cd` is surprising; an explicit `proj` + token is the safer gate. +- A dedicated project-marker file (punkproject.toml) as the sole signal - + rejected: not universal (tomlish lacks it; it also appears in layout + templates), and is_project_root already provides a VCS-root marker that works + today. + +## Notes + +- The related `dev` machinery (module.templates -> punk::mix::commandset::module + -> punk::cap `punk.templates` plugin handlers) uses find_project and has + unpolished plugin issues, plus an 8.6 shell-context zip-modpod-mount failure + (G-034). This goal deliberately does NOT gate on synchronising with that + machinery - it only reuses the find_project detection concept. +- Related: G-018 (the installable generic/plain binary this serves), G-031 + (boot core is where proj discovery belongs; the template project_main.tcl + lacks even src mode - fork drift), G-015 (`script` also benefits: a visitor + binary running `proj script` against a cwd project), G-027 (if a universal + project marker is ever seeded, proj could prefer it over the structural VCS + heuristic).