bsmnt 0.0.0

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] `bun lint` passes
+- [ ] Tested locally in dev mode
+- [ ] No breaking changes (or documented in summary)
+

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run check
+
+      - name: Build
+        run: bun run build
+
+      - name: Ensure changeset exists for PR changes
+        if: github.event_name == 'pull_request'
+        run: bunx changeset status --since=origin/${{ github.base_ref }}

package/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Version and Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Setup Node for npm publishing
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Use npm 11.6.2
+        run: npm i -g npm@11.6.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Configure npm for publishing
+        run: |
+          cat > ~/.npmrc <<'EOF'
+          registry=https://registry.npmjs.org/
+          access=public
+          EOF
+
+      - name: Version packages or publish
+        uses: changesets/action@v1
+        with:
+          version: bun run version-packages
+          publish: bun run release
+          createGithubReleases: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.tldr/cache/call_graph.json

@@ -0,0 +1,7 @@
+{
+  "edges": [],
+  "languages": [
+    "typescript"
+  ],
+  "timestamp": 1769018359.8225532
+}

package/.tldr/languages.json

@@ -0,0 +1,6 @@
+{
+  "languages": [
+    "typescript"
+  ],
+  "timestamp": 1769018359.822764
+}

package/.tldr/status

@@ -0,0 +1 @@
+stopped

package/.tldrignore

@@ -0,0 +1,84 @@
+# TLDR ignore patterns (gitignore syntax)
+# Auto-generated - review and customize for your project
+# Docs: https://git-scm.com/docs/gitignore
+
+# ===================
+# Dependencies
+# ===================
+node_modules/
+.venv/
+venv/
+env/
+__pycache__/
+.tox/
+.nox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+vendor/
+Pods/
+
+# ===================
+# Build outputs
+# ===================
+dist/
+build/
+out/
+target/
+*.egg-info/
+*.whl
+*.pyc
+*.pyo
+
+# ===================
+# Binary/large files
+# ===================
+*.so
+*.dylib
+*.dll
+*.exe
+*.bin
+*.o
+*.a
+*.lib
+
+# ===================
+# IDE/editors
+# ===================
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# ===================
+# Security (always exclude)
+# ===================
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.*
+secrets.*
+
+# ===================
+# Version control
+# ===================
+.git/
+.hg/
+.svn/
+
+# ===================
+# OS files
+# ===================
+.DS_Store
+Thumbs.db
+
+# ===================
+# Project-specific
+# Add your custom patterns below
+# ===================
+# large_test_fixtures/
+# data/

package/.vscode/extensions.json

