bsmnt 0.2.8 → 0.2.10

package/README.md

@@ -1,137 +1,65 @@
-# bsmnt `0.2.8`
+# bsmnt
 
-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.
+<a href="https://basement.studio"><img alt="basement.studio logo" src="https://img.shields.io/badge/MADE%20BY%20basement.studio-000000.svg?style=for-the-badge&labelColor=000"></a>
+<a href="https://www.npmjs.com/package/bsmnt"><img alt="NPM version" src="https://img.shields.io/npm/v/bsmnt.svg?style=for-the-badge&labelColor=000000"></a>
+<a href="https://github.com/basementstudio/basement-cli"><img alt="License" src="https://img.shields.io/npm/l/bsmnt.svg?style=for-the-badge&labelColor=000000"></a>
 
-```bash
-bsmnt
-```
-
-## 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 + optional WebGPU renderer toggle |
-| **Experiment** | + Creative coding setup with navigation UI |
+`bsmnt` is a CLI for scaffolding basement projects, adding integrations, and installing optional hooks and agent setup.
 
-Every template ships with TypeScript strict mode, React Compiler, Turbopack, PostCSS functions (`tovw`, `torem`, `columns`), component generation scripts, and the full `lib/` architecture.
+## Overview
 
-### Full Sanity integration — code and infrastructure
+- Scaffold new projects from basement starter templates
+- Add Sanity to an existing project
+- Copy optional hooks into an existing codebase
+- Set up supported agent tooling
 
-Not just boilerplate files. The CLI sets up your entire Sanity stack:
+## Templates
 
-- 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
+| Template | Includes |
+| --- | --- |
+| Default | Next.js, React, TypeScript, Tailwind, Biome, and Zustand |
+| WebGPU | Default stack plus React Three Fiber, Three.js, and 3D/WebGPU-ready setup |
+| Experiment | Default stack plus creative coding utilities and navigation UI |
 
-**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.
+## Install
 
-### Add Sanity to existing projects
-
-Already have a project running? The `integrate` 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.
+Run without installing:
 
 ```bash
-bsmnt integrate --sanity
-```
-
-### 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 WebGL and Experiment templates)
-- Sanity agent toolkit (when Sanity is selected)
-
-For Claude Code + Sanity, it also registers the Sanity MCP server automatically.
-
-## Project Structure
-
-Single TypeScript package published as `bsmnt` on npm:
-
-```
-src/
-├── index.ts                     # Commander program, prompts, routing
-├── paths.ts                     # Centralized path resolution
-├── configs/animations.ts        # GSAP / Motion dependency configs
-├── helpers/
-│   ├── create/                  # Project creation pipeline
-│   ├── integrate/               # CMS integration injection
-│   │   └── sanity/              # Sanity files, config, mergers
-│   └── add/                     # Hook injection
-└── utils/                       # detect-project, format-results
-templates/                       # Standalone project templates
-template-hooks/                  # Reusable React hooks
-plugins/                         # Biome linting rules (Grit patterns)
+npx bsmnt
+bunx bsmnt
 ```
 
-## (SOON) Installation
+Install globally:
 
 ```bash
 npm install -g bsmnt
 ```
 
-For local development -- clone the repo and run:
-
-```bash
-bun install
-npm link .
-```
-
-## Release Channels
-
-This repo follows a two-channel release model similar to the Next.js stable/canary approach, while keeping Changesets as the version source of truth.
-
-- `latest` (stable): production releases from the Changesets release PR flow.
-- `canary`: snapshot prereleases from `main` under npm dist-tag `canary` triggered manually.
-
-Install stable:
-
-```bash
-npm install -g bsmnt@latest
-```
+## Usage
 
-Install canary:
+Create a new project:
 
 ```bash
-npm install -g bsmnt@canary
+bsmnt
+npx bsmnt
+bunx bsmnt
 ```
 
-Verify dist-tags:
+Add Sanity to an existing project:
 
 ```bash
-npm view bsmnt dist-tags
+bsmnt integrate --sanity
+npx bsmnt integrate --sanity
+bunx bsmnt integrate --sanity
 ```
 
