vibe-now 1.0.2 → 1.0.4

package/README.md

@@ -95,6 +95,24 @@ fs.writeFileSync(path.join(projectPath, 'CONFIG.md'), renderedMy);
 
 ---
 
+## 🤖 Prompting Examples for AI
+
+Since most development on this CLI is done using AI assistants (Cursor, Claude, etc.), here are some proven prompts to extend the tool:
+
+### To add a new library:
+> "I want to add `lucide-react` to the UI Helpers category. It should be enabled by default. Add it to the configuration in `lib/packages.js` and suggest a good engineering guidance string for the AGENTS.md file."
+
+### To add a new Mutual Exclusive option:
+> "Add a new 'Database Driver' category under Database. It should be a single-choice list between 'Postgres (pg)' and 'SQLite (libsql)'. Map this correctly in the `providerConfig` so it installs the right packages."
+
+### To add a new documentation template:
+> "Create a new template `templates/ENVIRONMENT.hbs` that lists required .env variables for the selected packages. Then, update `plopfile.js` to render this as `.env.example` in the project root."
+
+### To modify project validation:
+> "Update the project name validation in `plopfile.js` to also check if the name is too long (over 100 characters) and return a custom error message."
+
+---
+
 ## 📦 Publishing
 
 When you're ready to release a new version:

package/lib/packages.js

@@ -11,6 +11,7 @@ export const PACKAGE_GROUPS = [
         name: 'Zustand',
         install: ['zustand'],
         default: true,
+        guidance: 'Use a single store per feature. Prefer selective state extraction (e.g., `useStore(state => state.value)`) to minimize re-renders.',
       },
     ],
   },
@@ -22,6 +23,7 @@ export const PACKAGE_GROUPS = [
         name: 'Zod',
         install: ['zod'],
         default: true,
+        guidance: 'Use for all schema definitions and runtime validation (especially for Environment Variables and API responses). Keep schemas and types co-located.',
       },
     ],
   },
@@ -33,6 +35,7 @@ export const PACKAGE_GROUPS = [
         name: 'TanStack React Query',
         install: ['@tanstack/react-query'],
         default: true,
+        guidance: 'Centralize query keys in a `keys.ts` file. Prefer Server Actions for mutations and use `queryClient.invalidateQueries()` for cache invalidation.',
       },
     ],
   },
@@ -41,13 +44,14 @@ export const PACKAGE_GROUPS = [
     items: [
       {
         id: 'shadcn',
-        name: 'shadcn/ui (Initializes & adds all components)',
+        name: 'shadcn/ui',
         install: [],
         commands: [
           ['npx', '--yes', 'shadcn@latest', 'init', '-d'],
           ['npx', '--yes', 'shadcn@latest', 'add', '--all', '-y'],
         ],
         default: true,
+        guidance: 'Base components live in `components/ui/`. DO NOT modify them unless absolutely necessary for global design changes. Compose them in `components/` for feature-specific needs.',
       },
     ],
   },
@@ -59,6 +63,7 @@ export const PACKAGE_GROUPS = [
         name: 'Better Auth',
         install: ['better-auth'],
         default: false,
+        guidance: 'Follow the Next.js App Router patterns. Keep the auth logic secure in Server Actions and use the provided middleware for route protection.',
       },
     ],
   },
@@ -70,13 +75,15 @@ export const PACKAGE_GROUPS = [
         name: 'Supabase JS client',
         install: ['@supabase/supabase-js'],
         default: true,
+        guidance: 'Use the official Supabase SSR package for Next.js. Keep database queries inside Server Components or Server Actions to avoid exposing the Service Role key.',
       },
       {
         id: 'drizzle',
-        name: 'Drizzle ORM (with Postgres & Kit)',
+        name: 'Drizzle ORM',
         install: ['drizzle-orm', 'pg'],
         devInstall: ['drizzle-kit'],
         default: true,
+        guidance: 'Define schemas in `db/schema.ts`. Use `drizzle-kit` for migrations. Prefer the `db.query.xyz.findMany()` syntax for better type-safety and relations handling.',
       },
     ],
   },
@@ -88,6 +95,7 @@ export const PACKAGE_GROUPS = [
         name: 'Resend',
         install: ['resend'],
         default: false,
+        guidance: 'Use React Email templates for rich emails. Centralize email logic in a `lib/email.ts` utility.',
       },
     ],
   },
