bsmnt 0.0.0

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

@@ -0,0 +1,695 @@
+# Sanity Smart Merge Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the blind tiged overlay with a smart merge system that preserves template-specific code while adding Sanity integration.
+
+**Architecture:** Clone integration to temp directory, then process files in two modes: (1) additive files are copied directly, (2) merge files are intelligently combined using string manipulation to inject Sanity-specific imports, variables, and components.
+
+**Tech Stack:** Node.js, fs-extra (already installed), no new dependencies needed (using string manipulation instead of ts-morph for simplicity).
+
+---
+
+## Task 1: Create Merger Config
+
+**Files:**
+- Create: `src/mergers/config.js`
+
+**Step 1: Create the mergers directory**
+
+```bash
+mkdir -p src/mergers
+```
+
+**Step 2: Write the config file**
+
+```js
+// src/mergers/config.js
+
+/**
+ * Files that need smart merging (exist in both template and integration)
+ */
+export const MERGE_FILES = [
+  'app/layout.tsx',
+  'app/sitemap.ts',
+  'lib/integrations/check-integration.ts',
+]
+
+/**
+ * Paths that are purely additive (copy directly, no conflict)
+ */
+export const ADDITIVE_PATHS = [
+  'lib/integrations/sanity',
+  'components/ui/sanity-image',
+  'app/api/draft-mode',
+  'lib/utils/metadata.ts',
+  'lib/scripts/generate-page.ts',
+  'lib/integrations/README.md',
+]
+```
+
+**Step 3: Commit**
+
+```bash
+git add src/mergers/config.js
+git commit -m "feat(mergers): add file classification config"
+```
+
+---
+
+## Task 2: Create Layout Merger
+
+**Files:**
+- Create: `src/mergers/layout-merger.js`
+
+**Step 1: Write the layout merger**
+
+```js
+// src/mergers/layout-merger.js
+import fs from 'fs-extra'
+
+/**
+ * Sanity-specific imports to inject into layout
+ */
+const SANITY_IMPORTS = `import { draftMode } from "next/headers"
+import { VisualEditing } from "next-sanity/visual-editing"
+import { isSanityConfigured } from "@/lib/integrations/check-integration"
+import { SanityLive } from "@/lib/integrations/sanity/live"`
+
+/**
+ * Sanity-specific variables to inject before return statement
+ */
+const SANITY_VARIABLES = `  const { isEnabled: isDraftMode } = await draftMode()
+  const sanityConfigured = isSanityConfigured()
+`
+
+/**
+ * Sanity components to inject after {children}
+ */
+const SANITY_COMPONENTS = `
+        {/* Sanity Visual Editing - only when draft mode is enabled */}
+        {sanityConfigured && isDraftMode && (
+          <Suspense fallback={null}>
+            <VisualEditing />
+            <SanityLive />
+          </Suspense>
+        )}`
+
+/**
+ * Merge Sanity integration into template layout
+ * @param {string} templatePath - Path to the template's layout.tsx
+ */
+export async function mergeLayout(templatePath) {
+  let content = await fs.readFile(templatePath, 'utf-8')
+
+  // Skip if already has Sanity integration
+  if (content.includes('isSanityConfigured')) {
+    return { skipped: true, reason: 'Already has Sanity integration' }
+  }
+
+  // 1. Add Sanity imports after existing imports
+  // Find the last import statement
+  const importMatches = [...content.matchAll(/^import .+$/gm)]
+  if (importMatches.length > 0) {
+    const lastImport = importMatches[importMatches.length - 1]
+    const insertPos = lastImport.index + lastImport[0].length
+    content = content.slice(0, insertPos) + '\n' + SANITY_IMPORTS + content.slice(insertPos)
+  }
+
+  // 2. Add Sanity variables before the return statement in the Layout function
+  // Find "export default async function Layout" or similar and its return statement
+  const returnMatch = content.match(/export default async function \w+[^{]*\{[\s\S]*?(return\s*\()/m)
+  if (returnMatch) {
+    const returnIndex = content.indexOf(returnMatch[1], returnMatch.index)
+    content = content.slice(0, returnIndex) + SANITY_VARIABLES + '\n  ' + content.slice(returnIndex)
+  }
+
+  // 3. Add Sanity components after {children}
+  // Find {children} inside <body> and add Sanity components after it
+  const childrenMatch = content.match(/(\{children\})([\s\S]*?)(<\/body>)/m)
+  if (childrenMatch) {
+    content = content.replace(
+      /(\{children\})([\s\S]*?)(<\/body>)/m,
+      `$1${SANITY_COMPONENTS}$2$3`
+    )
+  }
+
+  await fs.writeFile(templatePath, content)
+  return { success: true }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/mergers/layout-merger.js
+git commit -m "feat(mergers): add layout merger for Sanity integration"
+```
+
+---
+
+## Task 3: Create Sitemap Merger
+
+**Files:**
+- Create: `src/mergers/sitemap-merger.js`
+
+**Step 1: Write the sitemap merger**
+
+```js
+// src/mergers/sitemap-merger.js
+import fs from 'fs-extra'
+
+/**
+ * Sanity-specific import to add
+ */
+const SANITY_IMPORT = `import { isSanityConfigured } from "@/lib/integrations/check-integration"`
+
+/**
+ * Sanity fetch logic to inject before return
+ */
+const SANITY_FETCH_LOGIC = `
+  // Only fetch Sanity pages if Sanity is configured
+  if (isSanityConfigured()) {
+    try {
+      const sanityModule = await import("@/lib/integrations/sanity/client")
+      const sanityGroq = await import("next-sanity")
+
+      const client = sanityModule?.client
+      const groq = sanityGroq?.groq
+
+      // Skip if client is null (shouldn't happen since we check isSanityConfigured)
+      if (client && groq) {
+        type SanityDocument = {
+          slug: { current: string }
+          _updatedAt: string
+          metadata?: { noIndex?: boolean }
+        }
+
+        // Fetch all published pages and articles
+        const pages = (await client.fetch(
+          groq\`*[_type == "page" && defined(slug.current)] {
+            slug,
+            _updatedAt,
+            metadata
+          }\`
+        )) as SanityDocument[]
+
+        const articles = (await client.fetch(
+          groq\`*[_type == "article" && defined(slug.current)] {
+            slug,
+            _updatedAt,
+            metadata
+          }\`
+        )) as SanityDocument[]
+
+        // Add pages to sitemap (exclude noIndex pages)
+        const pageEntries: MetadataRoute.Sitemap = pages
+          .filter((page: SanityDocument) => !page.metadata?.noIndex)
+          .map((page: SanityDocument) => ({
+            url: \`\${APP_BASE_URL}/sanity/\${page.slug.current}\`,
+            lastModified: new Date(page._updatedAt),
+            changeFrequency: "weekly" as const,
+            priority: 0.8,
+          }))
+
+        // Add articles to sitemap (exclude noIndex articles)
+        const articleEntries: MetadataRoute.Sitemap = articles
+          .filter((article: SanityDocument) => !article.metadata?.noIndex)
+          .map((article: SanityDocument) => ({
+            url: \`\${APP_BASE_URL}/sanity/\${article.slug.current}\`,
+            lastModified: new Date(article._updatedAt),
+            changeFrequency: "weekly" as const,
+            priority: 0.7,
+          }))
+
+        baseRoutes.push(...pageEntries, ...articleEntries)
+      }
+    } catch (error) {
+      console.error("Error generating sitemap from Sanity:", error)
+    }
+  }
+`
+
+/**
+ * Merge Sanity integration into template sitemap
+ * @param {string} templatePath - Path to the template's sitemap.ts
+ */
+export async function mergeSitemap(templatePath) {
+  let content = await fs.readFile(templatePath, 'utf-8')
+
+  // Skip if already has Sanity integration
+  if (content.includes('isSanityConfigured')) {
+    return { skipped: true, reason: 'Already has Sanity integration' }
+  }
+
+  // 1. Add Sanity import after existing imports
+  const importMatches = [...content.matchAll(/^import .+$/gm)]
+  if (importMatches.length > 0) {
+    const lastImport = importMatches[importMatches.length - 1]
+    const insertPos = lastImport.index + lastImport[0].length
+    content = content.slice(0, insertPos) + '\n' + SANITY_IMPORT + content.slice(insertPos)
+  }
+
+  // 2. Add Sanity fetch logic before the return statement
+  // Find "return baseRoutes" or similar return statement
+  const returnMatch = content.match(/(\n)([ \t]*)(return\s+\w+)/m)
+  if (returnMatch) {
+    const returnIndex = content.indexOf(returnMatch[0])
+    content = content.slice(0, returnIndex) + SANITY_FETCH_LOGIC + content.slice(returnIndex)
+  }
+
+  await fs.writeFile(templatePath, content)
+  return { success: true }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/mergers/sitemap-merger.js
+git commit -m "feat(mergers): add sitemap merger for Sanity integration"
+```
+
+---
+
+## Task 4: Create Check-Integration Merger
+
+**Files:**
+- Create: `src/mergers/check-integration-merger.js`
+
+**Step 1: Write the check-integration merger**
+
+```js
+// src/mergers/check-integration-merger.js
+import fs from 'fs-extra'
+
+/**
+ * Sanity configuration check function to add
+ */
+const SANITY_FUNCTION = `
+/**
+ * Check if Sanity CMS is configured
+ * Requires: NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET
+ */
+export function isSanityConfigured(): boolean {
+  return Boolean(
+    process.env.NEXT_PUBLIC_SANITY_PROJECT_ID &&
+      process.env.NEXT_PUBLIC_SANITY_DATASET
+  )
+}
+`
+
+/**
+ * Update to getConfiguredIntegrations to include Sanity
+ */
+const SANITY_CONFIGURED_CHECK = `  if (isSanityConfigured()) integrations.push("Sanity")`
+
+/**
+ * Update to getUnconfiguredIntegrations to include Sanity
+ */
+const SANITY_UNCONFIGURED_CHECK = `  if (!isSanityConfigured()) integrations.push("Sanity")`
+
+/**
+ * Merge Sanity integration into template check-integration
+ * @param {string} templatePath - Path to the template's check-integration.ts
+ */
+export async function mergeCheckIntegration(templatePath) {
+  let content = await fs.readFile(templatePath, 'utf-8')
+
+  // Skip if already has isSanityConfigured
+  if (content.includes('isSanityConfigured')) {
+    return { skipped: true, reason: 'Already has isSanityConfigured' }
+  }
+
+  // 1. Add isSanityConfigured function after isAnalyticsConfigured
+  const analyticsMatch = content.match(/(export function isAnalyticsConfigured\(\)[^}]+\})/s)
+  if (analyticsMatch) {
+    const insertPos = analyticsMatch.index + analyticsMatch[0].length
+    content = content.slice(0, insertPos) + '\n' + SANITY_FUNCTION + content.slice(insertPos)
+  } else {
+    // If no isAnalyticsConfigured, add before getConfiguredIntegrations
+    const getConfiguredMatch = content.match(/export function getConfiguredIntegrations/)
+    if (getConfiguredMatch) {
+      content = content.slice(0, getConfiguredMatch.index) + SANITY_FUNCTION + '\n' + content.slice(getConfiguredMatch.index)
+    } else {
+      // Fallback: append to end
+      content = content.trimEnd() + '\n' + SANITY_FUNCTION
+    }
+  }
+
+  // 2. Update getConfiguredIntegrations to include Sanity check
+  const configuredFnMatch = content.match(/(export function getConfiguredIntegrations\(\)[^{]*\{[\s\S]*?)(if \(isAnalyticsConfigured\(\)\))/m)
+  if (configuredFnMatch) {
+    const insertPos = content.indexOf(configuredFnMatch[2], configuredFnMatch.index)
+    content = content.slice(0, insertPos) + SANITY_CONFIGURED_CHECK + '\n  ' + content.slice(insertPos)
+  }
+
+  // 3. Update getUnconfiguredIntegrations to include Sanity check
+  const unconfiguredFnMatch = content.match(/(export function getUnconfiguredIntegrations\(\)[^{]*\{[\s\S]*?)(if \(!isAnalyticsConfigured\(\)\))/m)
+  if (unconfiguredFnMatch) {
+    const insertPos = content.indexOf(unconfiguredFnMatch[2], unconfiguredFnMatch.index)
+    content = content.slice(0, insertPos) + SANITY_UNCONFIGURED_CHECK + '\n  ' + content.slice(insertPos)
+  }
+
+  await fs.writeFile(templatePath, content)
+  return { success: true }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/mergers/check-integration-merger.js
+git commit -m "feat(mergers): add check-integration merger for Sanity"
+```
+
+---
+
+## Task 5: Create Merger Orchestrator
+
+**Files:**
+- Create: `src/mergers/index.js`
+
+**Step 1: Write the orchestrator**
+
+```js
+// src/mergers/index.js
+import fs from 'fs-extra'
+import path from 'path'
+import os from 'os'
+import tiged from 'tiged'
+import { MERGE_FILES, ADDITIVE_PATHS } from './config.js'
+import { mergeLayout } from './layout-merger.js'
+import { mergeSitemap } from './sitemap-merger.js'
+import { mergeCheckIntegration } from './check-integration-merger.js'
+
+/**
+ * Map of file paths to their merger functions
+ */
+const MERGERS = {
+  'app/layout.tsx': mergeLayout,
+  'app/sitemap.ts': mergeSitemap,
+  'lib/integrations/check-integration.ts': mergeCheckIntegration,
+}
+
+/**
+ * Inject Sanity integration using smart merge
+ * @param {string} targetDir - The project directory
+ * @param {string} cms - The CMS name (e.g., 'sanity')
+ * @param {object} spinner - Ora spinner for progress
+ * @returns {object} Results of the merge operation
+ */
+export async function injectIntegration(targetDir, cms, spinner) {
+  const results = {
+    merged: [],
+    copied: [],
+    skipped: [],
+    failed: [],
+  }
+
+  // 1. Clone integration to temp directory
+  const tempDir = path.join(os.tmpdir(), `integration-${Date.now()}`)
+
+  try {
+    spinner.text = `Downloading ${cms} integration...`
+
+    const integrationRepoPath = `github:basementstudio/basement-cli/integrations/${cms}#sanity-integration`
+    const emitter = tiged(integrationRepoPath, {
+      cache: false,
+      force: true,
+      mode: 'git',
+    })
+
+    await emitter.clone(tempDir)
+
+    // 2. Copy additive files/directories
+    spinner.text = `Adding ${cms} files...`
+
+    for (const additivePath of ADDITIVE_PATHS) {
+      const src = path.join(tempDir, additivePath)
+      const dest = path.join(targetDir, additivePath)
+
+      try {
+        if (await fs.pathExists(src)) {
+          await fs.copy(src, dest, { overwrite: false })
+          results.copied.push(additivePath)
+        }
+      } catch (error) {
+        results.failed.push({ path: additivePath, error: error.message })
+      }
+    }
+
+    // 3. Smart merge files that exist in both
+    spinner.text = `Merging ${cms} integration...`
+
+    for (const mergeFile of MERGE_FILES) {
+      const templateFile = path.join(targetDir, mergeFile)
+      const integrationFile = path.join(tempDir, mergeFile)
+      const merger = MERGERS[mergeFile]
+
+      try {
+        // Check if template file exists
+        if (!(await fs.pathExists(templateFile))) {
+          // Template doesn't have this file - copy from integration
+          if (await fs.pathExists(integrationFile)) {
+            await fs.copy(integrationFile, templateFile)
+            results.copied.push(mergeFile)
+          } else {
+            results.skipped.push({ path: mergeFile, reason: 'Not in integration' })
+          }
+          continue
+        }
+
+        // Check if integration file exists
+        if (!(await fs.pathExists(integrationFile))) {
+          results.skipped.push({ path: mergeFile, reason: 'Not in integration' })
+          continue
+        }
+
+        // Run the merger
+        if (merger) {
+          const result = await merger(templateFile)
+          if (result.skipped) {
+            results.skipped.push({ path: mergeFile, reason: result.reason })
+          } else {
+            results.merged.push(mergeFile)
+          }
+        }
+      } catch (error) {
+        results.failed.push({ path: mergeFile, error: error.message })
+      }
+    }
+
+  } finally {
+    // 4. Cleanup temp directory
+    try {
+      await fs.remove(tempDir)
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  return results
+}
+
+/**
+ * Format merge results for display
+ * @param {object} results - Results from injectIntegration
+ * @returns {string[]} Lines to display
+ */
+export function formatMergeResults(results) {
+  const lines = []
+
+  if (results.merged.length > 0) {
+    lines.push(...results.merged.map(f => `  ✓ Merged: ${f}`))
+  }
+
+  if (results.copied.length > 0) {
+    lines.push(...results.copied.map(f => `  ✓ Added: ${f}`))
+  }
+
+  if (results.skipped.length > 0) {
+    lines.push(...results.skipped.map(s => `  ○ Skipped: ${s.path} (${s.reason})`))
+  }
+
+  if (results.failed.length > 0) {
+    lines.push(...results.failed.map(f => `  ✗ Failed: ${f.path} (${f.error})`))
+  }
+
+  return lines
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/mergers/index.js
+git commit -m "feat(mergers): add orchestrator with smart merge logic"
+```
+
+---
+
+## Task 6: Update create.js to Use Smart Merge
+
+**Files:**
+- Modify: `src/commands/create.js:137-164`
+
+**Step 1: Update the integration injection section**
+
+Replace lines 137-164 in `src/commands/create.js`:
+
+```js
+    // 3.5. Inject Integration Files (Smart Merge)
+    if (cms && cms !== "none") {
+      const integrationSpinner = ora(
+        `Integrating ${pc.cyan(cms)}...`
+      ).start();
+
+      try {
+        const { injectIntegration, formatMergeResults } = await import('../mergers/index.js');
+        const results = await injectIntegration(targetDir, cms, integrationSpinner);
+
+        const hasErrors = results.failed.length > 0;
+        const resultLines = formatMergeResults(results);
+
+        if (hasErrors) {
+          integrationSpinner.warn(pc.yellow(`${cms} integration completed with warnings:`));
+        } else {
+          integrationSpinner.succeed(pc.green(`${cms} integration added:`));
+        }
+
+        // Display detailed results
+        resultLines.forEach(line => console.log(pc.dim(line)));
+
+      } catch (e) {
+        integrationSpinner.warn(
+          pc.yellow(`Failed to inject ${cms} integration: ${e.message}`)
+        );
+      }
+    }
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/commands/create.js
+git commit -m "feat(create): use smart merge for CMS integration"
+```
+
+---
+
+## Task 7: Test with Default Template
+
+**Step 1: Link the CLI locally**
+
+```bash
+npm link
+```
+
+**Step 2: Create a test project with default template + Sanity**
+
+```bash
+cd /tmp
+basement
+# Select: my-test-app, default, sanity, none, claude, no hooks
+```
+
+**Step 3: Verify the merged files**
+
+Check `app/layout.tsx`:
+- Should have original template structure
+- Should have Sanity imports added
+- Should have draftMode variables
+- Should have Sanity components after {children}
+
+Check `app/sitemap.ts`:
+- Should have original baseRoutes
+- Should have isSanityConfigured import
+- Should have Sanity fetch logic
+
+Check `lib/integrations/check-integration.ts`:
+- Should have isAnalyticsConfigured (from template)
+- Should have isSanityConfigured (added)
+- Should have updated getConfiguredIntegrations
+
+Check additive files exist:
+- `lib/integrations/sanity/` directory
+- `components/ui/sanity-image/`
+- `app/api/draft-mode/`
+
+**Step 4: Verify the project builds**
+
+```bash
+cd my-test-app
+bun install
+bun build
+```
+
+Expected: Build succeeds without errors
+
+**Step 5: Commit test results (if any fixes needed)**
+
+```bash
+git add -A
+git commit -m "fix(mergers): address issues found during testing"
+```
+
+---
+
+## Task 8: Test with WebGPU Template
+
+**Step 1: Create a test project with webgpu template + Sanity**
+
+```bash
+cd /tmp
+rm -rf my-test-webgpu
+basement
+# Select: my-test-webgpu, webgpu, sanity, none, claude, no hooks
+```
+
+**Step 2: Verify the merged files preserve WebGPU-specific code**
+
+Check `app/layout.tsx`:
+- Should preserve WebGPU providers/imports
+- Should have Sanity additions
+
+**Step 3: Verify the project builds**
+
+```bash
+cd my-test-webgpu
+bun install
+bun build
+```
+
+Expected: Build succeeds without errors
+
+---
+
+## Task 9: Final Cleanup and Documentation
+
+**Step 1: Update the CLI's README if needed**
+
+Document the new smart merge behavior.
+
+**Step 2: Final commit**
+
+```bash
+git add -A
+git commit -m "docs: document smart merge integration system"
+```
+
+---
+
+## Summary
+
+| Task | Description | Files |
+|------|-------------|-------|
+| 1 | Create merger config | `src/mergers/config.js` |
+| 2 | Create layout merger | `src/mergers/layout-merger.js` |
+| 3 | Create sitemap merger | `src/mergers/sitemap-merger.js` |
+| 4 | Create check-integration merger | `src/mergers/check-integration-merger.js` |
+| 5 | Create orchestrator | `src/mergers/index.js` |
+| 6 | Update create.js | `src/commands/create.js` |
+| 7 | Test with default template | Manual testing |
+| 8 | Test with webgpu template | Manual testing |
+| 9 | Final cleanup | Documentation |