bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/src/mergers/sitemap-merger.js

@@ -0,0 +1,121 @@
+// packages/create-basement-app/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 statement
+ * Uses early return pattern and spread operator for cleaner code
+ */
+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)) return baseRoutes
+
+      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}/\${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}/blog/\${article.slug.current}\`,
+          lastModified: new Date(article._updatedAt),
+          changeFrequency: "weekly" as const,
+          priority: 0.7,
+        }))
+
+      return [...baseRoutes, ...pageEntries, ...articleEntries]
+    } catch (error) {
+      console.error("Error generating sitemap from Sanity:", error)
+      return baseRoutes
+    }
+  }
+
+`;
+
+/**
+ * Merge Sanity integration into template sitemap
+ * Preserves all existing agnostic code (routes, baseRoutes structure)
+ * and injects Sanity-specific fetching logic
+ *
+ * @param {string} templatePath - Path to the template's sitemap.ts
+ * @returns {Promise<{skipped?: boolean, reason?: string, success?: boolean}>}
+ */
+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 final return statement
+	// Find the last "return baseRoutes" or "return [...baseRoutes" pattern
+	const returnMatch = content.match(
+		/(\n)([ \t]*)(return\s+(?:baseRoutes|\[\.\.\.baseRoutes))/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 };
+}

package/packages/create-basement-app/template-hooks/config.js

@@ -0,0 +1,38 @@
+// packages/create-basement-app/template-hooks/config.js
+
+/**
+ * Hook configuration manifest.
+ * Each entry describes a template hook, its source file, and npm dependencies.
+ */
+export const hooksConfig = [
+	{
+		name: "use-battery",
+		file: "use-battery.ts",
+		dependencies: {
+			"lodash-es": "^4.17.21",
+		},
+		devDependencies: {},
+	},
+	{
+		name: "use-device-perf",
+		file: "use-device-perf.ts",
+		dependencies: {
+			"detect-gpu": "^5.0.0",
+			"react-device-detect": "^2.2.3",
+			zustand: "^5.0.0",
+		},
+		devDependencies: {},
+	},
+	{
+		name: "use-intersection-observer",
+		file: "use-intersection-observer.ts",
+		dependencies: {},
+		devDependencies: {},
+	},
+	{
+		name: "use-media",
+		file: "use-media.ts",
+		dependencies: {},
+		devDependencies: {},
+	},
+];

package/packages/create-basement-app/templates/default/.biome/plugins/README.md

@@ -0,0 +1,21 @@
+## Plugins
+
+### 1. `no-anchor-element.grit`
+Enforces using Next.js `<Link>` component instead of HTML `<a>` elements.
+
+### 2. `no-unnecessary-forwardref.grit`
+Checks for unnecessary `forwardRef` usage in React 19 with the compiler.
+
+### 3. `no-relative-parent-imports.grit`
+Forbids relative parent imports (`../`) and encourages alias imports (`@/`).
+
+## Plugin Configuration
+
+The plugins are configured in `biome.json`:
+```json
+"plugins": [
+  "./biome-plugins/no-anchor-element.grit",
+  "./biome-plugins/no-unnecessary-forwardref.grit",
+  "./biome-plugins/no-relative-parent-imports.grit"
+]
+``` 

package/packages/create-basement-app/templates/default/.biome/plugins/no-anchor-element.grit

@@ -0,0 +1,12 @@
+language js;
+
+`<a $attrs>$content</a>` as $anchor where {
+    !$anchor <: within `if ($condition) { return ($jsx) }` where {
+        $condition <: contains or { `isExternal`, `isExternalSSR` }
+    },
+    register_diagnostic(
+        span = $anchor,
+        message = "Use custom Link component instead of <a> element. The Link component handles both internal and external links automatically.",
+        severity = "error"
+    )
+} 

package/packages/create-basement-app/templates/default/.biome/plugins/no-relative-parent-imports.grit

