bsmnt 0.0.0

package/.changeset/2026-02-11-test-patch-bump.md

@@ -0,0 +1,5 @@
+---
+"bsmnt": patch
+---
+
+Rename package to bsmnt and trigger first patch release to 0.0.1.

package/.changeset/README.md

@@ -0,0 +1,10 @@
+# Changesets
+
+Create a changeset in feature branches before merging:
+
+```bash
+bun run changeset
+```
+
+On merge to `main`, GitHub Actions opens or updates a release PR with version/changelog changes.
+Merging that release PR publishes to npm via Trusted Publishing.

package/.changeset/config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "basementstudio/basement-cli"
+    }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.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.
+

package/.cursor/rules/architecture.mdc

@@ -0,0 +1,437 @@
+---
+alwaysApply: true
+---
+---
+description: Architecture patterns, state management, routing, and best practices
+globs: *.tsx, *.jsx, *.css, *.js, *.ts
+---
+
+# Architecture Guidelines
+
+## Type Safety
+
+### TypeScript Configuration
+- Use TypeScript for all new code
+- Maintain strict type checking
+- Avoid `any` types unless absolutely necessary
+- Use proper type imports (`import type` when importing only types)
+
+```tsx
+import type { ComponentProps } from 'react'
+
+interface ButtonProps extends ComponentProps<'button'> {
+  variant?: 'primary' | 'secondary'
+}
+```
+
+## State Management
+
+### React Built-in State
+Prefer React's built-in state for component state. Keep state as close to where it's used as possible.
+
+```tsx
+function Component() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+### Zustand for Global State
+Use Zustand for global state when needed. Define stores in `@/lib/store.ts` or dedicated store files.
+
+```tsx
+import { create } from 'zustand'
+
+interface CartStore {
+  items: CartItem[]
+  addItem: (item: CartItem) => void
+  removeItem: (id: string) => void
+}
+
+export const useCartStore = create<CartStore>((set) => ({
+  items: [],
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+  removeItem: (id) => set((state) => ({
+    items: state.items.filter(item => item.id !== id)
+  })),
+}))
+```
+
+### State Management Best Practices
+- Keep state minimal and derived values computed
+- Use context for shared UI state (theme, modals)
+- Use Zustand for complex global state (cart, user)
+- Avoid prop drilling with composition patterns
+
+## Routing & Navigation
+
+### Next.js App Router
+Use Next.js App Router conventions. Follow the file-based routing structure.
+
+```
+app/
+  (pages)/
+    home/
+      page.tsx
+    about/
+      page.tsx
+```
+
+### Navigation
+Use the custom Link component for internal navigation. It automatically handles external links.
+
+```tsx
+import { Link } from '@/components/ui'
+
+function Navigation() {
+  return (
+    <>
+      {/* Internal link - uses next/link */}
+      <Link href="/about">About</Link>
+
+      {/* External link - uses <a> with target="_blank" */}
+      <Link href="https://example.com">External</Link>
+    </>
+  )
+}
+```
+
+### Metadata & SEO
+Use `@/utils/metadata` for SEO optimization. Generate metadata for all pages.
+
+```tsx
+import { generatePageMetadata } from '@/utils/metadata'
+
+export async function generateMetadata({ params }) {
+  const page = await fetchPage(params.slug)
+
+  return generatePageMetadata({
+    title: page.title,
+    description: page.description,
+    image: { url: page.image },
+    url: `/pages/${params.slug}`,
+  })
+}
+```
+
+### Loading and Error States
+Implement proper loading and error states for all routes.
+
+```tsx
+// loading.tsx
+export default function Loading() {
+  return <div>Loading...</div>
+}
+
+// error.tsx
+'use client'
+
+export default function Error({ error, reset }) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  )
+}
+```
+
+## Performance
+
+### Server Components
+Use React Server Components by default. Only add 'use client' when needed.
+
+```tsx
+// Server Component (default)
+async function ServerComponent() {
+  const data = await fetchData()
+  return <div>{data.title}</div>
+}
+
+// Client Component (when needed)
+'use client'
+
+function ClientComponent() {
+  const [state, setState] = useState(0)
+  return <button onClick={() => setState(state + 1)}>{state}</button>
+}
+```
+
+### Code Splitting
+Use `next/dynamic` for heavy components. Implement proper loading states.
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
+  loading: () => <div>Loading...</div>,
+  ssr: false // if needed
+})
+```
+
+### Caching Strategies
+Follow Next.js 16 recommended caching strategies. Use appropriate revalidation times.
+
+```tsx
+// Static generation with revalidation
+export const revalidate = 3600 // 1 hour
+
+// Dynamic with specific cache tags
+export async function fetchData() {
+  const res = await fetch('https://api.example.com/data', {
+    next: {
+      revalidate: 3600,
+      tags: ['data']
+    }
+  })
+  return res.json()
+}
+
+// User-specific data - NEVER cache
+export async function fetchUserCart(userId: string) {
+  const res = await fetch(`https://api.example.com/cart/${userId}`, {
+    cache: 'no-store' // Required for user-specific data
+  })
+  return res.json()
+}
+```
+
+### Cache Components (Next.js 16)
+
+Cache Components are enabled globally (`cacheComponents: true`). Key considerations:
+
+**Suspense Boundaries:**
+```tsx
+import { Suspense } from 'react'
+
+export default async function Page() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <DataComponent />
+    </Suspense>
+  )
+}
+```
+
+**Cache Invalidation:**
+```tsx
+import { revalidateTag, revalidatePath } from 'next/cache'
+
+// In webhook handlers
+export async function POST(request: Request) {
+  revalidateTag('products')
+  // or
+  revalidatePath('/products/[slug]', 'page')
+  return Response.json({ revalidated: true })
+}
+```
+
+**⚠️ Critical Rules:**
+- User-specific data: Always use `cache: 'no-store'`
+- Real-time data: Always use `cache: 'no-store'`
+- Test with hard refresh AND navigation
+- Wrap data fetching in Suspense boundaries
+
+### Asset Optimization
+- Always use the custom `Image` component (`@/components/ui/image`)
+- Optimize bundles with tree-shaking
+- Check bundle size impact of new dependencies
+- Use `bun lint` to check for linting issues
+
+## Security
+
+### Environment Variables
+- Never commit API keys
+- Use `.env.local` for development
+- Document required variables in `.env.example`
+- Validate environment variables are set before use
+
+```typescript
+// Check required env vars at module load
+const requiredEnvVars = [
+  'NEXT_PUBLIC_API_KEY',
+  'DATABASE_URL',
+  'SANITY_API_TOKEN'
+] as const
+
+for (const envVar of requiredEnvVars) {
+  if (!process.env[envVar]) {
+    throw new Error(`Missing required environment variable: ${envVar}`)
+  }
+}
+```
+
+### Input Validation
+Validate all user inputs. Use server-side validation for forms.
+
+```tsx
+async function submitForm(formData: FormData) {
+  'use server'
+
+  const email = formData.get('email')
+
+  // Validate
+  if (!email || typeof email !== 'string') {
+    return { error: 'Invalid email' }
+  }
+
+  // Process
+  // ...
+}
+```
+
+### Authentication & Authorization
+- Implement proper authentication
+- Use server-side API calls for sensitive operations
+- Implement rate limiting where necessary
+- Follow CSP guidelines
+
+## Testing & Debugging
+
+### Unit Testing
+Write unit tests for critical functionality.
+
+```tsx
+import { render, screen } from '@testing-library/react'
+import Button from './Button'
+
+test('renders button with text', () => {
+  render(<Button>Click me</Button>)
+  expect(screen.getByText('Click me')).toBeInTheDocument()
+})
+```
+
+### Debugging Tools
+- Use React DevTools for component inspection
+
+### Error Boundaries
+Implement error boundaries for critical sections. Provide meaningful fallback UI.
+
+```tsx
+'use client'
+
+import { Component } from 'react'
+
+class ErrorBoundary extends Component {
+  state = { hasError: false }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true }
+  }
+
+  componentDidCatch(error, errorInfo) {
+    console.error('ErrorBoundary caught:', error, errorInfo)
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong.</div>
+    }
+
+    return this.props.children
+  }
+}
+```
+
+### Logging Best Practices
+- Use console.log for simple debugging (auto-stripped in production)
+- Use console.error and console.warn for important issues (kept in production)
+- Gate expensive debug operations with `process.env.NODE_ENV === 'development'`
+- Log errors with context for better debugging
+
+## Code Quality
+
+### Linting & Formatting
+- Follow Biome linting rules
+- Run `bun lint` before committing
+- Maintain consistent code style
+- Fix linting errors immediately
+
+### Code Organization
+- Follow the defined project structure
+- Maintain separation of concerns
+- Use meaningful variable and function names
+- Write meaningful comments and documentation
+- Prefer named exports for utilities
+
+### Component Composition
+Follow component composition patterns. Keep components focused and reusable.
+
+```tsx
+// Good: Composable components
+function Card({ children, className }) {
+  return <div className={cn(s.card, className)}>{children}</div>
+}
+
+function CardHeader({ children }) {
+  return <div className={s.header}>{children}</div>
+}
+
+function CardBody({ children }) {
+  return <div className={s.body}>{children}</div>
+}
+
+// Usage
+<Card>
+  <CardHeader>Title</CardHeader>
+  <CardBody>Content</CardBody>
+</Card>
+```
+
+## Development Workflow
+
+### Package Manager
+Use Bun as the JavaScript runtime and package manager.
+
+```bash
+# Install dependencies
+bun install
+
+# Run development server (with Turbopack)
+bun dev
+
+# Build for production
+bun run build
+
+# Run linting
+bun lint
+```
+
+### Git Workflow
+- Write meaningful commit messages
+- Use conventional commits when possible
+- Review changes before committing
+- DO NOT use `git push --force` without permission
+- DO NOT skip hooks (--no-verify) unless explicitly requested
+
+### Client/Server Boundaries
+Keep client/server boundaries clear. Understand when code runs where.
+
+```tsx
+// Server Component
+async function ServerComponent() {
+  'use server' // Optional annotation
+  const data = await fetchData() // Runs on server
+  return <ClientComponent data={data} />
+}
+
+// Client Component
+'use client'
+
+function ClientComponent({ data }) {
+  const [state, setState] = useState(data) // Runs on client
+  return <div>{state}</div>
+}
+```
+
+## Best Practices Summary
+
+1. **Type Safety**: Use TypeScript everywhere, avoid `any`
+2. **State Management**: React state first, Zustand for global needs
+3. **Performance**: Server components by default, code splitting for heavy components
+4. **Security**: Validate inputs, secure environment variables, server-side sensitive operations
+5. **Testing**: Write tests for critical paths, use debugging tools effectively
+6. **Code Quality**: Follow linting rules, maintain consistent style, write meaningful documentation
+7. **Development**: Use Bun, follow git best practices, understand client/server boundaries
+
+Last updated: 2026-01-26