bsmnt 0.0.0

package/changelog/04-02-26.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## [Unreleased] - Worktree Management
+
+### Added
+
+#### Git Worktree Management (`-w`, `--worktree`)
+
+A new CLI mode for managing git worktrees, enabling isolated development environments for parallel feature work.
+
+**New Commands:**
+
+| Flag | Long Flag | Description |
+|------|-----------|-------------|
+| `-w` | `--worktree` | Interactive worktree menu |
+| `-wc` | `--worktree-create` | Create new worktree(s) |
+| `-wl` | `--worktree-list` | List all worktrees for current project |
+| `-ws` | `--worktree-switch` | Get cd command to switch to a worktree |
+| `-wr` | `--worktree-remove` | Remove a worktree |
+| `-wp` | `--worktree-prune` | Clean up stale worktrees |
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-b=<name>` | Specify branch name (supports comma-separated for multiple) |
+| `-db`, `--delete-branch` | Delete branch when removing worktree |
+| `-f`, `--force` | Skip confirmation prompts |
+
+**Features:**
+
+- **Multiple worktree creation**: Create several worktrees at once via interactive prompts or comma-separated flag values
+- **Auto-dependency installation**: Detects and installs dependencies based on lock files:
+  - `bun.lock` / `bun.lockb` → `bun install`
+  - `pnpm-lock.yaml` → `pnpm install`
+  - `yarn.lock` → `yarn install`
+  - `package.json` (no lock) → `npm install`
+  - `Cargo.toml` → `cargo build`
+  - `requirements.txt` → `pip install -r requirements.txt`
+  - `pyproject.toml` → `poetry install` or `pip install -e .`
+  - `go.mod` → `go mod download`
+- **Smart directory structure**: Worktrees stored in `~/.claude/worktrees/<project>/<branch>`
+- **Branch name sanitization**: Converts `feature/auth` to `feature-auth` for directory names
+- **Prune command**: Cleans up stale git references and orphaned directories
+
+**Examples:**
+
+```bash
+# Interactive worktree management
+basement -w
+
+# Create single worktree
+basement -wc -b=feature/auth
+
+# Create multiple worktrees at once
+basement -wc -b=feature/auth,feature/dashboard,fix/bug-123
+
+# List all worktrees
+basement -wl
+
+# Remove worktree and delete branch
+basement -wr -b=feature/auth -db -f
+
+# Clean up stale worktrees
+basement -wp
+```
+
+### Files Added
+
+- `src/commands/worktree.js` - Worktree command implementation
+
+### Files Modified
+
+- `bin/index.js` - Added worktree mode, flags, routing, and help text
+
+---
+
+## Previous Releases
+
+### Sanity Integration Branch
+
+- Added `add-integration` command (`-a`, `--add`)
+- Sanity CMS integration with revalidate API
+- Support for Next.js projects with `src/` directory structure
+- Layout merging for Sanity integration
+- Updated sitemap paths for Sanity content

package/changelog/05-02-26.md

@@ -0,0 +1,101 @@
+# Changelog — February 5, 2026
+
+## Sanity Integration Overhaul
+
+### Added
+
+#### Automated Sanity Project Setup (`setup-sanity.js`)
+
+A new 8-step automated setup flow that provisions a Sanity project without leaving the CLI.
+
+**Steps performed automatically:**
+1. Verify Sanity CLI is available
+2. Check user authentication (prompts `sanity login` if needed)
+3. Create Sanity project via `sanity projects create`
+4. Create an API read token via the Sanity Management API
+5. Write credentials to `.env.local`
+6. Deploy a CORS origin for `localhost:3000`
+7. Create an initial dataset (`production`)
+8. Display a summary with project ID, dataset, and Studio URL
+
+Wired into both `create.js` (step 5.5) and `add-integration.js` (step 7) — if auto-setup is skipped or fails, the CLI falls back to manual credential instructions.
+
+#### `add-integration` Command (`-a`, `--add`)
+
+Post-scaffold command to inject a CMS integration into an existing Next.js project.
+
+- Validates the target is a Next.js App Router project
+- Supports Sanity and BaseHub integrations
+- Automatically injects dependencies, scripts, and CMS files
+- Registers the Sanity MCP server (`claude mcp add`) when Claude Code is detected
+- Installs `sanity-io/agent-toolkit` skills for AI-assisted workflows
+- Conditional next-steps messaging based on whether auto-setup succeeded
+
+#### Smart Merge System (`src/mergers/`)
+
+CMS-specific file mergers that intelligently inject integration code into existing project files instead of blindly overwriting them.
+
+| Merger | File | What it does |
+|--------|------|--------------|
+| `layout-merger.js` | `app/layout.tsx` | Injects Sanity providers, draft-mode components, and imports |
+| `sitemap-merger.js` | `app/sitemap.ts` | Adds Sanity content routes to the sitemap generator |
+| `check-integration-merger.js` | `lib/integrations/check-integration.ts` | Registers Sanity in the integration check map |
+| `config.js` | — | File classification config (merge vs. copy vs. skip) |
+| `index.js` | — | Orchestrator: detects `src/` prefix, resolves mergers, handles fallbacks |
+
+**Key features:**
+- Auto-detects `src/` directory structure and adjusts all paths accordingly
+- Downloads integration files from a dedicated branch (`#sanity-integration`)
+- Falls back to direct copy when no merger is defined for a file
+
+#### Sanity MCP Server & Agent Toolkit
+
+- Registers `https://mcp.sanity.io` as an MCP server during setup (Claude Code projects)
+- Installs `sanity-io/agent-toolkit` skills via `bunx skills add`
+
+#### Integration Files (moved to `integrations/sanity/`)
+
+Sanity CMS files are now centralized under `integrations/sanity/` instead of being duplicated across all four templates:
+
+- `app/studio/[[...tool]]/page.tsx` — Embedded Sanity Studio route
+- `app/studio/layout.tsx` — Studio layout (passthrough, no nested `<html>`)
+- `app/api/revalidate/route.ts` — On-demand ISR revalidation webhook
+- `app/api/draft-mode/{enable,disable}/route.ts` — Draft mode toggle
+- `app/layout.tsx` — Layout with Sanity providers
+- `app/sitemap.ts` — Sitemap with Sanity content routes
+- `lib/integrations/sanity/` — Client, schemas, queries, types, structure
+- `lib/integrations/check-integration.ts` — Integration checker
+- `lib/scripts/generate-page.ts` — Page scaffolding with Sanity schema support
+- `lib/utils/metadata.ts` — Sanity-aware metadata helpers
+- `components/ui/sanity-image/` — Sanity image component
+
+### Fixed
+
+#### Studio Hydration Errors
+
+`app/studio/layout.tsx` previously rendered its own `<html>` and `<body>` tags, causing React hydration mismatches when nested inside the root layout. The layout now passes `children` through directly.
+
+### Changed
+
+- **Templates cleaned up** — Removed duplicated Sanity files from `template/{default,webgl,webgpu,experiment}/`. Sanity is now injected at build time via the merger system.
+- **Removed `sanity:mcp` script** — The `copy-sanity-mcp.ts` script and its `package.json` entry were removed in favor of direct MCP registration via `claude mcp add`.
+- **`create.js` updated** — Sanity auto-setup (step 5.5), MCP registration (step 5.6), and conditional next-steps messaging added.
+- **`CLAUDE.md` updated** — Added guidance that nested layouts must not render `<html>` or `<body>` tags.
+
+### Files Added
+
+- `src/commands/setup-sanity.js`
+- `src/commands/add-integration.js`
+- `src/mergers/index.js`
+- `src/mergers/config.js`
+- `src/mergers/layout-merger.js`
+- `src/mergers/sitemap-merger.js`
+- `src/mergers/check-integration-merger.js`
+- `integrations/sanity/` (all CMS files)
+
+### Files Modified
+
+- `bin/index.js` — Added `--add` / `-a` flag routing
+- `src/commands/create.js` — Sanity auto-setup, MCP registration, agent toolkit
+- `CLAUDE.md` — Nested layout guidance
+- `package.json` — Updated dependencies