-How to trigger stable releases:
-
-1. Add a changeset in your feature PR (`bun run changeset`).
-2. Merge PR(s) into `main`.
-3. GitHub Actions updates/opens the release PR with version/changelog changes.
-4. Merge that release PR to publish to npm `latest`.
-
-How to trigger canary releases:
-
-1. Add a changeset in your feature PR (`bun run changeset`).
-2. Merge the PR into `main`.
-3. In GitHub Actions, run `Canary Release` with `workflow_dispatch` on the `main` branch.
-4. The workflow publishes snapshot builds to npm tag `canary` when pending changesets exist.
-
-## Usage
-
-Interactive mode — answer prompts step by step:
+Add hooks to an existing project:
 
 ```bash
-bsmnt
+bsmnt add
+npx bsmnt add
+bunx bsmnt add
 ```
 
 Skip prompts with flags:
@@ -140,64 +68,74 @@ Skip prompts with flags:
 bsmnt create my-app --webgpu --sanity --gsap --claude --no-hooks
 ```
 
-Add Sanity to an existing project:
+## Command Summary
 
 ```bash
+bsmnt
+bsmnt create [project-name]
 bsmnt integrate --sanity
+bsmnt add
+bsmnt --help
 ```
 
-## All Flags
+## Options
 
-```
-bsmnt [command]
+### Global
 
-Commands:
-  create|c [project-name]   Create a new project
-  integrate|i               Add CMS integration to existing project
-  add|a                     Add hooks to an existing project
+| Option | Description |
+| --- | --- |
+| `-h, --help` | Show help |
+| `-V, --version` | Show the CLI version |
 
-Templates:
-  -d, --default             Next.js starter
-  --webgpu                  Three.js/WebGPU starter
-  --experiment              Creative coding
+### `create`
 
-CMS:
-  --sanity                  Sanity CMS
-  --no-cms                  No CMS
+| Option | Description |
+| --- | --- |
+| `-d, --default` | Use the default template |
+| `--webgpu` | Use the WebGPU template |
+| `--webgl` | Deprecated alias for `--webgpu` |
+| `--experiment` | Use the experiment template |
+| `--sanity` | Add Sanity |
+| `--no-cms` | Skip CMS setup |
+| `--gsap` | Use GSAP |
+| `--motion` | Use Motion |
+| `--no-animation` | Skip animation setup |
+| `--claude` | Set up Claude Code |
+| `--opencode` | Set up OpenCode |
+| `--cursor` | Set up Cursor |
+| `--codex` | Set up Codex |
+| `--gemini` | Set up Gemini CLI |
+| `--no-agent` | Skip agent setup |
+| `--no-hooks` | Skip hook selection |
 
-Animation:
-  --gsap                    GSAP
-  --motion                  Framer Motion
-  --no-animation            No animation library
+### `integrate`
 
-Agent:
-  --claude                  Claude Code
-  --opencode                OpenCode
+| Option | Description |
+| --- | --- |
+| `--sanity` | Add Sanity to the current project |
 
-Hooks:
-  --no-hooks                Skip hook selection
+### `add`
 
-Other:
-  -h, --help                Show help
-```
+No command-specific flags currently.
 
-## Generated Project Commands
+## Templates
 
-```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
-```
+- Default
+- WebGPU
+- Experiment
+
+## Included Features
 
-With Sanity:
+- Starter templates
+- Optional Sanity integration
+- Optional hooks
+- Optional agent setup
+
+## Local Development
 
 ```bash
-bun sanity:extract    # Extract Sanity schema
-bun sanity:typegen    # Generate TS types from schema
+bun install
+npm link .
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bsmnt",
-	"version": "0.2.8",
+	"version": "0.2.10",
 	"packageManager": "bun@1.2.20",
 	"description": "CLI to scaffold basement projects and add integrations",
 	"type": "module",
@@ -30,7 +30,7 @@
 		"lint": "biome check .",
 		"lint:fix": "biome check --write .",
 		"changeset": "changeset",
