bsmnt 0.1.2 → 0.2.0

package/tasks/archive/2026-02-09-next-starter-dynamic-layers/progress.txt

@@ -1,115 +0,0 @@
-## Codebase Patterns
-- This is a plain JS (ESM) CLI project - no TypeScript, no typecheck command. "Typecheck passes" = no syntax errors.
-- Config pattern: export const CONFIG object + getXConfig(name) helper that returns config or null
-- src/mergers/config.js holds all configuration (CMS_CONFIG, LAYER_CONFIG)
-- src/mergers/index.js holds injection/merge logic (injectIntegration for CMS, injectLayer for layers)
-- src/commands/create.js is the main CLI flow
-- next-starter uses package.json directly (no template rename needed)
-- Layer files are local (in layers/ directory), CMS integration files are remote (fetched via tiged)
-- ESM requires __dirname workaround: `path.dirname(fileURLToPath(import.meta.url))`
-- CLI binary is basement (defined in package.json bin field)
-- Dependency injection order in create.js: layer deps → CMS deps → animation deps
-
----
-
-## 2026-02-09 - US-001
-- Implemented LAYER_CONFIG export with webgl, webgpu, experiment entries
-- Added getLayerConfig() helper function
-- Each layer config has: replaceFiles, additivePaths, dependencies, devDependencies
-- webgpu is deps-only (empty replaceFiles and additivePaths)
-- Files changed: src/mergers/config.js
-- **Learnings for future iterations:**
-  - The CLI project is plain JS ESM, verified by running `node --input-type=module -e "import {...}"`
-  - Config pattern follows existing CMS_CONFIG style - object + getter helper
-  - experiment uses three ^0.172.0 (not ^0.182.0 like webgl/webgpu) per PRD
----
-
-## 2026-02-09 - US-002
-- Created layers/webgl/ with app/page.tsx and 3 webgl component files from template/webgl/
-- Created layers/experiment/ with header, navigation-menu, constats.ts, cn.ts from template/experiment/
-- Created layers/webgpu/.gitkeep (empty layer, deps-only)
-- Verified all files are byte-for-byte identical using diff
-- Files changed: 9 new files in layers/
-- **Learnings for future iterations:**
-  - Layer files are local to CLI repo (no network clone needed, unlike CMS integrations)
-  - webgl is the only layer with a different app/page.tsx (imports DynamicCanvas)
-  - experiment has its own header and navigation-menu components
----
-
-## 2026-02-09 - US-003
-- Added injectLayer(targetDir, layer, spinner) function to src/mergers/index.js
-- Uses __dirname (via import.meta.url + fileURLToPath) to resolve layers/ directory
-- Reuses detectPathPrefix() and transformPath() for src/ directory support
-- Handles replaceFiles (overwrite: true) and additivePaths (overwrite: false) separately
-- Returns results with replaced, copied, skipped, failed arrays
-- Extended formatMergeResults() with defensive optional chaining for replaced/merged/copied/etc
-- Files changed: src/mergers/index.js
-- **Learnings for future iterations:**
-  - ESM doesn't have __dirname, must use: `const __dirname = path.dirname(fileURLToPath(import.meta.url))`
-  - Layer injection is purely local file copy (no network), unlike CMS integration which uses tiged
-  - formatMergeResults now handles both CMS results (merged) and layer results (replaced) gracefully
----
-
-## 2026-02-09 - US-004
-- Changed tiged source from basement/template/${type} to basementstudio/next-starter#main
-- Removed BASEMENT_CLI_BRANCH env var usage (was only used for template, not used elsewhere)
-- Added bun.lock deletion after clone (since deps will be modified by layers/CMS/animation)
-- Updated spinner text to "Downloading next-starter from GitHub..."
-- Updated troubleshooting message to reference basementstudio/next-starter
-- Kept dotenv import as it may be used by merger modules
-- Files changed: src/commands/create.js
-- **Learnings for future iterations:**
-  - dotenv is loaded in create.js but env vars are only used in merger modules (check-integration-merger.js)
-  - bun.lock must be deleted before modifying package.json deps, otherwise bun install may conflict
----
-
-## 2026-02-09 - US-005
-- Added layer injection step (3.2) between template download and CMS integration (3.5)
-- Layer injection only runs when type !== 'default'
-- Uses dynamic import for injectLayer and formatMergeResults from mergers/index.js
-- Shows ora spinner with layer name during injection
-- On failure, shows warning and continues (not a hard error)
-- Files changed: src/commands/create.js
-- **Learnings for future iterations:**
-  - Layer injection MUST happen before CMS integration to keep layout.tsx intact for CMS mergers
-  - Uses dynamic import (await import) consistent with existing CMS integration pattern
----
-
-## 2026-02-09 - US-006
-- Imported getLayerConfig from src/mergers/config.js at top of create.js
-- Layer deps injected from LAYER_CONFIG before CMS and animation deps
-- Simplified package.json handling: removed package.template.json logic (next-starter uses package.json directly)
-- CMS and animation dependency injection unchanged
-- Project name and version still set correctly
-- Files changed: src/commands/create.js
-- **Learnings for future iterations:**
-  - Dependency injection order matters: layer deps first, then CMS, then animation (later ones override earlier)
-  - next-starter uses package.json directly, no need for package.template.json rename logic
----
-
-## 2026-02-09 - US-007
-- Deleted template/default/, template/webgl/, template/webgpu/, template/experiment/ directories
-- Removed entire template/ directory (281 files, -27,778 lines)
-- Verified no remaining references to template/ paths in source code (src/)
-- Updated CLAUDE.md to reflect new architecture (layers/ instead of template/)
-- Files changed: template/ deleted, CLAUDE.md updated
-- **Learnings for future iterations:**
-  - CLAUDE.md should be kept in sync with architecture changes
-  - Only documentation files (CLAUDE.md, PRD) had remaining references to template/ paths, not source code
----
-
-## 2026-02-09 - US-008
-- Installed CLI locally via npm link
-- E2E test results (all passed):
-  - test-default: Created successfully, name=test-default, version=0.1.0, has next dep, no R3F deps
-  - test-webgl: Created with layer applied (replaced page.tsx, added 3 webgl components), R3F ^9.5.0, three ^0.182.0, @types/three ^0.182.0
-  - test-webgpu: Created with deps-only layer, R3F 10.0.0-alpha.2, drei ^11.0.0-alpha.4, lucide-react ^0.474.0
-  - test-experiment: Created with layer (header, navigation-menu, constats.ts, cn.ts), three ^0.172.0
-  - test-sanity: Combined webgl + sanity + gsap - all deps present (R3F, next-sanity, sanity, gsap, @gsap/react, sanity:extract script)
-- All 4 projects pass bun install without errors
-- CLI command is basement (not basement-starter as PRD mentions)
-- **Learnings for future iterations:**
-  - Skills installation may fail without network (bunx skills add), but it's non-blocking
-  - The sanity integration triggers an interactive Sanity setup prompt after project creation
-  - bun install correctly resolves all dependency versions including alpha packages
----