package/changelog/09-02-26.md

@@ -0,0 +1,83 @@
+# Changelog — February 9, 2026
+
+## Dynamic Layer Architecture (next-starter migration)
+
+Replaced the duplicated full-template system with a layer-based architecture. The CLI now clones `basementstudio/next-starter` as the base for all project types and overlays technology-specific layers on top, eliminating ~27,000 lines of duplicated code.
+
+### Added
+
+#### Layer Configuration System (`src/mergers/config.js`)
+
+Centralized configuration that defines per-layer dependencies, scripts, and dev dependencies.
+
+**Supported layers:**
+
+| Layer | Key Dependencies |
+|-------|-----------------|
+| `default` | (base next-starter, no extra deps) |
+| `webgl` | `@react-three/fiber`, `@react-three/drei`, `three`, `@types/three` |
+| `webgpu` | `three` (WebGPU renderer) |
+| `experiment` | (navigation/header components, no extra deps) |
+
+Each layer config specifies `dependencies`, `devDependencies`, and `scripts` that get injected into `package.json` during project hydration.
+
+#### Layer Files (`layers/`)
+
+Technology-specific files extracted from the old full templates into minimal overlay directories:
+
+- `layers/webgl/` — Custom `app/page.tsx`, WebGL canvas, and scene components
+- `layers/webgpu/` — `.gitkeep` placeholder (deps-only layer)
+- `layers/experiment/` — Header component, navigation menu, and constants
+
+#### Layer Injection Function (`src/mergers/index.js`)
+
+New `injectLayer()` function that copies layer-specific files on top of the cloned next-starter base. Handles file overlay with proper path resolution.
+
+#### Config-Driven Package Hydration
+
+`package.json` hydration now reads dependencies from `LAYER_CONFIG` instead of hardcoding them per template. The `hydratePackageJson()` function in `create.js` merges layer-specific deps, scripts, and devDeps into the base `package.json`.
+
+### Changed
+
+- **`create.js` — Clone source changed**: All template types now clone from `basementstudio/next-starter#main` instead of per-type template directories. Layer injection happens as a post-clone step.
+- **`create.js` — Template directory deleted after injection**: The CLI cleans up the local `layers/` artifacts from the generated project after overlay.
+- **`bin/index.js` — Command renamed**: Updated CLI command name.
+- **`src/commands/worktree.js`** — Minor update.
+- **`src/mergers/config.js`** — Added `LAYER_CONFIG` export with per-layer dependency maps.
+- **`src/mergers/index.js`** — Added `injectLayer()` alongside existing merger functions.
+
+### Removed
+
+- **`template/` directory** — Deleted all four full template directories (`default/`, `webgl/`, `webgpu/`, `experiment/`), removing ~27,000 lines of duplicated boilerplate. Each template previously contained a full copy of the next-starter codebase.
+
+### Files Added
+
+- `layers/webgl/app/page.tsx`
+- `layers/webgl/components/webgl/canvas/dynamic.tsx`
+- `layers/webgl/components/webgl/canvas/index.tsx`
+- `layers/webgl/components/webgl/components/scene/index.tsx`
+- `layers/webgpu/.gitkeep`
+- `layers/experiment/components/layout/header/index.tsx`
+- `layers/experiment/components/layout/navigation-menu.tsx`
+- `layers/experiment/lib/constants.ts`
+- `tasks/prd-next-starter-dynamic-layers.md`
+- `tasks/prd.json`
+- `tasks/progress.txt`
+
+### Files Modified
+
+- `bin/index.js`
+- `src/commands/create.js`
+- `src/commands/worktree.js`
+- `src/mergers/config.js`
+- `src/mergers/index.js`
+- `CLAUDE.md`
+- `README.md`
+- `package.json`
+
+### Files Deleted
+
+- `template/default/` (all files)
+- `template/webgl/` (all files)
+- `template/webgpu/` (all files)
+- `template/experiment/` (all files)

