vibe-now 1.0.0

package/PLAN.md

@@ -0,0 +1,54 @@
+# Custom CLI Wizard Plan (Plop.js + Next.js Stack)
+
+This project has been successfully implemented and released as **Vibe Now**.
+
+## 1. Project Overview
+A custom CLI (`vibe-now`) that:
+- Prompts for project name with validation.
+- Dynamically generates interactive prompts group by category.
+- Orchestrates project creation and dependency installation using a configuration-driven approach.
+- Generates dynamic documentation (AGENTS.md and README.md).
+
+## 2. Core Dependencies
+- **plop**: Generator framework.
+- **inquirer**: Interactive prompts.
+- **execa**: Process execution.
+- **ora**: Premium progress spinners.
+- **handlebars**: Template engine for file generation.
+
+## 3. Configuration-Driven Architecture (DRY & Scalable)
+The CLI uses a `PACKAGE_GROUPS` array in `lib/packages.js`. Adding a new package or category is fully decoupled from the core logic.
+
+## 4. Implementation Details & Commands
+
+### Base Next.js Setup
+- **Command**: `npx create-next-app@latest`
+
+### Features Implemented
+- **AI SDK**: Vercel AI SDK & OpenRouter.
+- **Linters**: ESLint/Prettier and Biome selection.
+- **UI & Helpers**: shadcn/ui, nuqs, hook-form, dayjs, lodash.
+- **Database**: Supabase & Drizzle ORM.
+- **Payments**: Stripe & Polar.sh.
+- **Authentication**: Better Auth.
+
+## 5. Implementation Status
+
+- [x] **Phase 1: Environment Setup** - Completed with ESM support and binary linking.
+- [x] **Phase 2: Configuration Hub** - Scalable group-based configuration implemented.
+- [x] **Phase 3: CLI Entry Point** - `index.js` and `plopfile.js` logic finalized.
+- [x] **Phase 4: Premium UI** - **Ora** spinners integrated for all major steps.
+- [x] **Phase 5: Smart Validation** - URL-safe project names and empty directory checks.
+- [x] **Phase 6: Dynamic Documentation** - Handlebars-based `README.md` and `AGENTS.md` generation.
+
+## 6. Project Structure
+```text
+vibe-cli/
+├── lib/
+│   └── packages.js     # Centralized configuration
+├── templates/          # HBS templates (README, AGENTS)
+├── index.js            # CLI Entry point 
+├── plopfile.js         # Plop logic & Action orchestrator
+├── package.json
+└── README.md
+```

package/README.md

