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.
683 Commits
1 Branch
1 Tag
147 MiB
 
 
 
 
 
 
Tree: 92f6c30442
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '92f6c30442'
${ noResults }
punkshell/goals/G-027-derived-project-pull-...

4.6 KiB
Raw Blame History

G-027 Pull-based infrastructure updates for punkshell-derived projects

Status: proposed Scope: src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new push path), src/modules/punkcheck-999999.0a1.0.tm (install provenance records), src/make.tcl (derived-project pull entrypoint) Acceptance: as in root GOALS.md index (canonical).

Context

Projects initialised via dev project.new (punk::mix::commandset::project::new) receive a snapshot of punkshell's layout system: make.tcl/build.tcl, bootsupport modules and libs, template payloads. That snapshot then drifts. The current remedy is a push from punkshell: re-running dev project.new -force 1 -update 1 against the derived project. A pull - one command run inside the derived project - is the more natural shape: the derived project knows when it wants updating, and its owner is the right party to review what changes.

Motivating incident (2026-07-06, tomlish project): a make.tcl vintage 2025-04 carried a bootsupport-update step that itself depended on a stale bundled fileutil::traverse (Tcl 8.x-only constraint, broken under 9.0.3), so the tool that should fix the drift was disabled by the drift; bootsupport/lib still had the obsolete per-platform layout; include_modules.config files were empty template stubs. Recovery required manual cross-project copying - exactly the push-shaped work this goal eliminates. A drifted derived project must be recoverable by a pull whose own machinery does not depend on the freshness of the drifted parts (the pull entrypoint should be small/self-contained enough to work from a stale project, or delivered as its first step).

Current mechanism and its limits

  • .punkcheck records in the derived project record where targets were installed from (installer/source paths) - "roughly the right shape": provenance-driven, change-detected, skippable when unchanged.
  • Limits:
    • Source references are local relative paths - resolution breaks or silently mislocates if the derived project (or punkshell checkout) moves.
    • No VCS awareness: nothing checks whether the punkshell source is dirty (G-026 territory) or whether the pull would clobber uncommitted local modifications in the derived project.
    • Push-only initiation, from the punkshell side.

Approach

  • A pull entrypoint in the derived project (make.tcl subcommand or a small standalone bootstrap that does not depend on the possibly-stale local infrastructure).
  • Provenance robust to moves: record the origin punkshell project by something more durable than a relative path - candidates: fossil project-code / git remote or commit identity, plus a locally-resolvable path hint refreshed on each pull; dev projects.work discovery (G-016/G-017) can re-locate a moved punkshell checkout by name/id when the stored path fails.
  • VCS integration on both ends:
    • Source side: G-026 clean-checkout policy shared, not reimplemented.
    • Target side: before overwriting, classify each target file - unmodified since last punkcheck install (safe), locally modified but committed (report/confirm), uncommitted local changes (refuse or explicit override).
  • Remote pulls: decide whether updates may come directly from a remote punkshell repository (fossil clone/sync or git fetch of a punkshell repo, or the G-006 artifact-download channel) rather than a local checkout. Considerations: provenance/verification of remote content, version pinning (pull a tagged punkshell release vs trunk), and interaction with the consent-gating principle of G-006. May be recorded as deferred with rationale.

Alternatives considered

  • Keeping push-only and just fixing its path robustness - rejected as the end state: the updater lives on the wrong side of the relationship; the derived project's owner should initiate and review. Push retained during transition.
  • Making derived projects git/fossil-track punkshell as an upstream remote and merge - rejected: derived projects are independent repos with their own history; infrastructure files are a curated payload, not a branch to merge.

Notes

  • Related: G-012 (inert template payloads and the make.tcl template-refresh step feed what a pull delivers), G-016/G-017 (project discovery for re-locating a moved origin), G-026 (clean-checkout policy on the source), G-005/G-006 (remote artifact channels if remote pull proceeds).
  • The 2025-04 tomlish checkin "update bootsupport and make.tcl from punkshell" and the 2026-07-06 manual recovery are the concrete push-model precedents to test the pull against: a scratch project seeded at an old layout vintage should be fully recoverable by one pull.