package/docs/fix-studio-hydration.md

@@ -0,0 +1,46 @@
+# Fix: Studio Hydration Errors
+
+## Problem
+
+`/studio` route produces two critical React hydration mismatch errors:
+
+1. **`<body>` style attribute mismatch** — Server renders inline `style={{margin: 0}}` on a nested `<body>` tag that conflicts with the root layout's `<body>`.
+2. **`<html>` tag attribute mismatch** — `dir`, `className` attributes differ between server and client because a second `<html>` tag is rendered inside the root layout's `<html>`.
+
+### Root Cause
+
+`app/studio/layout.tsx` renders its own `<html>` and `<body>` tags. In Next.js App Router, nested layouts do **not** replace the root layout — they render **inside** it. This creates duplicate `<html>` and `<body>` elements, causing hydration mismatches.
+
+## Fix
+
+### File: `app/studio/layout.tsx`
+
+**Before:**
+```tsx
+export default function StudioLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0 }}>{children}</body>
+    </html>
+  );
+}
+```
+
+**After:**
+```tsx
+export default function StudioLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return children;
+}
+```
+
+## Notes
+
+- There is also a `motion() is deprecated. Use motion.create() instead.` warning — this is upstream in the `sanity` package's internal use of framer-motion. No action needed on our end.