@@ -0,0 +1,94 @@
+# Vibe Now 🌌
+
+A premium, interactive CLI wizard for scaffolding modern Next.js applications with a perfectly curated stack. Stop running manual `npm install` commands and start building within seconds.
+
+## ✨ Features
+
+- **Interactive Wizard**: A beautiful CLI experience powered by Plop.js and Inquirer.
+- **World-Class Feedback**: Engaged progress tracking with **Ora** spinners for a premium feel.
+- **Smart Scaffolding**: Automatically orchestrates `create-next-app` and library-specific initializations (like `shadcn init` and `biome init`).
+- **Dynamic Documentation**: Automatically generates a project-specific `README.md` and a comprehensive `AGENTS.md` to guide AI assistants (Cursor, Claude) on your stack and standards.
+- **Template System**: Powered by Handlebars templates in the `templates/` directory for highly customized project initialization.
+- **Safety First**: Project name validation and directory check to prevent accidental overwrites.
+
+## 🛠️ The Curated Stack
+
+### Base
+- **Framework**: Next.js (App Router, TypeScript, Tailwind CSS v4)
+
+### Optional Libraries
+- **State**: Zustand
+- **Validation**: Zod
+- **Data Fetching**: TanStack React Query
+- **UI & Components**: shadcn/ui (Initializes & adds all components automatically)
+- **Database & ORM**: Supabase JS client, Drizzle ORM (Postgres + Drizzle Kit)
+- **Authentication**: Better Auth
+- **Email**: Resend
+- **Payments**: Mutually exclusive selection between **Stripe** and **Polar.sh**
+- **AI SDK**: Vercel AI SDK & OpenRouter Provider support
+- **Linting & Formatting**: Choose between **ESLint + Prettier** or **Biome** (High speed)
+- **UI Helpers**: nuqs, React Hook Form, Day.js, Lodash
+
+---
+
+## 🚀 Quick Start
+
+Launch the wizard without installation:
+
+```bash
+npx vibe-now
+```
+
+---
+
+## 🛠️ Local Development
+
+Clone the repo to customize the logic or add your own favorite packages.
+
+### 1. Installation
+```bash
+git clone https://github.com/mosster/vibe-now.git
+cd vibe-now
+npm install
+```
+
+### 2. Linking for Development
+To use the `vibe-now` command globally on your machine while developing:
+```bash
+npm link
+```
+Now you can run `vibe-now` from any directory!
+
+### 3. Adding New Packages
+The CLI uses a group-based configuration for easy maintenance. To add a new library:
+1. Open `lib/packages.js`.
+2. Find the relevant `PACKAGE_GROUPS` entry or add a new one.
+
+```javascript
+{
+  category: 'My New Category',
+  items: [
+    {
+      id: 'myPackage',
+      name: 'Cool Library',
+      install: ['cool-lib-package'],
+      default: false
+    }
+  ]
+}
+```
+
+---
+
+## 📦 Publishing
+
+When you're ready to release a new version:
+
+1. Update version: `npm version patch` (or minor/major)
+2. Login: `npm login`
+3. Publish: `npm publish --access public`
+
+---
+
+## 📜 License
+MIT © [Ed Moss](https://github.com/mosster)

package/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import minimist from 'minimist';
+import { Plop, run } from 'plop';
+
+const args = process.argv.slice(2);
+const argv = minimist(args);
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+Plop.prepare({
+    cwd: argv.cwd,
+    configPath: path.join(__dirname, 'plopfile.js'),
+    preload: argv.preload || [],
+    completion: argv.completion,
+}, env => Plop.execute(env, run));

package/lib/packages.js

@@ -0,0 +1,195 @@
+/**
+ * Configuration for all optional packages and their install/init commands.
+ * Grouped by category for better UX.
+ */
+export const PACKAGE_GROUPS = [
+  {
+    category: 'State Management',
+    items: [
+      {
+        id: 'zustand',
+        name: 'Zustand',
+        install: ['zustand'],
+        default: true,
+      },
+    ],
+  },
+  {
+    category: 'Validation',
+    items: [
+      {
+        id: 'zod',
+        name: 'Zod',
+        install: ['zod'],
+        default: true,
+      },
+    ],
+  },
+  {
+    category: 'Data Fetching',
+    items: [
+      {
+        id: 'reactQuery',
+        name: 'TanStack React Query',
+        install: ['@tanstack/react-query'],
+        default: true,
+      },
+    ],
+  },
+  {
+    category: 'UI & Components',
+    items: [
+      {
+        id: 'shadcn',
+        name: 'shadcn/ui (Initializes & adds all components)',
+        install: [],
+        commands: [
+          ['npx', 'shadcn@latest', 'init', '-y'],
+          ['npx', 'shadcn@latest', 'add', '--all', '-y'],
+        ],
+        default: true,
+      },
+    ],
+  },
+  {
+    category: 'Authentication',
+    items: [
+      {
+        id: 'betterAuth',
+        name: 'Better Auth',
+        install: ['better-auth'],
+        default: false,
+      },
+    ],
+  },
+  {
+    category: 'Database & ORM',
+    items: [
+      {
+        id: 'supabase',
+        name: 'Supabase JS client',
+        install: ['@supabase/supabase-js'],
+        default: true,
+      },
+      {
+        id: 'drizzle',
+        name: 'Drizzle ORM (with Postgres & Kit)',
+        install: ['drizzle-orm', 'pg'],
+        devInstall: ['drizzle-kit'],
+        default: true,
+      },
+    ],
+  },
+  {
+    category: 'Email',
+    items: [
+      {
+        id: 'resend',
+        name: 'Resend',
+        install: ['resend'],
+        default: false,
+      },
+    ],
+  },
+  {
+    category: 'Payments (Select One)',
+    type: 'list',
+    id: 'paymentProvider',
+    choices: [
+      { name: 'None', value: 'none' },
+      { name: 'Stripe (Server + Client SDKs)', value: 'stripe' },
+      { name: 'Polar.sh (SDK + Next.js integration)', value: 'polar' },
+    ],
+    default: 'none',
+    // Mapping provider value to actual package config
+    providerConfig: {
+      stripe: {
+        name: 'Stripe',
+        install: ['stripe', '@stripe/stripe-js', '@stripe/react-stripe-js'],
+      },
+      polar: {
+        name: 'Polar.sh',
+        install: ['@polar-sh/sdk', '@polar-sh/nextjs'],
+      },
+    },
+  },
+  {
+    category: 'AI SDK',
+    items: [
+      {
+        id: 'aiSdk',
+        name: 'Vercel AI SDK',
+        install: ['ai'],
+        default: false,
+      },
+      {
+        id: 'openRouter',
+        name: 'OpenRouter AI SDK Provider',
+        install: ['@openrouter/ai-sdk-provider'],
+        default: false,
+      },
+    ],
+  },
+  {
+    category: 'Linting & Formatting',
+    type: 'list',
+    id: 'linter',
+    choices: [
+      { name: 'None', value: 'none' },
+      { name: 'ESLint + Prettier (Standard)', value: 'eslint' },
+      { name: 'Biome (Fast, All-in-one)', value: 'biome' },
+    ],
+    default: 'eslint',
+    providerConfig: {
+      eslint: {
+        name: 'ESLint + Prettier',
+        devInstall: [
+          'eslint',
+          'eslint-config-next',
+          'prettier',
+          'eslint-config-prettier',
+          'eslint-plugin-prettier'
+        ],
+      },
+      biome: {
+        name: 'Biome',
+        devInstall: ['@biomejs/biome'],
+        commands: [
+          ['npx', '@biomejs/biome', 'init']
+        ],
+      },
+    },
+  },
+  {
+    category: 'UI Helpers',
+    items: [
+      {
+        id: 'nuqs',
+        name: 'nuqs (Type-safe query params)',
+        install: ['nuqs'],
+        default: false,
+      },
+      {
+        id: 'hookForm',
+        name: 'React Hook Form',
+        install: ['react-hook-form'],
+        default: true,
+      },
+      {
+        id: 'dayjs',
+        name: 'Day.js (Date handling)',
+        install: ['dayjs'],
+        default: false,
+      },
+      {
+        id: 'lodash',
+        name: 'Lodash (Utilities)',
+        install: ['lodash'],
+        default: false,
+      },
+    ],
+  },
+];
+
+// Helper to get a flat list of all potential packages for the prompt validation or internal logic if needed
+export const ALL_ITEMS = PACKAGE_GROUPS.flatMap(group => group.items || []);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "vibe-now",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "vibe-now": "./index.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Ed Moss <ed@mossified.com>",
+  "license": "ISC",
+  "description": "Quickly scaffold a Next.js app with a curated stack",
+  "dependencies": {
+    "execa": "^8.0.1",
+    "fs-extra": "^11.3.3",
+    "inquirer": "^9.2.16",
+    "minimist": "^1.2.8",
+    "ora": "^9.0.0",
+    "plop": "^4.0.4"
+  }
+}

