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.
878 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: 6e68e29a1e
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6e68e29a1e'
${ noResults }
punkshell/goals/G-086-light-project-layout.md

3.1 KiB
Raw Blame History

G-086 Light project layout: punkshell-generated minimal projects carrying startup/test module-path semantics

Status: proposed Scope: src/project_layouts/ (new light layout), src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new layout selection), layout-seeded test harness + startup preamble (no bootsupport/vfs/build trees in generated output) Goal: project.new can generate a "light" layout - no kits, vfs, bootsupport or build-output trees - that still carries punkshell's environment-control semantics: a seeded script/test startup preamble that deterministically places project module paths (modules, vendormodules, vendorlib) ahead of machine-default tm paths before any package require, a runtests-style test harness, and the DOX/GOALS doc seed, so light projects (e.g. serversecretsync) inherit punkshell startup discipline without the build machinery. Acceptance: on a machine whose default tm paths carry older copies of a vendored package (the tomlish 1.1.10-vs-1.1.12 incident as the reference case), a generated light project's seeded harness and preamble provably select the project's vendored module on both Tcl 8.6 and 9.x, with a characterization test shipping in the layout that exercises the require-before-path-setup failure mode; the generated tree contains no build-output directories; and serversecretsync can adopt the seeded preamble/harness with its existing doc.test suite passing unchanged.

Context

serversecretsync (c:/repo/jn/serversecretsync) was seeded 2026-07-14 by hand rather than via project.new, deliberately staying light - and promptly hit the class of failure punkshell's launch control exists for: on Tcl 8.6, a package require before tm path setup registered modules from the machine-default tm paths (which on dev machines carry punkshell's built modules/ dir) and silently selected tomlish 1.1.10 over that project's vendored 1.1.12; Tcl 9.0 selected correctly with either ordering. Characterized in serversecretsync's src/tests/AGENTS.md and its archived G-008 detail file. A light layout should make this failure impossible by construction, giving hand-lightness without giving up startup semantics.

Approach

  • Default mechanism (user decision 2026-07-14): vendor punk::libunknown + punk::packagepreference into the light layout as the bootstrap minimum, so generated projects get punkshell's package-resolution control rather than relying on bare path ordering alone. The seeded preamble stays small: project path setup plus the bootstrap requires, before anything else runs.
  • Pure-Tcl path ordering remains the inner layer the bootstrap itself depends on - the preamble must be correct before any package require, including the requires that load the bootstrap modules themselves.
  • Related goals: G-012 (template payload safety - inert VCS-config payloads apply to this layout too), G-027 (derived-project pull updates - how light projects receive infrastructure refreshes), G-035 (mixed .tm/pkgIndex provision characterization backing libunknown/packagepreference behaviour), G-029 (packaged test modules - the light harness should stay compatible with that direction).