package/docs/plans/2026-01-29-sanity-smart-merge-design.md

@@ -0,0 +1,196 @@
+# Sanity Smart Merge Integration Design
+
+> Date: 2026-01-29
+> Status: Approved for implementation
+
+## Problem
+
+The current Sanity integration uses `tiged` to overlay files directly onto the selected template. This causes template-specific code to be completely overwritten, losing:
+- Template-specific providers and imports in `app/layout.tsx`
+- Template-specific sitemap entries in `app/sitemap.ts`
+- Other integration checks in `lib/integrations/check-integration.ts`
+
+## Solution
+
+Replace the blind file overlay with a **smart merge system** that:
+1. Copies additive files directly (new directories/files)
+2. Intelligently merges files that exist in both template and integration
+
+## Architecture
+
+### Current Flow (Broken)
+```
+1. Clone template via tiged
+2. Overlay integration via tiged (OVERWRITES files)
+3. Hydrate package.json
+```
+
+### New Flow (Smart Merge)
+```
+1. Clone template via tiged → targetDir
+2. Clone integration to TEMP directory (not targetDir)
+3. Process integration files:
+   a. ADDITIVE files → copy directly to targetDir
+   b. MERGE files → read both versions, merge, write result
+4. Clean up temp directory
+5. Hydrate package.json
+```
+
+## File Classification
+
+### Files Requiring Smart Merge
+| File | Merge Strategy |
+|------|----------------|
+| `app/layout.tsx` | Add imports, variables, and Sanity components after `{children}` |
+| `app/sitemap.ts` | Add imports and Sanity page/article fetching to return array |
+| `lib/integrations/check-integration.ts` | Append `isSanityConfigured()` function |
+
+### Additive Files (Direct Copy)
+- `lib/integrations/sanity/` — entire directory
+- `components/ui/sanity-image/` — new component
+- `app/api/draft-mode/` — new API routes
+- `lib/utils/metadata.ts` — new utility
+- `lib/scripts/generate-page.ts` — new script
+
+## New File Structure
+
+```
+src/
+├── commands/create.js          # Updated to use new merge logic
+├── mergers/                    # NEW: Smart merge functions
+│   ├── index.js               # Orchestrates merging
+│   ├── config.js              # File classification config
+│   ├── layout-merger.js       # Merges app/layout.tsx
+│   ├── sitemap-merger.js      # Merges app/sitemap.ts
+│   └── check-integration-merger.js  # Merges check-integration.ts
+└── utils/
+    └── file-utils.js          # Helper for reading/writing files
+```
+
+## Merge Strategies
+
+### Layout Merger (`app/layout.tsx`)
+
+**Injected imports:**
+```tsx
+import { draftMode } from 'next/headers'
+import { Suspense } from 'react'
+import { VisualEditing } from 'next-sanity'
+import { SanityLive } from '@/lib/integrations/sanity/live'
+import { isSanityConfigured } from '@/lib/integrations/check-integration'
+```
+
+**Injected variables (before return):**
+```tsx
+const isDraftMode = (await draftMode()).isEnabled
+const sanityConfigured = isSanityConfigured()
+```
+
+**Injected components (after {children}):**
+```tsx
+{sanityConfigured && isDraftMode && (
+  <Suspense fallback={null}>
+    <VisualEditing />
+    <SanityLive />
+  </Suspense>
+)}
+```
+
+### Sitemap Merger (`app/sitemap.ts`)
+
+**Injected imports:**
+```ts
+import { isSanityConfigured } from '@/lib/integrations/check-integration'
+import { client } from '@/lib/integrations/sanity/client'
+import { ALL_PAGES_SLUGS_QUERY, ALL_ARTICLES_SLUGS_QUERY } from '@/lib/integrations/sanity/queries'
+```
+
+**Injected fetch logic (before return):**
+```ts
+let sanityPages: MetadataRoute.Sitemap = []
+
+if (isSanityConfigured() && client) {
+  const [pages, articles] = await Promise.all([
+    client.fetch(ALL_PAGES_SLUGS_QUERY),
+    client.fetch(ALL_ARTICLES_SLUGS_QUERY),
+  ])
+
+  sanityPages = [
+    ...pages.map((page) => ({
+      url: `${baseUrl}/${page.slug}`,
+      lastModified: new Date(page._updatedAt),
+    })),
+    ...articles.map((article) => ({
+      url: `${baseUrl}/blog/${article.slug}`,
+      lastModified: new Date(article._updatedAt),
+    })),
+  ]
+}
+```
+
+**Modified return:**
+```ts
+return [
+  ...existingEntries,
+  ...sanityPages,
+]
+```
+
+### Check-Integration Merger
+
+**Appended function:**
+```ts
+export function isSanityConfigured(): boolean {
+  return Boolean(
+    process.env.NEXT_PUBLIC_SANITY_PROJECT_ID &&
+    process.env.NEXT_PUBLIC_SANITY_DATASET
+  )
+}
+```
+
+## Error Handling
+
+| Scenario | Handling |
+|----------|----------|
+| Template file doesn't exist | Copy from integration instead |
+| Integration file doesn't exist | Skip merge, continue |
+| `{children}` not found in layout | Fallback: append to end of body |
+| No `return` in sitemap | Create new sitemap structure |
+| `isSanityConfigured` already exists | Skip adding function |
+| Template uses different layout function name | Search for default export function |
+
+## Dependencies
+
+Add to CLI's `package.json`:
+```json
+{
+  "dependencies": {
+    "ts-morph": "^24.0.0"
+  }
+}
+```
+
+## User Feedback
+
+After merging, display:
+```
+✓ Sanity integration added:
+  ✓ Merged: app/layout.tsx
+  ✓ Merged: app/sitemap.ts
+  ✓ Merged: lib/integrations/check-integration.ts
+  ✓ Added: lib/integrations/sanity/ (14 files)
+  ✓ Added: components/ui/sanity-image/
+  ✓ Added: app/api/draft-mode/
+```
+
+## Implementation Tasks
+
+1. Create `src/mergers/` directory structure
+2. Implement `config.js` with file classifications
+3. Implement `layout-merger.js`
+4. Implement `sitemap-merger.js`
+5. Implement `check-integration-merger.js`
+6. Implement `index.js` orchestrator with error handling
+7. Update `src/commands/create.js` to use new merge system
+8. Add `ts-morph` dependency
+9. Test with all 4 templates (default, webgl, webgpu, experiment)