package/plopfile.js

@@ -0,0 +1,190 @@
+import { execa } from 'execa';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import ora from 'ora';
+import { PACKAGE_GROUPS, ALL_ITEMS } from './lib/packages.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default function (plop) {
+    plop.setGenerator('next-app', {
+        description: 'Scaffold a custom Next.js app',
+        prompts: [
+            {
+                type: 'input',
+                name: 'projectName',
+                message: 'What is your project name?',
+                default: 'my-vibe-now',
+                validate: (input) => {
+                    const validName = /^[a-z0-9-_.]+$/.test(input);
+                    if (!validName) {
+                        return 'Project name must be url-safe (a-z, 0-9, -, _, .)';
+                    }
+                    if (input === '.' && fs.readdirSync(process.cwd()).length > 0) {
+                        return 'Current directory is not empty. Please provide a different project name.';
+                    }
+                    return true;
+                }
+            },
+            ...PACKAGE_GROUPS.flatMap((group) => {
+                if (group.type === 'list') {
+                    return [{
+                        type: 'list',
+                        name: group.id,
+                        message: `${group.category}:`,
+                        choices: group.choices,
+                        default: group.default,
+                    }];
+                }
+                return group.items.map(item => ({
+                    type: 'confirm',
+                    name: item.id,
+                    message: `${group.category}: Include ${item.name}?`,
+                    default: item.default,
+                }));
+            }),
+        ],
+        actions: (data) => {
+            const actions = [];
+            const projectPath = path.join(process.cwd(), data.projectName);
+
+            // 1. Create Base Next.js App
+            actions.push({
+                type: 'customSync',
+                async action(answers) {
+                    const spinner = ora({
+                        text: `Creating base Next.js app in ${answers.projectName}...`,
+                        color: 'cyan',
+                    }).start();
+
+                    try {
+                        await execa('npx', [
+                            'create-next-app@latest',
+                            answers.projectName,
+                            '--ts',
+                            '--tailwind',
+                            '--app',
+                            '--eslint',
+                            '--import-alias',
+                            '@/*',
+                            '--yes',
+                        ]);
+                        spinner.succeed('Base Next.js app created!');
+                        return 'Base Next.js app created';
+                    } catch (error) {
+                        spinner.fail('Failed to create Next.js app');
+                        throw error;
+                    }
+                },
+            });
+
+            // 2. Install selected packages & run commands
+            actions.push({
+                type: 'customSync',
+                async action(answers) {
+                    // Collect standard selections
+                    const selectedPackages = ALL_ITEMS.filter(item => answers[item.id]);
+
+                    // Collect list-based selections (e.g. Payments)
+                    PACKAGE_GROUPS.filter(g => g.type === 'list').forEach(group => {
+                        const choice = answers[group.id];
+                        if (choice && choice !== 'none' && group.providerConfig[choice]) {
+                            selectedPackages.push({
+                                ...group.providerConfig[choice],
+                                id: `${group.id}_${choice}` // unique internal id
+                            });
+                        }
+                    });
+
+                    if (selectedPackages.length === 0) return 'No additional packages selected';
+
+                    const pkgNames = selectedPackages.map(p => p.name).join(', ');
+                    const installSpinner = ora({
+                        text: `Installing: ${pkgNames}...`,
+                        color: 'magenta',
+                    }).start();
+
+                    const installCmds = selectedPackages.flatMap(pkg => pkg.install || []);
+                    const devInstallCmds = selectedPackages.flatMap(pkg => pkg.devInstall || []);
+
+                    try {
+                        // Standard Installs
+                        if (installCmds.length > 0) {
+                            await execa('npm', ['install', ...installCmds], { cwd: projectPath });
+                        }
+
+                        // Dev Installs
+                        if (devInstallCmds.length > 0) {
+                            installSpinner.text = 'Installing devDependencies...';
+                            await execa('npm', ['install', '-D', ...devInstallCmds], { cwd: projectPath });
+                        }
+                        installSpinner.succeed('Packages installed successfully!');
+                    } catch (error) {
+                        installSpinner.fail('Package installation failed');
+                        throw error;
+                    }
+
+                    // Run initialization commands (like shadcn init)
+                    for (const pkg of selectedPackages) {
+                        if (pkg.commands && pkg.commands.length > 0) {
+                            console.log(`\n✨ Finalizing ${pkg.name}...`);
+
+                            try {
+                                for (const cmd of pkg.commands) {
+                                    const [command, ...args] = cmd;
+                                    // Use 'inherit' so user can see/interact with shadow-style commands
+                                    await execa(command, args, {
+                                        cwd: projectPath,
+                                        stdio: 'inherit'
+                                    });
+                                }
+                            } catch (error) {
+                                console.error(`❌ Failed to initialize ${pkg.name}`);
+                                throw error;
+                            }
+                        }
+                    }
+
+                    // 3. Generate README and AGENTS files
+                    const docSpinner = ora({
+                        text: 'Generating custom documentation and agent rules...',
+                        color: 'blue',
+                    }).start();
+
+                    try {
+                        const templateData = {
+                            projectName: answers.projectName === '.' ? path.basename(projectPath) : answers.projectName,
+                            selectedPackages
+                        };
+
+                        const readmeTmpl = fs.readFileSync(path.join(__dirname, 'templates/README.md.hbs'), 'utf8');
+                        const agentsTmpl = fs.readFileSync(path.join(__dirname, 'templates/AGENTS.md.hbs'), 'utf8');
+
+                        const renderedReadme = plop.renderString(readmeTmpl, templateData);
+                        const renderedAgents = plop.renderString(agentsTmpl, templateData);
+
+                        fs.writeFileSync(path.join(projectPath, 'README.md'), renderedReadme);
+                        fs.writeFileSync(path.join(projectPath, 'AGENTS.md'), renderedAgents);
+
+                        docSpinner.succeed('Documentation and AGENTS.md generated!');
+                    } catch (error) {
+                        docSpinner.fail('Failed to generate documentation files');
+                        console.error(error);
+                    }
+
+                    return 'All selected packages installed and initialized';
+                },
+            });
+
+            actions.push('\n🌌 Vibe Check: COMPLETE. Your stack is ready.');
+            actions.push(`🚀 Next steps:\n   cd ${data.projectName}\n   npm run dev\n`);
+
+            return actions;
+        },
+    });
+
+    plop.setActionType('customSync', async (answers, config) => {
+        return await config.action(answers);
+    });
+}

