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.
698 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: 0540c3c19b
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '0540c3c19b'
${ noResults }
punkshell/goals/G-033-proj-mode-cwd-project.md

5.0 KiB
Raw Blame History

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<N> 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).