From f9046dc191385c24ef25267365335316604a666d Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Fri, 17 Jul 2026 00:52:54 +1000 Subject: [PATCH] G-087 hygiene: exact punk.project layout ref, junk refs removed, README rewritten - @vendor+punk+project-0.1.ref renamed to project@vendor+punk+project-0.1.ref: the alias yields the exact layout name 'punk.project', so project.new's defaulted -layout resolves unambiguously (previously tcl::prefix::match saw only punk.project-0.1 / punk.project-0.1_overrides). - Junk/test refs removed from the selectable layout list: test2, the custom/_project duplicate sample-0.1 ref, and the alias-less punk.shell-0.1 ref whose target was an a.txt-only folder (folder removed too; the real shell layout remains exposed as punk.shell-0.1_overrides). - src/project_layouts/README.md rewritten to describe the implemented punk.templates + layout_refs mechanism including the ref filename grammar, the not-yet-implemented overlay semantics, and a G-087 pointer; the dead punk.projectlayout capability description is gone. Layout names after this change: punk.sample-0.1 punk.project punk.minimal punk.basic punk.shell-0.1_overrides punk.project-0.1_overrides. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- .../@vendor+_project+punk.shell-0.1.ref | 0 .../test2@vendor+punk+sample-0.1.ref | 0 .../layout_refs/@vendor+punk+project-0.1.ref | 0 .../project@vendor+punk+project-0.1.ref} | 0 src/project_layouts/README.md | 88 ++++++++++++++----- .../vendor/_project/punk.shell-0.1/a.txt | 0 6 files changed, 68 insertions(+), 20 deletions(-) delete mode 100644 src/decktemplates/vendor/_project/layout_refs/@vendor+_project+punk.shell-0.1.ref delete mode 100644 src/decktemplates/vendor/_project/layout_refs/test2@vendor+punk+sample-0.1.ref delete mode 100644 src/decktemplates/vendor/punk/layout_refs/@vendor+punk+project-0.1.ref rename src/decktemplates/{custom/_project/layout_refs/@vendor+punk+sample-0.1.ref => vendor/punk/layout_refs/project@vendor+punk+project-0.1.ref} (100%) delete mode 100644 src/project_layouts/vendor/_project/punk.shell-0.1/a.txt diff --git a/src/decktemplates/vendor/_project/layout_refs/@vendor+_project+punk.shell-0.1.ref b/src/decktemplates/vendor/_project/layout_refs/@vendor+_project+punk.shell-0.1.ref deleted file mode 100644 index e69de29b..00000000 diff --git a/src/decktemplates/vendor/_project/layout_refs/test2@vendor+punk+sample-0.1.ref b/src/decktemplates/vendor/_project/layout_refs/test2@vendor+punk+sample-0.1.ref deleted file mode 100644 index e69de29b..00000000 diff --git a/src/decktemplates/vendor/punk/layout_refs/@vendor+punk+project-0.1.ref b/src/decktemplates/vendor/punk/layout_refs/@vendor+punk+project-0.1.ref deleted file mode 100644 index e69de29b..00000000 diff --git a/src/decktemplates/custom/_project/layout_refs/@vendor+punk+sample-0.1.ref b/src/decktemplates/vendor/punk/layout_refs/project@vendor+punk+project-0.1.ref similarity index 100% rename from src/decktemplates/custom/_project/layout_refs/@vendor+punk+sample-0.1.ref rename to src/decktemplates/vendor/punk/layout_refs/project@vendor+punk+project-0.1.ref diff --git a/src/project_layouts/README.md b/src/project_layouts/README.md index 2d52f366..ef2c7bcb 100644 --- a/src/project_layouts/README.md +++ b/src/project_layouts/README.md @@ -1,20 +1,68 @@ - -project_layout information -========================== - -project layouts don't show as available unless referenced by an entry in a layout_ref folder within the src/decktemplates structure. - -This is because some layouts may be intended for use with child projects generated from 'deck project.new' - but not directly by this parent project. - -The structure of decktemplates and project_layouts is designed to avoid circular dependencies arising during creation of layouts for child projects - that may then need to in turn support the same layout if the child project creates projects. - -Layouts are not included in the resource files of modules for the same reason. (modules may need to be included in layouts) -Instead they are pointed to via the decktemplates custom & vendor structure. - --------- - -layouts within project_layouts/vendor should generally not be customised directly -The vendor layouts should be created and updated by loading the appropriate vendor modules. -These are plugin modules that are providers of the punk.projectlayout capability -(see punk::cap module documentation and the project_layouts/vendor/punk/sample-0.1 layout) - +project_layouts information +=========================== + +This folder is the payload store for project layouts: the directory trees that +`dev project.new` (punk::mix::commandset::project::new) copies to create a new +project. + +Discovery: the punk.templates capability +---------------------------------------- + +Layouts in this store do not show as available unless referenced by a layout +ref file found via the punk.templates capability (handler: +punk::cap::handlers::templates; principal provider: punk::mix::templates). + +Providers register template base folders with a pathtype. Base folders are +merged in priority order (lowest to highest): + + module < shellproject < currentproject < absolute < adhoc + +Within the shellproject/currentproject multivendor trees (src/decktemplates), +vendor/ folders are added before vendor/_project, and custom/ +levels override vendor/ levels. When the same visible name is produced by more +than one ref, the highest-priority one keeps the bare name and later ones are +suffixed #2, #3, ... + +Layout refs +----------- + +A layout ref is a zero-byte file in a layout_refs/ folder under a template +base (e.g. src/decktemplates/vendor/punk/layout_refs/, or a module-shipped +templates/layout_refs/). The entire meaning is in the filename: + + @++... .ref + +- The text before the first @ is the alias - the layout's nominal name. + If the alias is empty the last + separated segment is used as the name. +- The text after the first @ is a + separated path relative to + /src/project_layouts identifying the layout folder. + Segments after the first @ may themselves contain @ (derived-layout folder + names such as othersample@sample-0.1). +- The visible layout name is prefixed with the vendor folder name and a dot + unless the vendor is the pseudo-vendor _project + (e.g. project@vendor+punk+project-0.1.ref in a vendor/punk/layout_refs + folder presents as layout name "punk.project"). +- Only filenames matching *@vendor+*.ref or *@custom+*.ref are recognised; + files named ignore* are skipped. + +The ref indirection exists to break recursion: layout payloads may embed +module trees (including the punk::mix::templates module itself), so modules +ship only small ref files while the layout payloads live once, here, outside +any module. + +Store structure +--------------- + + src/project_layouts/{vendor,custom}/{,_project}/ + +- vendor/ trees should not be customised directly; place overrides under + custom/. The pseudo-vendor _project holds project-local staging copies. +- Overlay semantics (custom-over-vendor merging, .anti deletion markers, + newname@base derived layouts, _project staging) are documented design - + see custom/punk/sample-0.1/extra.txt - but are NOT yet implemented: + project.new currently copies exactly one resolved layout folder. + +Goal G-087 (goals/G-087-thin-project-layouts.md) tracks implementing the +overlay merge, migrating refs to fauxlink files, and restructuring this store +to thin layouts whose heavy infrastructure is injected at generation time +(retiring the embedded module-tree snapshots currently stored here). diff --git a/src/project_layouts/vendor/_project/punk.shell-0.1/a.txt b/src/project_layouts/vendor/_project/punk.shell-0.1/a.txt deleted file mode 100644 index e69de29b..00000000