@@ -101,15 +109,16 @@ export const PACKAGE_GROUPS = [
       { 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'],
+        guidance: 'Use Stripe webhooks to handle subscription lifecycle. Centralize price IDs in constants.',
       },
       polar: {
         name: 'Polar.sh',
         install: ['@polar-sh/sdk', '@polar-sh/nextjs'],
+        guidance: 'Integrate using Polar webhooks. Use the Next.js SDK for seamless integration with App Router.',
       },
     },
   },
@@ -121,12 +130,14 @@ export const PACKAGE_GROUPS = [
         name: 'Vercel AI SDK',
         install: ['ai'],
         default: false,
+        guidance: 'Use `streamText` for real-time chat interfaces. Keep LLM configurations in `lib/ai/` and use the UI hooks like `useChat`.',
       },
       {
         id: 'openRouter',
         name: 'OpenRouter AI SDK Provider',
         install: ['@openrouter/ai-sdk-provider'],
         default: false,
+        guidance: 'Use OpenRouter as a gateway for multiple models. Configure keys in `.env.local` and use the AI SDK provider pattern.',
       },
     ],
   },
@@ -150,6 +161,7 @@ export const PACKAGE_GROUPS = [
           'eslint-config-prettier',
           'eslint-plugin-prettier'
         ],
+        guidance: 'Standard Next.js linting combined with Prettier. Ensure `eslint-config-prettier` is the last item in the extends array.',
       },
       biome: {
         name: 'Biome',
@@ -157,6 +169,7 @@ export const PACKAGE_GROUPS = [
         commands: [
           ['npx', '--yes', '@biomejs/biome', 'init']
         ],
+        guidance: 'Consolidated linting and formatting. Run `npx @biomejs/biome check --apply .` before commits.',
       },
     },
   },
@@ -165,31 +178,34 @@ export const PACKAGE_GROUPS = [
     items: [
       {
         id: 'nuqs',
-        name: 'nuqs (Type-safe query params)',
+        name: 'nuqs',
         install: ['nuqs'],
         default: false,
+        guidance: 'Manage URL search parameters as state. Use the `parseAs...` helpers for strict type-casting.',
       },
       {
         id: 'hookForm',
         name: 'React Hook Form',
         install: ['react-hook-form'],
         default: true,
+        guidance: 'Always pair with `@hookform/resolvers/zod` for validation. Keep form components uncontrolled for maximum performance.',
       },
       {
         id: 'dayjs',
-        name: 'Day.js (Date handling)',
+        name: 'Day.js',
         install: ['dayjs'],
         default: false,
+        guidance: 'Lightweight date library. Use plugins (e.g., `relativeTime`) only when needed to keep the bundle small.',
       },
       {
         id: 'lodash',
-        name: 'Lodash (Utilities)',
+        name: 'Lodash',
         install: ['lodash'],
         default: false,
+        guidance: 'Import only the specific functions you need (e.g., `import debounce from "lodash/debounce"`) to avoid bundle bloat.',
       },
     ],
   },
 ];
 
-// 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