package/templates/AGENTS.md.hbs

@@ -0,0 +1,45 @@
+# Agent Guidance & Project Standards
+
+This document serves as a reference for AI Coding Assistants (Cursor, Claude, etc.) to ensure consistency and
+high-quality engineering standards.
+
+## 🏗️ Architecture Overview
+- **Framework**: Next.js 15+ (App Router)
+- **Language**: TypeScript (Strict mode)
+- **Styling**: Tailwind CSS (Utility-first)
+- **Components**: shadcn/ui (Radix UI primitives)
+
+## 🛠️ Tech Stack Consistency
+{{#each selectedPackages}}
+- **{{this.name}}**: Use standard patterns as defined in official documentation.
+{{/each}}
+
+## 🤖 AI Coding Rules
+
+### 1. General Principles
+- **Conciseness**: Write clean, modular code. Avoid bloated components.
+- **Type Safety**: Avoid `any`. Use Zod for runtime validation and TypeScript for compile-time safety.
+- **Modern Syntax**: Prefer functional components, hooks, and async/await.
+
+### 2. Component Standards
+- Small, focused components in `components/`.
+- UI primitives in `components/ui/`.
+- Use `cn()` utility for conditional classes.
+- Favor Server Components by default; use `'use client'` sparingly and only at the leaf nodes.
+
+### 3. State & Data
+- **Server State**: Use TanStack React Query or Server Actions.
+- **Client State**: Use Zustand for global state only if necessary.
+- **Forms**: Use React Hook Form with Zod resolvers.
+
+### 4. Performance & SEO
+- Use Next.js `
+<Image />` for optimized assets.
+- Ensure proper semantic HTML and ARIA labels.
+- Implement metadata for every page.
+
+## 📝 Best Practices
+- Follow the "Rule of Three": If you repeat logic three times, abstract it.
+- Keep business logic separate from UI logic where possible.
+- Use meaningful variable and function names.
+- Always include error handling for data fetching and mutations.

package/templates/README.md.hbs

@@ -0,0 +1,28 @@
+# {{projectName}}
+
+This project was bootstrapped with [vibe-now](https://github.com/mosster/vibe-now).
+
+## 🚀 Installed Stack
+
+### Core
+- **Next.js** (App Router)
+- **TypeScript**
+- **Tailwind CSS** (v4)
+
+### Selected Features
+{{#each selectedPackages}}
+- **{{this.name}}**
+{{/each}}
+
+## 🛠️ Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+---
+Generated by quick-vibe