@@ -0,0 +1,20 @@
+{
+  "recommendations": [
+    // Formatting & Linting
+    "biomejs.biome",
+
+    // CSS & Styling
+    "bradlc.vscode-tailwindcss",
+    "csstools.postcss",
+
+    // GraphQL (Shopify, etc.)
+    "graphql.vscode-graphql-syntax",
+
+    // Sanity CMS (GROQ syntax + validation)
+    "sanity-io.vscode-sanity",
+
+    // DX Enhancements
+    "yoavbls.pretty-ts-errors",
+    "waderyan.gitblame"
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,98 @@
+{
+  // Formatting
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "biomejs.biome",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "always",
+    "source.organizeImports.biome": "always"
+  },
+
+  // TypeScript
+  "typescript.suggest.autoImports": true,
+  "typescript.preferences.importModuleSpecifier": "non-relative",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  // "typescript.experimental.useTsgo": true, // Disabled: tsgo doesn't support Next.js plugin
+  "javascript.suggest.autoImports": true,
+
+  // Editor labels (fixed for .tsx files)
+  "workbench.editor.customLabels.patterns": {
+    "**/app/**/page.tsx": "${dirname(1)}/${dirname} <page>",
+    "**/app/**/layout.tsx": "${dirname(1)}/${dirname} <layout>",
+    "**/app/api/**/route.ts": "${dirname(1)}/${dirname} <route>",
+    "**/components/**/index.tsx": "${dirname} <component>"
+  },
+
+  // File associations
+  "files.associations": {
+    "*.json": "jsonc"
+  },
+
+  // CSS (Tailwind v4)
+  "css.lint.validProperties": ["user-drag"],
+  "css.lint.unknownAtRules": "ignore",
+  "tailwindCSS.experimental.configFile": "./lib/styles/css/tailwind.css",
+  "tailwindCSS.includeLanguages": {
+    "typescriptreact": "html"
+  },
+  "tailwindCSS.classFunctions": ["cn", "cva", "twMerge", "cx"],
+  "tailwindCSS.classAttributes": [
+    "class",
+    "className",
+    ".*ClassName",
+    ".*Styles"
+  ],
+  "tailwindCSS.experimental.classRegex": [
+    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^\"'`]*)(?:'|\"|`)"],
+    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
+  ],
+
+  // Search exclusions (performance)
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/.next": true,
+    "**/bun.lock": true,
+    "**/.vercel": true,
+    "**/lib/integrations/sanity/sanity.types.ts": true
+  },
+
+  // Language-specific formatters
+  "[css]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+
+  // General
+  "files.eol": "\n",
+  "workbench.editorAssociations": {
+    "*.svg": "default"
+  },
+  "colorize.languages": [
+    "javascript",
+    "typescript",
+    "css",
+    "scss",
+    "less",
+    "html",
+    "json",
+    "yaml",
+    "markdown",
+    "glsl"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @basementstudio/cli
+
+## 0.2.2
+
+### Patch Changes
+
+- [#14](https://github.com/basementstudio/basement-cli/pull/14) [`c3e43db`](https://github.com/basementstudio/basement-cli/commit/c3e43db93e417b46ffc6dbe9d7120a5600a1bf08) Thanks [@valebearzotti](https://github.com/valebearzotti)! - Retry npm release after fixing trusted publisher workflow configuration.
+
+## 0.2.1
+
+### Patch Changes
+
+- [#12](https://github.com/basementstudio/basement-cli/pull/12) [`9af1be7`](https://github.com/basementstudio/basement-cli/commit/9af1be7701eeea3d1843cacdce52e144954aac0d) Thanks [@valebearzotti](https://github.com/valebearzotti)! - Set up automated npm releases with Changesets and GitHub Actions.

package/CLAUDE.md

@@ -0,0 +1,138 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is **basement**, a CLI tool that scaffolds Next.js projects with AI agent integration. It creates projects from templates (Default, WebGL, WebGPU, Experiment) and optionally injects CMS integrations (Sanity, BaseHub) and animation libraries (GSAP, Framer Motion).
+
+## Commands
+
+### CLI Development
+```bash
+npm link              # Install CLI locally for testing
+basement      # Run the CLI
+```
+
+### Generated Project Commands
+Projects created by this CLI use these commands:
+```bash
+bun dev               # Start dev server with Turbopack
+bun build             # Build for production
+bun lint              # Run Biome linter
+bun lint:fix          # Auto-fix linting issues
+bun typecheck         # Type check with tsgo
+bun generate          # Scaffold components/hooks
+bun analyze           # Bundle size analysis
+```
+
+Sanity-specific (when Sanity CMS is selected):
+```bash
+bun sanity:extract    # Extract Sanity schema
+bun sanity:typegen    # Generate TS types from Sanity schema
+```
+
+## Architecture
+
+```
+basement-starter-cli/
+├── bin/index.js              # CLI entry point (basement command)
+├── src/commands/create.js    # Main project creation logic
+├── layers/                   # Technology layer overlays (applied on top of next-starter)
+│   ├── webgl/               # Three.js WebGL components (page, canvas, scene)
+│   ├── webgpu/              # WebGPU (deps-only, .gitkeep)
+│   └── experiment/          # Creative coding (header, navigation, utils)
+├── integrations/             # CMS integrations (injected on top of templates)
+│   └── sanity/              # Sanity CMS files
+├── template-hooks/           # Reusable React hooks (selected during setup)
+└── plugins/                  # Biome linting rules (Grit patterns)
+```
+
+### CLI Flow (src/commands/create.js)
+1. **Prompts**: Collect project name, template type, CMS, animation library, agent preference, hooks
+2. **Template Download**: Clone from `basementstudio/next-starter#main`
+3. **Layer Injection**: Overlay technology layer files from local `layers/{type}/` directory
+4. **Integration Injection**: Overlay CMS files from `basementstudio/basement/integrations/{cms}#sanity-integration`
+5. **Package Hydration**: Inject layer deps (from LAYER_CONFIG), CMS deps, animation deps, and scripts
+6. **Agent Skills**: Install AI agent skills via `bunx skills add`
+7. **Hooks**: Copy selected hooks from `template-hooks/`
+
+## Generated Project Stack
+
+Projects created by this CLI use:
+- **Next.js 16+** with App Router, Turbopack, Cache Components
+- **React 19+** with React Compiler (no manual useMemo/useCallback needed)
+- **TypeScript** strict mode with `noUncheckedIndexedAccess`
+- **Tailwind CSS v4** (CSS-first configuration)
+- **Biome** for linting/formatting
+- **Zustand** for state management
+- **Bun** as runtime/package manager
+
+## Key Guidelines from Cursor Rules
+
+### React Compiler
+React Compiler is enabled - do NOT use `useMemo`, `useCallback`, or `React.memo`. Exception: use `useRef` for object instantiation to prevent infinite loops.
+
+```tsx
+// ❌ DON'T
+const instance = new SomeClass()
+
+// ✅ DO
+const instanceRef = useRef<SomeClass | null>(null)
+if (!instanceRef.current) instanceRef.current = new SomeClass()
+```
+
+### React 19 Features
+- `<Activity />` - Defer off-screen component updates (tabs, carousels, WebGL scenes)
+- `useEffectEvent` - Separate event logic from effect dependencies
+- `cacheSignal()` - Auto-abort signal for server component data fetching
+- Refs as regular props (no forwardRef needed)
+
+### Image Components
+- Use `@/components/ui/image` for standard images (not `next/image` directly)
+- For WebGL: use `@/lib/webgl/components/image`
+
+### CSS Modules
+Import as `s`, use `cn` from `@/styles/cn` for className conditionals:
+```tsx
+import s from './component.module.css'
+import { cn } from '@/styles/cn'
+```
+
+### Custom PostCSS Functions
+- `tovw(pixels)` - Convert to viewport width
+- `torem(pixels)` - Convert to rem
+- `columns(n)` - Width based on grid columns
+
+### Sanity CMS
+- All files in `/lib/integrations/sanity/`
+- Use `defineType`, `defineField`, `defineArrayMember` for schemas
+- GROQ queries use `SCREAMING_SNAKE_CASE`, wrap with `defineQuery`
+- Use `sanityFetch` (includes `cacheSignal()` automatically)
+- Visual editing: add `data-sanity` attributes
+- Nested layouts (e.g. `app/studio/layout.tsx`) must NOT render `<html>` or `<body>` tags — the root layout already provides them. Just return `children`.
+- Studio route guard: site chrome (nav, skip link, footer) is wrapped in `<SanityStudioGuard>` — a `"use client"` component using `useSelectedLayoutSegment()` that returns `null` on `/studio` routes. This prevents layout duplication in the Sanity Presentation tool.
+
+### Next.js Dynamic Rendering Rules
+**NEVER call `headers()`, `cookies()`, `draftMode()`, or `searchParams` in root layouts** — these trigger "uncached data / Runtime data accessed outside `<Suspense>`" errors that block the entire page. Instead:
+- For route detection in layouts: use `useSelectedLayoutSegment()` in a `"use client"` wrapper component
+- For draft mode / visual editing: extract into an async server component wrapped in its own `<Suspense>` boundary (see `components/sanity/visual-editing.tsx`)
+- Root layouts should have ZERO dynamic function calls — encapsulate all dynamic behavior in child components with proper Suspense boundaries
+
+### Integration File Sources
+- **Technology layers** (`layers/`) are LOCAL files in this CLI repo
+- **CMS integrations** (`integrations/`) are downloaded from REMOTE GitHub branches via `tiged` — the local `integrations/` directory is only a reference copy
+- Files that need to exist in generated projects but aren't on the remote branch must be **generated inline by the merger** (e.g., `SanityStudioGuard` component is written by `layout-merger.js`)
+
+### Debug Components
+Always gate debug UI (not auto-removed in production):
+```tsx
+{process.env.NODE_ENV === 'development' && <Stats />}
+```
+
+## Biome Plugins
+
+Custom linting rules in `plugins/`:
+- `no-anchor-element.grit` - Enforce Next.js `<Link>` over `<a>`
+- `no-unnecessary-forwardref.grit` - Prevent forwardRef with React 19
+- `no-relative-parent-imports.grit` - Enforce `@/` alias imports

package/README.md

@@ -0,0 +1,176 @@
+# basement `1.0.0`
+
+Your project starts here. One command to go from zero to a fully configured Next.js project with our stack, CMS, agent skills, and everything wired up.
+
+```bash
+basement
+```
+
+## What's in 1.0
+
+### Instant project scaffolding from templates
+
+Spin up a new project based on the stack we actually use. Pick a template, answer a few prompts, and you're running.
+
+| Template | What you get |
+|----------|-------------|
+| **Default** | Next.js 16 + React 19 + Tailwind v4 + Biome + Zustand |
+| **WebGL** | + React Three Fiber + Three.js |
+| **WebGPU** | + R3F WebGPU renderer (alpha) |
+| **Experiment** | + Creative coding setup with navigation UI |
+
+Every template ships with TypeScript strict mode, React Compiler, Turbopack, PostCSS functions (`tovw`, `torem`, `columns`), component generation scripts, and the full `lib/` architecture.
+
+### Full Sanity integration — code and infrastructure
+
+Not just boilerplate files. The CLI sets up your entire Sanity stack:
+
+- Embedded Studio at `/studio` with schemas, structure builder, and live preview
+- GROQ queries with TypeScript type generation
+- Draft mode with visual editing
+- API routes for revalidation webhooks
+- `.env.local` with all credentials
+
+**Automated project creation** — The CLI creates a Sanity project on your dashboard, generates API tokens, and wires everything into your repo. If you're not logged in, it opens `sanity login` inline — you never leave the terminal.
+
+### Add Sanity to existing projects
+
+Already have a project running? The `--add` command injects Sanity into it. It detects your project structure (`app/` or `src/app/`) and smart-merges layout, sitemap, and integration files without overwriting your code.
+
+Real-world validated — this is how we integrated Sanity into the ROX project.
+
+```bash
+basement --add
+```
+
+### Agent skills out of the box
+
+Pick your agent (Claude Code or OpenCode) and the CLI installs curated skills so it understands our stack from the start:
+
+- React + Next.js performance patterns
+- Web design and accessibility guidelines
+- Frontend design standards
+- WebGPU/TSL guides (for WebGPU and Experiment templates)
+- Sanity agent toolkit (when Sanity is selected)
+
+For Claude Code + Sanity, it also registers the Sanity MCP server automatically.
+
+### Git worktrees for parallel agent work
+
+Run multiple Claude Code instances on separate branches without conflicts. The CLI manages worktree creation, switching, and cleanup.
+
+```bash
+basement -wc -b=feature/auth,feature/dashboard,fix/bug-123
+```
+
+Creates three isolated worktrees with dependencies auto-installed. Each one is a full working copy your agent can run in independently.
+
+---
+
+## (SOON) Installation
+
+```bash
+npm install -g basement
+```
+
+For local development — clone the repo and run:
+
+```bash
+npm link
+```
+
+## Usage
+
+Interactive mode — answer prompts step by step:
+
+```bash
+basement
+```
+
+Skip everything with flags:
+
+```bash
+basement --create my-app --webgpu --sanity --gsap --claude
+```
+
+Add Sanity to an existing project:
+
+```bash
+basement --add
+```
+
+Manage worktrees:
+
+```bash
+basement --worktree
+```
+
+## All Flags
+
+```
+basement [mode] [project-name] [flags]
+
+Modes:
+  -c, --create              Setup a new project
+  -a, --add                 Add integration to existing project
+  -w, --worktree            Manage git worktrees
+
+Templates:
+  -d, --default             Next.js starter
+  --webgl                   Three.js WebGL
+  --webgpu                  WebGPU graphics
+  --experiment              Creative coding
+
+CMS:
+  --sanity                  Sanity CMS
+  --basehub                 BaseHub CMS
+  --no-cms                  No CMS
+
+Animation:
+  --gsap                    GSAP
+  --motion                  Framer Motion
+  --no-animation            No animation library
+
+Agent:
+  --claude                  Claude Code
+  --opencode                OpenCode
+
+Hooks:
+  --no-hooks                Skip hook selection
+
+Worktrees:
+  -wc, --worktree-create    Create worktree(s)
+  -wl, --worktree-list      List worktrees
+  -ws, --worktree-switch    Switch to a worktree
+  -wr, --worktree-remove    Remove a worktree
+  -wp, --worktree-prune     Clean up stale references
+  -b=<branch>               Branch name (comma-separated for multiple)
+  -db                       Delete branch on remove
+  -f                        Skip confirmations
+
+Other:
+  -h, --help                Show help
+```
+
+## Generated Project Commands
+
+```bash
+bun dev               # Dev server with Turbopack
+bun build             # Production build
+bun lint              # Biome linter
+bun lint:fix          # Auto-fix lint issues
+bun typecheck         # Type check with tsgo
+bun generate          # Scaffold components/hooks
+bun analyze           # Bundle size analysis
+```
+
+With Sanity:
+
+```bash
+bun sanity:extract    # Extract Sanity schema
+bun sanity:typegen    # Generate TS types from schema
+```
+
+## License
+
+ISC