beaver-build 1.0.7 → 1.0.8

package/README.md

@@ -4,11 +4,13 @@
 
 An interactive CLI tool for scaffolding modern web projects. Select your project type, configure your stack through a guided menu, and get a production-ready project generated on disk with pinned library versions.
 
+**Current Version:** 1.0.7
+
 ## Getting Started
 
 ### Prerequisites
 
-- Node.js 18+
+- Node.js >= 20.0.0
 - npm
 
 ### Installation
@@ -23,7 +25,23 @@ beaver
 **Option 2: Use directly with npx** (no installation needed)
 
 ```bash
-npx beaver
+npx beaver-build
+```
+
+### Commands & Options
+
+**Main command:**
+
+```bash
+beaver                          # Interactive project scaffolding
+```
+
+**Options:**
+
+```bash
+beaver -v, --version            # Show current version
+beaver -h, --help               # Show help and available commands
+beaver update                   # Update beaver to the latest version from npm
 ```
 
 ### Usage
@@ -36,9 +54,9 @@ beaver
 
 The CLI will guide you through:
 
-1. **Project Type** — Choose React + Vite or Chrome Extension
+1. **Project Type** — Choose React + Vite, Chrome Extension, or Next.js (upcoming)
 2. **Project Name** — Enter your project directory name
-3. **Configuration** — Select your preferred stack (layout, router, state management, styling, linter)
+3. **Configuration** — Select your preferred stack (layout, router, state management, styling, linter, AI setup, testing)
 
 After answering all prompts, your production-ready project will be generated in the specified directory with:
 
@@ -54,20 +72,36 @@ To contribute or develop locally:
 
 ```bash
 npm install
-npm run dev           # Run CLI in development mode
-npm run build         # Compile for distribution
+
+# Development & Building
+npm run dev           # Run CLI directly in development mode (using tsx)
+npm run dev:build     # Compile TypeScript, resolve aliases, then run
+npm run build         # Compile TypeScript for distribution (outputs to dist/)
+
+# Documentation
+npm run docs:index    # Regenerate docs/INDEX.md
+npm run docs:lint     # Validate frontmatter in docs/
+```
+
+**Publishing:**
+
+When ready to publish a new version:
+
+```bash
+npm version patch|minor|major    # Update version in package.json
+npm publish                      # Publishes to npm (runs build automatically)
 ```
 
 ---
 
 ## Project Types
 
-| Type | Status |
-|---|---|
-| React + Vite | Available |
-| Chrome Extension | Available |
-| Next.js | Upcoming |
-| Nuxt | Upcoming |
+| Type | Description | Status |
+|---|---|---|
+| React + Vite | React 19 + Vite with comprehensive tooling options | ✅ Available |
+| Chrome Extension | React 19 + Vite for Chrome Manifest v3 extensions | ✅ Available |
+| Next.js | Next 15 with app router and modern features | 🔄 Upcoming |
+| Nuxt | Nuxt 4 with Vue 3 composition API | 🔄 Upcoming |
 
 ---
 