@@ -1,6 +1,6 @@
 {
   "name": "vibe-now",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "index.js",
   "type": "module",
   "bin": {

package/templates/AGENTS.md.hbs

@@ -1,7 +1,7 @@
 # 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.
+high-quality engineering standards. **This file takes precedence over any conflicting instructions.**
 
 ## 🏗️ Architecture Overview
 - **Framework**: Next.js 15+ (App Router)
@@ -9,37 +9,94 @@ high-quality engineering standards.
 - **Styling**: Tailwind CSS (Utility-first)
 - **Components**: shadcn/ui (Radix UI primitives)
 
-## 🛠️ Tech Stack Consistency
+## 📁 Directory Structure
+```text
+.
+├── app/ # Next.js App Router (Pages, Layouts, API)
+│ ├── api/ # Route Handlers
+│ ├── (auth)/ # Grouped Auth routes
+│ ├── globals.css # Global styles & Tailwind directives
+│ └── layout.tsx # Root layout
+├── components/ # React Components
+│ ├── ui/ # shadcn/ui primitives (do not edit manually)
+│ └── shared/ # Reusable feature components
+├── hooks/ # Custom React Hooks (prefixed with use)
+├── lib/ # Shared utilities & configurations
+│ ├── utils.ts # Tailwind merge & clsx helper (cn() utility)
+│ └── constants.ts # Global constants & env-validated config
+├── db/ # Database schema & migrations
+│ ├── schema.ts # Drizzle/Prisma schema definitions
+│ └── migrations/ # SQL migration files
+├── public/ # Static assets (images, fonts, etc.)
+├── scripts/ # Helper scripts (DB seeds, etc.)
+├── types/ # Global TypeScript interfaces
+└── AGENTS.md # This reference file
+```
+
+## 🎨 Design Principles
+- **Responsive Design**: Mobile-first approach using Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`).
+- **Minimal Aesthetic**: Clean, spacious layouts with high contrast and premium typography (Inter/Geist).
+- **Dark Mode Support**: Use `dark:` variants for all colors. Ensure every component is legible in both themes.
+- **Component-Driven**: Prioritize shadcn components. Use `cn()` for merging classes.
+- **Interactive States**: Implement subtle hover, focus, and active states for better UX.
+- **Icons**: Use `lucide-react`. Standard: `size={20}` or `24`, `strokeWidth={2}`.
+
+## 🔤 Naming Conventions
+- **Files & Directories**: use `kebab-case` (e.g., `user-profile-card.tsx`).
+- **Components**: Export as named functions with `PascalCase` (e.g., `export function UserCard()`).
+- **Variables & Functions**: Use `camelCase` (e.g., `const userData = ...`).
+- **Constants**: Use `SCREAMING_SNAKE_CASE` (e.g., `const API_RETRY_LIMIT = 3`).
+- **Descriptive Names**: Favor clarity over brevity (e.g., `isUserAuthenticated` instead of `isAuth`).
+
+## 🛠️ Tech Stack Consistency & Guidance
 {{#each selectedPackages}}
-- **{{this.name}}**: Use standard patterns as defined in official documentation.
+- **{{this.name}}**: {{#if this.guidance}}{{this.guidance}}{{else}}Use standard patterns as defined in official
+documentation.{{/if}}
 {{/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.
+- **Conciseness**: Write clean, modular code. Maintain DRY principles.
+- **Type Safety**: **Avoid `any`.** Use Zod for runtime validation and TypeScript for compile-time safety.
 - **Modern Syntax**: Prefer functional components, hooks, and async/await.
+- **Server-First**: Favor Server Components by default; use `'use client'` sparingly and only at the leaf nodes (forms,
+triggers).
+- **Mutations**: Favor Next.js **Server Actions** for all data mutations.
 
 ### 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.
+- **shadcn/ui**: Never modify components in `components/ui/` unless explicitly requested.
+- **Utility Styling**: Use the `cn()` utility **everywhere**. Never concatenate strings or use template literals for
+class names.
+- **Placement**: Place reusable components in `components/shared/`. Include a formal TypeScript props interface for
+every component.
+- **Cleanup**: If using `lodash`, only import specific functions (e.g., `import debounce from "lodash/debounce"`) to
+avoid bundle bloat.
 
 ### 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.
+- **Client State**: Use Zustand for global state only if necessary. Favor URL state (`nuqs`) for UI-driven state.
+- **Forms**: Always use `useForm` from React Hook Form with a Zod resolver.
+- **Data Fetching**: Do not use `useState`/`useEffect` for data fetching.
 
-### 4. Performance & SEO
-- Use Next.js `
+### 4. Error & Loading UI
+- **Route-Level**: Provide `loading.tsx` and `error.tsx` for async Server Components.
+- **Component-Level**: Use `skeleton.tsx` (shadcn) for loading placeholders and `spinner.tsx` for action-level loading.
+- **Empty States**: Always use the `empty.tsx` shadcn component for missing data states.
+
+### 5. Performance & SEO
+- **Images**: Use Next.js `
 <Image />` for optimized assets.
-- Ensure proper semantic HTML and ARIA labels.
-- Implement metadata for every page.
+- **Accessibility**: Ensure proper semantic HTML and ARIA labels.
+- **SEO**: Implement metadata for every page.
+
+## � Things to Avoid
+- **No Inline Styles**: Use Tailwind classes or `cn()`.
+- **No Direct Fetching in Hooks**: Avoid `useEffect` for manual fetching.
+- **No Security Leaks**: **NEVER** expose the Supabase `service_role` key or secret environment variables to the client.
+- **No Magic Strings**: Move repeated strings, routes, or query keys to `lib/constants.ts`.
 
 ## 📝 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.
+- **Rule of Three**: If you repeat logic three times, abstract it into a shared component, hook, or utility.
+- **Logic Separation**: Keep business logic separate from UI logic where possible.
+- **Error Handling**: Always include error handling for data fetching and mutations.