@@ -0,0 +1,10 @@
+language js;
+
+`import $imports from $source` as $import where {
+    $source <: r"['\"]\.\.\/\.\.\/.*['\"]",
+    register_diagnostic(
+        span = $import,
+        message = "Use alias imports (~/dir/) instead of deep relative imports (../../). Single level imports (../) are allowed for colocated files.",
+        severity = "error"
+    )
+} 

package/packages/create-basement-app/templates/default/.biome/plugins/no-unnecessary-forwardref.grit

@@ -0,0 +1,9 @@
+language js;
+
+`forwardRef($func)` as $ref where {
+    register_diagnostic(
+        span = $ref,
+        message = "forwardRef is unnecessary in React 19 with the compiler",
+        severity = "warning"
+    )
+} 

package/packages/create-basement-app/templates/default/.cursor/rules/README.md

@@ -0,0 +1,184 @@
+# Cursor Rules Documentation
+
+This directory contains consolidated Cursor AI rules for the Satus project. The rules are organized into 5 focused files for easy maintenance and efficient AI context loading.
+
+## 📁 File Structure
+
+### 1. `main.mdc` - Project Overview & Cross-Cutting Concerns
+**Purpose**: High-level overview and concerns that apply across the entire project
+
+**Contents**:
+- Technology stack (Next.js 16+, React 19+, Tailwind v4, Biome, Bun)
+- React 19+ new features (`<Activity />`, `useEffectEvent`, `cacheSignal`)
+- Next.js 16 Cache Components gotchas and best practices
+- File organization
+- React Compiler & memoization guidelines (single source of truth)
+- Image optimization guidelines (single source of truth)
+- Development vs production guidelines (single source of truth)
+- Core utility libraries (`@/utils`)
+
+**When to reference**: Starting a new project, understanding the tech stack, cross-cutting concerns
+
+---
+
+### 2. `components.mdc` - React Component Patterns & WebGL
+**Purpose**: All React component patterns including standard components and WebGL/Three.js
+
+**Contents**:
+- Component structure and imports
+- Props interfaces and React 19 ref handling
+- Forms and responsive design
+- Performance best practices (code splitting)
+- Error handling
+- WebGL/Three.js setup and patterns
+- React Three Fiber
+- Drei components
+- Custom shaders
+- Animation and interaction
+- Post-processing
+
+**When to reference**: Building React components, creating WebGL experiences, working with Three.js
+
+---
+
+### 3. `styling.mdc` - CSS Modules & Tailwind CSS v4
+**Purpose**: All styling approaches including CSS Modules and Tailwind CSS v4
+
+**Contents**:
+- CSS Modules (file naming, class naming, imports)
+- Responsive design (viewport functions, breakpoints, grid system)
+- Typography and colors
+- Animations and transitions
+- Tailwind CSS v4 (CSS-first configuration, theme variables, new features)
+- 3D transforms, gradients, shadows
+- New variants (composable, `starting`, `not-*`, `nth-*`)
+- Custom extensions (`@utility`, `@variant`, `@plugin`)
+- Breaking changes and migration
+- Project-specific custom utilities (`b-*` classes)
+- PostCSS functions
+
+**When to reference**: Styling components, using Tailwind, creating responsive designs
+
+---
+
+### 4. `integrations.mdc` - Third-Party Integrations
+**Purpose**: Guidelines for all third-party service integrations
+
+**Contents**:
+- **Sanity CMS**: Configuration, schema management, GROQ queries, visual editing, TypeScript generation, cacheSignal integration
+- **Shopify**: API configuration, product management, cart operations, cacheSignal integration
+- General best practices (environment variables, API resilience, error handling)
+- Cache Components gotchas for integrations (user-specific data, real-time data)
+- Type safety and performance
+- Security and integration management
+- Webhook handling
+
+**When to reference**: Integrating with Sanity, Shopify, or other third-party services
+
+---
+
+### 5. `architecture.mdc` - Architecture Patterns & Best Practices
+**Purpose**: Architectural patterns, state management, routing, and code quality guidelines
+
+**Contents**:
+- Type safety (TypeScript configuration)
+- State management (React state, Zustand)
+- Routing & navigation (Next.js App Router, Link component)
+- Metadata & SEO
+- Performance (server components, code splitting, caching)
+- Cache Components (Next.js 16) - Suspense, invalidation, gotchas
+- Security (environment variables, input validation, authentication)
+- Testing & debugging (unit tests, debugging tools, error boundaries)
+- Code quality (linting, formatting, code organization)
+- Development workflow (package manager, git workflow, client/server boundaries)
+
+**When to reference**: Architectural decisions, state management, routing patterns, code quality
+
+---
+
+## 🎯 Quick Reference Guide
+
+### I want to...
+
+- **Start a new feature** → Read `main.mdc` for overview, then `architecture.mdc` for patterns
+- **Build a React component** → `components.mdc`
+- **Add WebGL/Three.js** → `components.mdc` § WebGL Components & Activity Integration
+- **Style with CSS Modules** → `styling.mdc` § CSS Modules
+- **Style with Tailwind** → `styling.mdc` § Tailwind CSS v4
+- **Use custom utilities** → `styling.mdc` § Project-Specific Custom Utilities
+- **Integrate Sanity CMS** → `integrations.mdc` § Sanity CMS Integration
+- **Integrate Shopify** → `integrations.mdc` § Shopify Integration
+- **Manage state** → `architecture.mdc` § State Management
+- **Add routing** → `architecture.mdc` § Routing & Navigation
+- **Optimize performance** → `architecture.mdc` § Performance
+- **Handle security** → `architecture.mdc` § Security
+- **Debug issues** → `architecture.mdc` § Testing & Debugging
+- **Understand React Compiler** → `main.mdc` § React Compiler & Memoization
+- **Handle images** → `main.mdc` § Image Optimization (`@/components/ui/image`)
+- **Dev vs prod differences** → `main.mdc` § Development vs Production
+- **Use utility functions** → `main.mdc` § Core Utility Libraries (`@/utils`)
+
+---
+
+## 📝 Maintenance Guidelines
+
+### When Editing Rules
+
+1. **Avoid Duplication**: If content applies to multiple areas, put it in `main.mdc` and reference it
+2. **Use Cross-References**: Link to other sections instead of duplicating content
+3. **Keep It Focused**: Each file should maintain its specific purpose
+4. **Update Dates**: Update the "Last updated" date when making changes
+5. **Check Dependencies**: When updating one file, check if related files need updates
+
+### Example Cross-Reference Pattern
+
+```markdown
+<!-- In components.mdc -->
+## Performance Optimization
+See main.mdc § React Compiler & Memoization for optimization guidelines.
+```
+
+### Adding New Content
+
+**Ask yourself**:
+- Is this component-specific? → `components.mdc`
+- Is this styling-related? → `styling.mdc`
+- Is this an integration? → `integrations.mdc`
+- Is this architectural? → `architecture.mdc`
+- Is this cross-cutting? → `main.mdc`
+
+---
+
+## 🚀 For Developers
+
+### Quick Setup
+1. These rules are automatically loaded by Cursor AI
+2. All files have `alwaysApply: true` in frontmatter
+3. Files apply to: `*.tsx, *.jsx, *.css, *.js, *.ts`
+
+### Contributing
+When adding new guidelines:
+1. Choose the appropriate file
+2. Follow existing formatting patterns
+3. Add clear examples
+4. Update this README if needed
+5. Keep content focused and actionable
+
+---
+
+## 📊 File Statistics
+
+| File | Purpose | Key Topics |
+|------|---------|------------|
+| `main.mdc` | Overview & Cross-cutting | Tech stack, React 19+ features, Cache Components, React Compiler, Images, Dev/Prod |
+| `components.mdc` | React & WebGL | Components, Forms, WebGL, Three.js, Shaders, Activity |
+| `styling.mdc` | All Styling | CSS Modules, Tailwind v4, Responsive, Custom utilities |
+| `integrations.mdc` | Third-party Services | Sanity, Shopify, Cache Components, cacheSignal |
+| `architecture.mdc` | Patterns & Quality | State, Routing, Performance, Cache Components, Security, Testing |
+
+---
+
+Last updated: 2026-01-26
+
+For questions or suggestions about these rules, contact the development team.
+