-		"version-packages": "changeset version && node scripts/sync-readme-version.js",
+		"version-packages": "changeset version",
 		"release": "changeset publish",
 		"prepublishOnly": "rm -rf dist && bun run build",
 		"default": "turbo run dev --filter=bsmnt-next-starter",

package/src/helpers/integrate/sanity/files/lib/utils/metadata.ts

@@ -56,7 +56,7 @@ export function generatePageMetadata(
 		keywords,
 		image,
 		url,
-		siteName = "Satūs",
+		siteName = "Basement",
 		noIndex = false,
 		type = "website",
 		publishedTime,

package/src/templates/next-default/README.md

@@ -1,221 +1,50 @@
 # Basement Next Starter
 
-A production-ready Next.js starter with React 19, Tailwind CSS v4, TypeScript strict mode, and everything you need to build modern web applications.
-
-## Tech Stack
-
-| Technology | Version | Description |
-|------------|---------|-------------|
-| Next.js | 16.1 | App Router, Turbopack |
-| React | 19 | React Compiler enabled |
-| TypeScript | 5.9 | Strict mode, `noUncheckedIndexedAccess` |
-| Tailwind CSS | 4 | CSS-first configuration |
-| Biome | 2.3 | Linting and formatting |
-| Bun | 1.3 | Package manager and runtime |
-| Zustand | 5.0 | State management |
+Minimal Next.js starter with Tailwind CSS, TypeScript, and Basement defaults.
 
 ## Quick Start
 
 ```bash
-# Clone the template
-bunx degit basementstudio/next-starter my-project
-
-# Install dependencies
-cd my-project && bun install
-
-# Start development
+bun install
 bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) to see the result.
-
 ## Scripts
 
 | Command | Description |
 |---------|-------------|
-| `bun dev` | Start development server with Turbopack |
-| `bun dev:https` | Start with HTTPS (for secure contexts) |
+| `bun dev` | Start the development server |
+| `bun dev:https` | Start the development server with HTTPS |
 | `bun build` | Build for production |
-| `bun start` | Start production server |
-| `bun generate` | Scaffold new components/hooks |
-| `bun lint` | Run Biome linter |
-| `bun lint:fix` | Fix lint issues |
-| `bun format` | Format code with Biome |
-| `bun typecheck` | Type check with tsgo |
-| `bun test` | Run tests with Bun |
-| `bun analyze` | Analyze bundle size |
+| `bun start` | Start the production server |
+| `bun lint` | Run Biome |
+| `bun lint:fix` | Run Biome with fixes |
+| `bun format` | Format the codebase |
+| `bun typecheck` | Run TypeScript |
+| `bun analyze` | Analyze the Next.js bundle |
 
 ## Project Structure
 
-```
-app/                     # Next.js App Router pages and routes
-  ├── api/               # API routes (draft-mode, revalidate)
-  ├── layout.tsx         # Root layout with metadata, fonts
-  ├── page.tsx           # Homepage
-  ├── sitemap.ts         # Dynamic sitemap generation
-  └── robots.ts          # SEO robots.txt
-
+```txt
+app/
 components/
-  ├── layout/
-  │   ├── header/        # Navigation header
-  │   ├── footer/        # Page footer
-  │   ├── wrapper/       # Page wrapper with theme
-  │   └── theme/         # Theme context provider
-  └── ui/
-      ├── image/         # Enhanced Next.js Image wrapper
-      └── link/          # Smart Link component
-
 lib/
-  ├── hooks/                      # Custom React hooks
-  │   ├── use-device-detection/   # Device/capability detection
-  │   ├── use-media-breakpoint/   # Responsive breakpoint hook
-  │   └── use-prefetch/           # Prefetch utilities
-  ├── integrations/               # Third-party integrations
-  ├── scripts/                    # Build and dev scripts
-  ├── store/                      # Zustand global state
-  ├── styles/                     # Design tokens, CSS config
-  │   ├── colors.ts               # Theme colors
-  │   ├── layout.mjs              # Breakpoints, grid, spacing
-  │   ├── easings.ts              # CSS easing variables
-  │   └── fonts.ts                # Font loading (Geist Mono)
-  └── utils/                      # Utility functions
-      ├── easings.ts              # 30+ animation easing functions
-      ├── math.ts                 # Math utilities
-      ├── strings.ts              # String utilities
-      └── fetch.ts                # Fetch utilities
-```
-
-## Features
-
-### Design System
-
-Pre-configured design tokens ready to use:
-
-**Breakpoints:**
-- `mobile`: 375px
-- `tablet`: 620px
-- `tablet-lg`: 1024px
-- `desktop`: 1440px
-- `desktop-large`: 1920px
-
-**Grid:**
-- Mobile: 4 columns
-- Desktop: 12 columns
-- Gap: 16px
-
-**Colors:**
-- Theme colors: `primary`, `secondary`, `contrast`
-- Accent colors: `red`, `blue`, `green`, `violet`, `pink`
-- Light/dark mode support
-
-**Easings:**
-30+ easing functions (quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce)
-
-### Smart Components
-
-**`<Image>`** - Enhanced Next.js Image wrapper:
-- Automatic responsive sizes based on breakpoints
-- Blur placeholder with shimmer effect
-- Preload support for LCP images
-- SVG handling
-
-**`<Link>`** - Intelligent link component:
-- Auto-detects external links (opens in new tab)
-- Connection-aware prefetching (4G only, respects data saver)
-- Falls back to button/div when no href
-- Active state detection
-
-**`<Wrapper>`** - Page layout component:
-- Includes Header and Footer
-- Theme provider integration
-- Flexible content area
-
-### Theme Support
-
-Light/dark theme with CSS custom properties:
-
-```tsx
-import { Wrapper } from "@/components/layout/wrapper"
-
-export default function Page() {
-  return (
-    <Wrapper theme="dark">
-      <section>Your content</section>
-    </Wrapper>
-  )
-}
+  hooks/
+  integrations/
+  scripts/
+  store/
+  styles/
+    index.css
+    tokens.css
+    global.css
+    fonts.ts
+    cn.ts
+  utils/
 ```
 
-Access theme in components:
-
-```tsx
-import { useTheme } from "@/components/layout/theme"
-
-function Component() {
-  const { name, setThemeName } = useTheme()
-  // ...
-}
-```
-
-### Performance Optimizations
-
-- **React Compiler** - Automatic memoization (no manual `useMemo`/`useCallback`)
-- **Turbopack** - Fast development builds
-- **Bundle Analyzer** - `bun analyze` to inspect bundle size
-- **Optimized Imports** - Auto-optimization for GSAP, Three.js, Lenis, Zustand
-- **Security Headers** - CSP, HSTS, XSS protection pre-configured
-- **Image Optimization** - AVIF, WebP with custom quality settings
-
-### Developer Experience
-
-- **Component Scaffolding** - `bun generate` to create components/hooks
-- **HTTPS Dev Server** - `bun dev:https` for secure contexts
-- **Strict TypeScript** - `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
-- **Biome** - Fast linting and formatting with custom rules
-- **Tests** - Bun test runner with utilities
-
-## Configuration
-
-### Styles
-
-Edit design tokens in `lib/styles/`:
-
-- `colors.ts` - Theme and accent colors
-- `layout.mjs` - Breakpoints, grid, spacing
-- `typography.ts` - Font definitions
-- `easings.ts` - CSS easing variables
-
-After editing, regenerate CSS:
-
-```bash
-bun setup:styles
-```
-
-### Next.js
-
-Configuration in `next.config.ts`:
-
-- React Compiler enabled
-- Typed routes
-- SVG loader (@svgr/webpack)
-- Security headers
-- Image optimization settings
-
-## Deployment
-
-### Vercel (Recommended)
-
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/basementstudio/next-starter)
-
-### Other Platforms
-
-```bash
-bun build
-bun start
-```
-
-The app runs on port 3000 by default.
-
-## License
+## Styling
 
-MIT
+- Import `@/lib/styles/index.css` once in `app/layout.tsx`.
+- Edit `lib/styles/tokens.css` for theme variables, breakpoints, and custom Tailwind utilities.
+- Edit `lib/styles/global.css` for reset rules and app-wide global styles.
+- `lib/styles/fonts.ts` handles font variables.

package/src/templates/next-default/app/layout.tsx

@@ -2,10 +2,9 @@ import type { Metadata, Viewport } from "next";
 import { Geist } from "next/font/google";
 import { type PropsWithChildren, Suspense } from "react";
 import { Link } from "@/components/ui/link";
-import { themes } from "@/lib/styles/colors";
 import { fontsVariable } from "@/lib/styles/fonts";
 import AppData from "@/package.json";
-import "@/lib/styles/css/index.css";
+import "@/lib/styles/index.css";
 import { cn } from "@/lib/styles/cn";
 
 const APP_NAME = AppData.name;
@@ -74,7 +73,7 @@ export const metadata: Metadata = {
 
 export const viewport: Viewport = {
   colorScheme: "normal",
-  themeColor: themes.dark.primary,
+  themeColor: "#000000",
 };
 
 export default async function Layout({ children }: PropsWithChildren) {

package/src/templates/next-default/biome.json

@@ -214,20 +214,7 @@
       }
     },
     {
-      "includes": ["**/*.module.css"],
-      "linter": {
-        "rules": {
-          "correctness": {
-            "noUnknownProperty": "off"
-          },
-          "style": {
-            "noDescendingSpecificity": "off"
-          }
-        }
-      }
-    },
-    {
-      "includes": ["lib/styles/css/root.css"],
+      "includes": ["lib/styles/tokens.css"],
       "linter": {
         "rules": {
           "suspicious": {

package/src/templates/next-default/components/layout/theme/index.tsx

@@ -2,16 +2,14 @@
 
 import { usePathname } from "next/navigation"
 import { createContext, useContext, useEffect, useState } from "react"
-import type { Themes } from "@/lib/styles/colors"
-import { type ThemeName, themes } from "@/lib/styles/config"
+
+export type ThemeName = "light" | "dark"
 
 export const ThemeContext = createContext<{
   name: ThemeName
-  theme: Themes[ThemeName]
   setThemeName: (theme: ThemeName) => void
 }>({
   name: "light",
-  theme: themes.light,
   setThemeName: () => {
     void 0
   },
@@ -55,7 +53,6 @@ export function Theme({
       <ThemeContext.Provider
         value={{
           name: currentTheme,
-          theme: themes[currentTheme],
           setThemeName: setCurrentTheme,
         }}
       >

package/src/templates/next-default/components/layout/wrapper/index.tsx

@@ -6,8 +6,7 @@
 import cn from "clsx"
 import { Footer } from "@/components/layout/footer"
 import { Header } from "@/components/layout/header"
-import { Theme } from "@/components/layout/theme"
-import type { ThemeName } from "@/lib/styles/config"
+import { Theme, type ThemeName } from "@/components/layout/theme"
 
 /**
  * Props for the Wrapper component.

package/src/templates/next-default/components/ui/README.md

@@ -65,9 +65,8 @@ import { Link } from '@/components/ui/link'
 <Link href="/about">Internal</Link>
 <Link href="https://example.com">External</Link>
 
-// ✅ CSS Modules + Tailwind
-import s from './component.module.css'
-<div className={cn(s.wrapper, 'flex items-center')} />
+// ✅ Tailwind only
+<div className="flex items-center" />
 ```
 
 ## Related

package/src/templates/next-default/components/ui/image/index.tsx

@@ -9,7 +9,8 @@
 import cn from "clsx"
 import NextImage, { type ImageProps as NextImageProps } from "next/image"
 import type { CSSProperties, Ref } from "react"
-import { breakpoints } from "@/lib/styles/config"
+
+const DESKTOP_BREAKPOINT = 1440
 
 /**
  * Enhanced Image component props extending Next.js Image.
@@ -166,8 +167,7 @@ export function Image({
 }: ImageProps) {
   // Generate responsive sizes if not provided
   const finalSizes =
-    sizes ||
-    `(max-width: ${breakpoints.desktop}px) ${mobileSize}, ${desktopSize}`
+    sizes || `(max-width: ${DESKTOP_BREAKPOINT}px) ${mobileSize}, ${desktopSize}`
 
   // Early return after hooks
   if (!src) return null