package/tasks/prd-next-starter-dynamic-layers.md

@@ -1,184 +0,0 @@
-# PRD: Replace Static Templates with next-starter + Dynamic Layers
-
-## Introduction
-
-The CLI currently maintains 4 complete, nearly-identical template copies (default, webgl, webgpu, experiment). Every bug fix, dependency bump, or structural change must be applied 4 times. The `default` template is essentially a stale snapshot of the `basementstudio/next-starter` repo.
-
-This feature replaces the static templates with a single `next-starter` clone as the base, then dynamically overlays technology-specific files and dependencies using a "layers" system — reusing the same smart-merge pattern already proven by the CMS integration system.
-
-## Goals
-
-- Eliminate template duplication by using `basementstudio/next-starter` as the single source of truth
-- Maintain the same user-facing CLI experience (same 4 template choices, same prompt flow)
-- Create a `layers/` system for technology-specific additions (WebGL, WebGPU, Experiment)
-- Reuse the existing merger infrastructure (`src/mergers/`) for layer injection
-- Delete the entire `template/` directory from the repo
-
-## User Stories
-
-### US-001: Clone next-starter as base template
-**Description:** As a developer using the CLI, I want my project to be scaffolded from the latest `next-starter` repo so that I always get the most up-to-date base configuration.
-
-**Acceptance Criteria:**
-- [ ] `create.js` clones from `github:basementstudio/next-starter#main` instead of `github:basementstudio/basement/template/{type}#main`
-- [ ] Selecting "Default" template produces a project identical to cloning next-starter directly
-- [ ] `bun.lock` is deleted after clone (since dependencies will be modified)
-- [ ] Download spinner text updated to reflect new source
-- [ ] Error/troubleshooting messages updated to reference `basementstudio/next-starter`
-- [ ] Typecheck passes
-
-### US-002: Create layer configuration system
-**Description:** As a CLI maintainer, I want technology layers defined in a config file so that adding or modifying layers only requires changing one file.
-
-**Acceptance Criteria:**
-- [ ] `LAYER_CONFIG` export added to `src/mergers/config.js` alongside existing `CMS_CONFIG`
-- [ ] Each layer config defines: `replaceFiles`, `additivePaths`, `dependencies`, `devDependencies`
-- [ ] `getLayerConfig(layer)` helper function exported
-- [ ] Config contains entries for `webgl`, `webgpu`, and `experiment`
-- [ ] `webgpu` is a deps-only layer (empty `replaceFiles` and `additivePaths`)
-- [ ] Dependencies match what's currently in each template's `package.template.json`
-
-### US-003: Implement layer injection function
-**Description:** As the CLI system, I need to overlay layer-specific files on top of the next-starter base so that WebGL/WebGPU/Experiment projects get their unique components.
-
-**Acceptance Criteria:**
-- [ ] `injectLayer(targetDir, layer, spinner)` function added to `src/mergers/index.js`
-- [ ] Function copies additive files from local `layers/{type}/` directory (no tiged needed)
-- [ ] Function replaces files listed in `replaceFiles` (overwrites base version)
-- [ ] Function uses existing `detectPathPrefix()` and `transformPath()` for `src/` directory support
-- [ ] Function returns results object with `replaced`, `copied`, `skipped`, `failed` arrays
-- [ ] `formatMergeResults()` extended to handle `replaced` entries
-- [ ] Skipped layers (type === 'default') produce no errors
-
-### US-004: Extract layer files from templates
-**Description:** As a CLI maintainer, I need the unique files from each template extracted into a `layers/` directory so they can be overlaid on next-starter.
-
-**Acceptance Criteria:**
-- [ ] `layers/webgl/app/page.tsx` contains the WebGL-specific page (DynamicCanvas import)
-- [ ] `layers/webgl/components/webgl/canvas/dynamic.tsx` exists (from template/webgl)
-- [ ] `layers/webgl/components/webgl/canvas/index.tsx` exists (from template/webgl)
-- [ ] `layers/webgl/components/webgl/components/scene/index.tsx` exists (from template/webgl)
-- [ ] `layers/experiment/components/layout/header/index.tsx` exists (custom header with NavigationMenu)
-- [ ] `layers/experiment/components/layout/navigation-menu.tsx` exists
-- [ ] `layers/experiment/lib/constats.ts` exists
-- [ ] `layers/experiment/lib/utils/cn.ts` exists
-- [ ] `layers/webgpu/` directory exists (empty, deps-only layer)
-- [ ] Files are byte-for-byte identical to their template counterparts
-
-### US-005: Integrate layer injection into create flow
-**Description:** As the CLI system, I need the layer injection step wired into the project creation flow so it runs between template download and CMS integration.
-
-**Acceptance Criteria:**
-- [ ] Layer injection runs after next-starter clone, before CMS integration
-- [ ] Layer injection only runs when `type !== 'default'`
-- [ ] Progress spinner shows layer name during injection
-- [ ] Injection results displayed to user (files added/replaced)
-- [ ] Failures produce warnings, not hard errors
-- [ ] CMS integration (Sanity) still works correctly after layer injection
-- [ ] Typecheck passes
-
-### US-006: Config-driven dependency injection
-**Description:** As the CLI system, I need package.json hydration to read layer dependencies from config instead of being hardcoded in create.js.
-
-**Acceptance Criteria:**
-- [ ] Layer dependencies read from `LAYER_CONFIG` and merged into `package.json`
-- [ ] CMS dependencies still injected as before (unchanged)
-- [ ] Animation library dependencies still injected as before (unchanged)
-- [ ] `package.template.json` rename logic simplified (next-starter uses `package.json` directly)
-- [ ] Project name and version still set correctly
-- [ ] Typecheck passes
-
-### US-007: Delete template directory
-**Description:** As a CLI maintainer, I want the `template/` directory removed so there's no duplicated code to maintain.
-
-**Acceptance Criteria:**
-- [ ] `template/default/` deleted
-- [ ] `template/webgl/` deleted
-- [ ] `template/webgpu/` deleted
-- [ ] `template/experiment/` deleted
-- [ ] No remaining references to `template/` paths in source code
-- [ ] No remaining references to `basementstudio/basement/template/` in source code
-
-### US-008: End-to-end verification
-**Description:** As a CLI maintainer, I need to verify all template + CMS + animation combinations work correctly.
-
-**Acceptance Criteria:**
-- [ ] `basement -c test-default -d -no-cms -no-animation -claude -no-hooks` produces a working project
-- [ ] `basement -c test-webgl -webgl -no-cms -no-animation -claude -no-hooks` produces a working project with R3F components
-- [ ] `basement -c test-webgpu -webgpu -no-cms -no-animation -claude -no-hooks` produces a working project with WebGPU deps
-- [ ] `basement -c test-experiment -exp -no-cms -no-animation -claude -no-hooks` produces a working project with experiment header
-- [ ] `basement -c test-sanity -webgl -sanity -gsap -claude -no-hooks` produces a working project with CMS + animation + layer
-- [ ] All generated projects pass `bun install && bun dev` (dev server starts)
-
-## Functional Requirements
-
-- FR-1: The CLI must clone `basementstudio/next-starter#main` as the base for all template types
-- FR-2: When `type !== 'default'`, the CLI must apply the corresponding layer from the local `layers/` directory
-- FR-3: Layer injection must copy additive files without overwriting existing files
-- FR-4: Layer injection must replace files listed in `replaceFiles`, overwriting the base version
-- FR-5: Layer injection must respect `src/` directory structure (using existing `detectPathPrefix`)
-- FR-6: Layer dependencies must be merged into `package.json` from `LAYER_CONFIG`
-- FR-7: CMS integration must continue to work identically after layer injection
-- FR-8: The `bun.lock` file must be deleted after cloning next-starter
-- FR-9: The user-facing prompt flow must remain unchanged (same 4 template choices)
-- FR-10: The `template/` directory must be deleted from the repository
-
-## Non-Goals
-
-- No multi-layer support (combining WebGL + Experiment) — one layer per project
-- No `add-layer` command for existing projects (only `create` flow)
-- No version pinning UI — always clones latest `main`
-- No changes to the CMS integration system (`src/mergers/` for Sanity/BaseHub)
-- No changes to the hooks, plugins, or agent skills systems
-- No new merger functions for layers (layers use simple copy/replace, not smart merge)
-
-## Technical Considerations
-
-- **Reuse existing infrastructure:** `detectPathPrefix()`, `transformPath()`, and `formatMergeResults()` from `src/mergers/index.js` are already built for this pattern
-- **Layer files are local:** Unlike CMS integrations (cloned via tiged from a remote branch), layer files live in the CLI repo's `layers/` directory. No network request needed.
-- **Application order matters:** Layers run before CMS integration. Layers do NOT modify `layout.tsx`, so the Sanity layout merger continues to work on the unmodified base layout.
-- **Package.json format:** `next-starter` uses `package.json` (not `package.template.json`), simplifying hydration logic.
-
-### Files to Modify
-
-| File | Change Type |
-|------|-------------|
-| `src/mergers/config.js` | Add `LAYER_CONFIG`, `getLayerConfig()` |
-| `src/mergers/index.js` | Add `injectLayer()`, extend `formatMergeResults()` |
-| `src/commands/create.js` | Change tiged source, add layer step, config-driven deps |
-
-### Files to Create
-
-| File | Source |
-|------|--------|
-| `layers/webgl/app/page.tsx` | `template/webgl/app/page.tsx` |
-| `layers/webgl/components/webgl/canvas/dynamic.tsx` | `template/webgl/components/webgl/canvas/dynamic.tsx` |
-| `layers/webgl/components/webgl/canvas/index.tsx` | `template/webgl/components/webgl/canvas/index.tsx` |
-| `layers/webgl/components/webgl/components/scene/index.tsx` | `template/webgl/components/webgl/components/scene/index.tsx` |
-| `layers/experiment/components/layout/header/index.tsx` | `template/experiment/components/layout/header/index.tsx` |
-| `layers/experiment/components/layout/navigation-menu.tsx` | `template/experiment/components/layout/navigation-menu.tsx` |
-| `layers/experiment/lib/constats.ts` | `template/experiment/lib/constats.ts` |
-| `layers/experiment/lib/utils/cn.ts` | `template/experiment/lib/utils/cn.ts` |
-
-### Files/Directories to Delete
-
-| Path | Reason |
-|------|--------|
-| `template/default/` | Replaced by next-starter clone |
-| `template/webgl/` | Replaced by `layers/webgl/` |
-| `template/webgpu/` | Replaced by `layers/webgpu/` |
-| `template/experiment/` | Replaced by `layers/experiment/` |
-
-## Success Metrics
-
-- Template directory eliminated (0 duplicated files to maintain)
-- All 4 template types produce working projects with `bun dev`
-- CMS + layer combinations work correctly
-- CLI prompt flow unchanged (invisible to users)
-- Layer addition requires only: adding files to `layers/`, adding config to `LAYER_CONFIG`
-
-## Open Questions
-
-- Should we add a `--starter-ref` CLI flag in a future iteration for version pinning?
-- If next-starter changes its directory structure significantly, should the CLI validate expected paths before applying layers?
-- Should the `experiment` template's `constats.ts` typo be fixed to `constants.ts`?