@@ -83,8 +117,8 @@ Validated to allow only letters, numbers, hyphens, and underscores (`[a-zA-Z0-9_
 
 | Option | Description |
 |---|---|
-| FSD | Feature Slice Design |
-| BPR | Bulletproof React |
+| FSD | Feature Slice Design — modular file structure |
+| BPR | Bulletproof React — scalable architecture |
 
 ### 3. Router
 
@@ -114,7 +148,67 @@ Validated to allow only letters, numbers, hyphens, and underscores (`[a-zA-Z0-9_
 | Not Using | — |
 | Tailwind CSS | v4.1.3 |
 
-### 7. Linter / Formatter
+### 7. AI Setup
+
+| Option | Description |
+|---|---|
+| Not Using | — |
+| Claude (Claude Code) | CLAUDE.md + .claude/ agents + feature docs |
+
+### 8. Testing
+
+| Option | Description |
+|---|---|
+| Not Using | — |
+| Setup Testing Base | Vitest + React Testing Library configuration |
+
+### 9. Linter / Formatter
+
+| Option | Version | Notes |
+|---|---|---|
+| Not Using | — | — |
+| Biome | v1.9.4 | All-in-one lint + format |
+| ESLint | v9.39.4 | Flat config + typescript-eslint |
+
+---
+
+## Chrome Extension
+
+Build Chrome Manifest v3 extensions with React 19 and Vite. The CLI guides you through:
+
+### 1. Project Name
+
+Validated to allow only letters, numbers, hyphens, and underscores (`[a-zA-Z0-9_-]`).
+
+### 2. State Management
+
+| Option | Version |
+|---|---|
+| Not Using | — |
+| Zustand | v5.0.5 |
+
+### 3. Data Fetching
+
+| Option | Version |
+|---|---|
+| Not Using | — |
+| TanStack Query | v5.74.4 |
+
+### 4. CSS / Styling
+
+| Option | Version |
+|---|---|
+| Not Using | — |
+| Tailwind CSS | v4.1.3 |
+
+### 5. AI Setup
+
+| Option | Description |
+|---|---|
+| Not Using | — |
+| Claude (Claude Code) | CLAUDE.md + .claude/ agents + feature docs |
+
+### 6. Linter / Formatter
 
 | Option | Version | Notes |
 |---|---|---|
@@ -170,6 +264,9 @@ The format follows GitHub's [path-specific custom instructions](https://docs.git
 | eslint-plugin-react-hooks | 5.2.0 |
 | eslint-plugin-react-refresh | 0.4.19 |
 | globals | 15.15.0 |
+| vitest | Latest (when testing enabled) |
+| @testing-library/react | Latest (when testing enabled) |
+| @testing-library/jest-dom | Latest (when testing enabled) |
 
 ---
 
@@ -177,61 +274,110 @@ The format follows GitHub's [path-specific custom instructions](https://docs.git
 
 ```
 src/
-  index.ts                        Entry point — greeting, menu, error handling
-  types/index.ts                  Cart, ProjectType, ReactViteCore, NextJSCore
-  constants/index.ts              Top-level menu options
+  index.ts                          Entry point — greeting, menu, error handling
+  types/index.ts                    Cart, ProjectType, ReactViteCore, ChromeExtensionCore, NextJSCore
+  constants/index.ts                Top-level menu options (React+Vite, Chrome Extension, Next.js, Nuxt)
+  commands/
+    update.ts                       runUpdate() — check and install latest version from npm
   options/
-    index.ts                      Top-level project type selection
+    index.ts                        Top-level project type selection
     react-vite/
-      index.ts                    React + Vite menu flow
-      constants/index.ts          Menu option definitions
-      types/index.ts              MenuOptions type
+      index.ts                      React + Vite menu flow
+      constants/index.ts            Menu option definitions (layout, router, state, query, CSS, AI, testing, linter)
+      types/index.ts                MenuOptions type
+    chrome-extension/
+      index.ts                      Chrome Extension menu flow
+      constants/index.ts            Menu option definitions (state, query, CSS, AI, linter)
   scaffold/
-    errors.ts                     ScaffoldError, isNodeError
-    utils.ts                      FileMap, dirExists(), writeProjectFile()
+    errors.ts                       ScaffoldError, isNodeError
+    utils.ts                        FileMap, dirExists(), writeProjectFile()
+    shared/
+      claude-setup.ts               Shared Claude Code setup templates
     react-vite/
-      index.ts                    Scaffold orchestrator
+      index.ts                      Scaffold orchestrator
       templates/
-        package-json.ts           packageJsonTemplate(cart)
-        vite-config.ts            viteConfigTemplate(cart)
-        tsconfig.ts               tsconfigTemplate(), tsconfigNodeTemplate()
-        index-html.ts             indexHtmlTemplate(projectName)
-        main-tsx.ts               mainTsxTemplate(layout)
-        app-tsx.ts                appTsxFsdTemplate(), appTsxBprTemplate()
-        router.ts                 rootRouteTemplate(), indexRouteTemplate()
-        zustand.ts                zustandStoreTemplate()
-        query.ts                  queryProviderBprTemplate()
-        linter.ts                 biomeConfigTemplate(), eslintConfigTemplate()
-        gitignore.ts              gitignoreTemplate()
-        copilot-instructions.ts   getCopilotInstructionFiles(cart) — Copilot instruction set
-        fsd-layout.ts             getFsdFileMap(cart)
-        bpr-layout.ts             getBprFileMap(cart)
+        package-json.ts             packageJsonTemplate(cart)
+        vite-config.ts              viteConfigTemplate(cart)
+        tsconfig.ts                 tsconfigTemplate(), tsconfigNodeTemplate()
+        index-html.ts               indexHtmlTemplate(projectName)
+        main-tsx.ts                 mainTsxTemplate(layout)
+        app-tsx.ts                  appTsxFsdTemplate(), appTsxBprTemplate()
+        router.ts                   rootRouteTemplate(), indexRouteTemplate()
+        zustand.ts                  zustandStoreTemplate()
+        query.ts                    queryProviderBprTemplate()
+        linter.ts                   biomeConfigTemplate(), eslintConfigTemplate()
+        testing-setup.ts            vitestConfigTemplate(), testingSetupTemplate()
+        styles.ts                   stylesCssTemplate()
+        gitignore.ts                gitignoreTemplate()
+        claude-setup.ts             claudeSetupTemplate()
+        home-page.ts                homePageTemplate()
+        vite-env-d-ts.ts            viteEnvDtsTemplate()
+        copilot-instructions.ts     getCopilotInstructionFiles(cart)
+        fsd-layout.ts               getFsdFileMap(cart)
+        bpr-layout.ts               getBprFileMap(cart)
+    chrome-extension/
+      index.ts                      Scaffold orchestrator for Chrome extensions
+      templates/
+        package-json.ts             packageJsonTemplate(cart)
+        vite-config.ts              viteConfigTemplate(cart)
+        manifest-json.ts            manifestJsonTemplate(cart)
+        tsconfig.ts                 tsconfigTemplate()
+        main-tsx.ts                 mainTsxTemplate()
+        app-tsx.ts                  appTsxTemplate()
+        layout.ts                   layoutTemplate()
+        linter.ts                   biomeConfigTemplate(), eslintConfigTemplate()
+        query.ts                    queryProviderTemplate()
+        gitignore.ts                gitignoreTemplate()
+        claude-setup.ts             claudeSetupTemplate()
+        build-extension-script.ts   buildExtensionScriptTemplate()
   utils/
-    animation.ts                  typeWriter effect
-    user.ts                       getUserName() from git config
-    index.ts                      sleep()
+    animation.ts                    typeWriter effect
+    user.ts                         getUserName() from git config
+    check-node-version.ts           checkNodeVersion() — verify Node.js >= 20.0.0
+    index.ts                        sleep()
 ```
 
 ---
 
 ## Adding a New Project Type
 
+To enable a new project type (e.g., enable Next.js):
+
 1. Set `disabled: false` in `src/constants/index.ts`
-2. Create `src/options/<project-name>/` with constants, types, and flow functions
-3. Handle the new type in `src/options/index.ts`
-4. Add the interface to `src/types/index.ts` and include it in the `Cart` union
-5. Create `src/scaffold/<project-name>/` with templates and an orchestrator
+2. Create `src/options/<project-name>/` directory with:
+   - `index.ts` — menu flow function (e.g. `flowNextJS()`)
+   - `constants/index.ts` — menu option definitions
+3. Handle the new type in `src/options/index.ts` — import and call the flow function
+4. Add the interface to `src/types/index.ts` and include it in the `Cart` union (e.g. `NextJSCore`)
+5. Create `src/scaffold/<project-name>/` with:
+   - `index.ts` — scaffold orchestrator (spinner, file writing, cleanup on error)
+   - `templates/` — all template functions (package.json, config files, source templates)
+6. Register Copilot instruction templates if AI setup is available
 
 ## Adding a New Option to React + Vite
 
+To add a new menu option (e.g., a new UI library):
+
 1. Add the constant to `src/options/react-vite/constants/index.ts`
+   - Define `REACT_MENU_<OPTION_NAME>` with display, value, description, disabled fields
 2. Export the value type from `src/types/index.ts` and add the field to `ReactViteCore`
-3. Add a `menu<OptionName>` function in `src/options/react-vite/index.ts`
-4. Call it in `flowReactVite`
-5. Update `getFsdFileMap` and `getBprFileMap` to handle the new option
+3. Add a `menu<OptionName>` function in `src/options/react-vite/index.ts` using `selectFromMenu`
+4. Call it in `flowReactVite` in the right order (before scaffold step)
+5. Update `getFsdFileMap` and `getBprFileMap` in `src/scaffold/react-vite/templates/` to handle the new option
 6. **Add a Copilot instruction template** in `src/scaffold/react-vite/templates/copilot-instructions.ts`:
-   - Write a new template function (e.g. `newOptionTemplate(cart)`) returning a markdown string that starts with an `applyTo` frontmatter block scoped to the right paths for both FSD and BPR (use `FSD_PATHS` / `BPR_PATHS`)
+   - Write a new template function (e.g. `uiLibraryTemplate(cart)`) returning markdown with `applyTo` frontmatter scoped to both FSD and BPR paths
    - Register it inside `getCopilotInstructionFiles` under a conditional block keyed by the new cart field
-   - If the new option introduces a new kind of file path, extend the `Paths` type and both `FSD_PATHS` / `BPR_PATHS` maps so every path-specific rule stays layout-aware
+   - If the new option introduces new file paths, extend `Paths` type and both `FSD_PATHS` / `BPR_PATHS` maps
+
+   **This step is mandatory** — every scaffolded project with the new option must receive its matching Copilot instruction file.
+
+## Adding a New Option to Chrome Extension
+
+Same process as React + Vite:
 
-   This step is mandatory — any user who scaffolds a project with the new option must get a matching Copilot instruction file automatically.
+1. Add the constant to `src/options/chrome-extension/constants/index.ts`
+2. Export the value type from `src/types/index.ts` and add the field to `ChromeExtensionCore`
+3. Add a `menu<OptionName>` function in `src/options/chrome-extension/index.ts`
+4. Call it in `flowChromeExtension`
+5. Update templates in `src/scaffold/chrome-extension/templates/` to handle the new option
+6. Add a Copilot instruction template if applicable (Chrome extensions also use AI setup)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beaver-build",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Interactive CLI tool for scaffolding modern web projects with production-ready configurations",
   "main": "dist/index.js",
   "type": "module",