start-vibing-stacks 2.2.0 → 2.4.0

package/stacks/_shared/config/security-rules.json

@@ -5,17 +5,39 @@
   },
   "sensitivePatterns": {
     "forbidden": [
-      "eval(",
-      "exec(",
-      "system(",
-      "passthru(",
-      "shell_exec(",
       "password:",
       "passwordHash",
       "apiKey:",
       "secret:"
     ]
   },
+  "envExposure": {
+    "$comment": "NEXT_PUBLIC_ vars are embedded in browser JS bundle. These patterns indicate secrets being exposed to the client.",
+    "forbiddenPublicEnvPatterns": [
+      "NEXT_PUBLIC_.*SECRET",
+      "NEXT_PUBLIC_.*TOKEN",
+      "NEXT_PUBLIC_.*PRIVATE",
+      "NEXT_PUBLIC_.*PASSWORD",
+      "NEXT_PUBLIC_.*CREDENTIAL"
+    ],
+    "forbiddenPublicEnvExact": [
+      "NEXT_PUBLIC_OPENAI_KEY",
+      "NEXT_PUBLIC_OPENAI_API_KEY",
+      "NEXT_PUBLIC_STRIPE_SECRET",
+      "NEXT_PUBLIC_STRIPE_SECRET_KEY",
+      "NEXT_PUBLIC_DATABASE_URL",
+      "NEXT_PUBLIC_SUPABASE_SERVICE_KEY",
+      "NEXT_PUBLIC_FIREBASE_ADMIN_KEY"
+    ],
+    "safePublicEnvPatterns": [
+      "NEXT_PUBLIC_.*URL",
+      "NEXT_PUBLIC_.*ID",
+      "NEXT_PUBLIC_STRIPE_KEY",
+      "NEXT_PUBLIC_GA_",
+      "NEXT_PUBLIC_SENTRY_DSN"
+    ],
+    "rule": "API keys, secrets, and tokens MUST stay server-side. Use Route Handlers or Server Actions as proxy."
+  },
   "cookies": {
     "httpOnly": true,
     "secure": true,

package/stacks/_shared/hooks/user-prompt-submit.ts

@@ -11,6 +11,7 @@ import { join } from 'path';
 
 const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
 const ACTIVE_PROJECT = join(PROJECT_DIR, '.claude', 'config', 'active-project.json');
+const STANDARDS_REVIEW = join(PROJECT_DIR, '.claude', 'config', 'standards-review.json');
 
 let stackName = 'Unknown';
 let qualityCmd = 'Run quality gates';
@@ -18,7 +19,6 @@ try {
   if (existsSync(ACTIVE_PROJECT)) {
     const config = JSON.parse(readFileSync(ACTIVE_PROJECT, 'utf8'));
     stackName = config.stack || 'Unknown';
-    // Read quality gates command from stack config
     const stackConfig = join(PROJECT_DIR, '.claude', 'config', 'quality-gates.json');
     if (existsSync(stackConfig)) {
       const gates = JSON.parse(readFileSync(stackConfig, 'utf8'));
@@ -27,6 +27,30 @@ try {
   }
 } catch {}
 
+interface ReviewFile {
+  status: string;
+  sources?: string[];
+  patterns?: { category: string; name: string }[];
+}
+
+let standardsContext = '';
+try {
+  if (!existsSync(STANDARDS_REVIEW)) {
+    standardsContext = `\n\nSTANDARDS REVIEW NEEDED: No standards-review.json found. ` +
+      `This project may have existing coding standards (.cursorrules, composer.json configs). ` +
+      `Ask the user: "I noticed this project hasn't been scanned for existing standards. ` +
+      `Would you like me to review your codebase patterns and adapt my behavior, ` +
+      `or should I use the default standards?"`;
+  } else {
+    const review: ReviewFile = JSON.parse(readFileSync(STANDARDS_REVIEW, 'utf8'));
+    if (review.status === 'adapted' && review.patterns && review.patterns.length > 0) {
+      const patternList = review.patterns.map(p => `- [${p.category}] ${p.name}`).join('\n');
+      standardsContext = `\n\nPROJECT STANDARDS (scanned from ${(review.sources || []).join(', ')}):\n${patternList}\n` +
+        `Follow these project-specific patterns. They take priority over generic defaults.`;
+    }
+  }
+} catch {}
+
 async function main(): Promise<void> {
   let hookInput: any = {};
   try {
@@ -65,7 +89,7 @@ async function main(): Promise<void> {
    a. "## Last Change" (date: ${today}, branch, summary)
    b. Update ALL affected rule/flow sections
 
-6. Run stop-validator before finishing.`;
+6. Run stop-validator before finishing.${standardsContext}`;
 
   console.log(JSON.stringify({ continue: true, systemMessage }));
   process.exit(0);

package/stacks/frontend/react/skills/preline-ui/SKILL.md

@@ -10,7 +10,7 @@ Preline is a **semantic token-based design system** built on TailwindCSS. It pro
 - Theme generator for custom color schemes
 - Light + dark mode via `data-theme` + `.dark`
 
-## Installation (Laravel + Inertia)
+## Installation
 
 ### Step 1: Install
 
@@ -21,7 +21,7 @@ npm install preline @tailwindcss/forms
 ### Step 2: CSS Config
 
 ```css
-/* resources/css/app.css */
+/* src/app/globals.css (Next.js) or styles/globals.css */
 @import "tailwindcss";
 
 /* Preline — MUST be in this order */
@@ -31,39 +31,35 @@ npm install preline @tailwindcss/forms
 @import "./node_modules/preline/themes/theme.css"; /* Base theme */
 ```
 
-### Step 3: Vite Config
+### Step 3: Init Preline on Route Changes (MANDATORY)
 
-```js
-// vite.config.js
-import { defineConfig } from 'vite';
-import laravel from 'laravel-vite-plugin';
-import react from '@vitejs/plugin-react';
+```tsx
+// src/components/PrelineInit.tsx
+'use client';
 
-export default defineConfig({
-  plugins: [
-    laravel({ input: ['resources/css/app.css', 'resources/js/app.tsx'], refresh: true }),
-    react(),
-  ],
-});
-```
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
 
-### Step 4: Init Preline in Inertia (MANDATORY)
+export function PrelineInit() {
+  const pathname = usePathname();
 
-```tsx
-// resources/js/app.tsx
-import { router } from '@inertiajs/react';
-
-// Re-init Preline components after every SPA navigation
-router.on('navigate', () => {
-  setTimeout(() => {
-    import('preline/preline').then(({ HSStaticMethods }) => {
-      HSStaticMethods.autoInit();
-    });
-  }, 100);
-});
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      import('preline/preline').then(({ HSStaticMethods }) => {
+        HSStaticMethods.autoInit();
+      });
+    }, 100);
+    return () => clearTimeout(timer);
+  }, [pathname]);
+
+  return null;
+}
+
+// Add to root layout:
+// <PrelineInit />
 ```
 
-**Rule:** Without `HSStaticMethods.autoInit()`, dropdowns, modals, and accordions will NOT work after Inertia navigation.
+**Rule:** Without `HSStaticMethods.autoInit()`, dropdowns, modals, and accordions will NOT work after client-side navigation.
 
 ## Templates & Components (840+ free)
 
@@ -80,11 +76,11 @@ router.on('navigate', () => {
 
 1. Browse https://preline.co/examples.html
 2. Click a block → copy the HTML/JSX
-3. Adapt to React + Inertia:
-   - Replace `<a href>` with `<Link href>` (Inertia)
+3. Adapt to React:
+   - Replace `<a href>` with Next.js `<Link href>` (from `next/link`)
    - Replace `class=` with `className=`
    - Add Preline `data-*` attributes for interactive components
-   - Use `usePage().props` for dynamic data
+   - Pass data via props or fetch with TanStack Query / Server Components
 
 ### Example: Copy a Hero Block
 
@@ -245,7 +241,7 @@ function ThemeToggle() {
 }
 ```
 
-## Using Components with React (Inertia)
+## Using Components with React
 
 ### Navbar
 
@@ -327,7 +323,7 @@ function ThemeToggle() {
 
 ```bash
 # Generate theme from config
-npx preline-theme-generator /tmp/config.json ./resources/css/themes/brand.css
+npx preline-theme-generator /tmp/config.json ./src/styles/themes/brand.css
 
 # Config format:
 {
@@ -359,4 +355,4 @@ npx preline-theme-generator /tmp/config.json ./resources/css/themes/brand.css
 | Force HTML class changes | Theme activation via `data-theme` only |
 | Invent token names | Follow Preline's naming system |
 | `@apply` for component styles | React components with token classes |
-| Skip `HSStaticMethods.autoInit()` | Always re-init after Inertia navigation |
+| Skip `HSStaticMethods.autoInit()` | Always re-init after client-side navigation |

package/stacks/frontend/react/skills/react-standards/SKILL.md

@@ -5,16 +5,16 @@
 - **ReactJS >= 19** — MANDATORY
 - **TailwindCSS >= 4** — MANDATORY
 
-## Translation Pattern
+## Label Constants Pattern
 
 ```tsx
-// ✅ Translations as CONST at the top, BEFORE hooks
+// ✅ Labels as CONST at the top, BEFORE hooks
 const LABELS = {
-    title: __('dashboard.title'),
-    save: __('common.save'),
-    cancel: __('common.cancel'),
-    errorRequired: __('errors.field_required'),
-};
+    title: 'Dashboard',
+    save: 'Save',
+    cancel: 'Cancel',
+    errorRequired: 'This field is required',
+} as const;
 
 export default function Dashboard() {
     const [data, setData] = useState(null);
@@ -22,14 +22,14 @@ export default function Dashboard() {
     return <h1>{LABELS.title}</h1>;
 }
 
-// ❌ NEVER call __() inside JSX (Hook violations)
-return <h1>{__('dashboard.title')}</h1>; // ❌
+// ❌ NEVER scatter string literals across JSX
+return <h1>Dashboard</h1>; // ❌ Duplicated, hard to maintain
 ```
 
 **Rules:**
-- Translations in `CONST` variables before state hooks
-- New strings → add to `lang/en/*.php` and `lang/pt/*.php`
-- Error strings centralized in `lang/*/errors.php`
+- Labels in `CONST` objects before state hooks for stable references
+- For i18n projects, use `next-intl` or `i18next` — same CONST pattern applies with `t()` calls
+- Error strings centralized in a shared constants file
 
 ## Debug Logging
 
@@ -65,11 +65,11 @@ export default function Dashboard() {
 
 ```tsx
 // ═══════════════════════════════════════════
-// 1. TRANSLATIONS (before hooks)
+// 1. LABELS (before hooks)
 // ═══════════════════════════════════════════
 const LABELS = {
-    title: __('dashboard.title'),
-    save: __('common.save'),
+    title: 'Dashboard',
+    save: 'Save',
 } as const;
 
 // ═══════════════════════════════════════════
@@ -156,7 +156,7 @@ import { cn } from '@/lib/utils';
 5. **Shared styles** — create a `styles.ts` file for cross-component constants
 
 ```tsx
-// resources/js/styles.ts — shared across components
+// src/styles.ts — shared across components
 export const SHARED_STYLES = {
     page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
     btnPrimary: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover ...',
@@ -187,10 +187,10 @@ export default function Bad() {
 ## SVG Icons
 
 ```tsx
-// ✅ Separate files, import with ?react
-// resources/js/Icons/CheckIcon.svg
-import CheckIcon from '@/Icons/CheckIcon.svg?react';
-import { CheckIcon, AlertIcon } from '@/Icons';
+// ✅ Separate files, import with ?react (Vite) or as components
+// src/components/icons/CheckIcon.svg
+import CheckIcon from '@/components/icons/CheckIcon.svg?react';
+import { CheckIcon, AlertIcon } from '@/components/icons';
 
 // ❌ Inline SVG
 <svg viewBox="0 0 24 24">...</svg> // ❌ Bloats JSX

package/stacks/frontend/react/skills/react-ui-patterns/SKILL.md

@@ -138,7 +138,7 @@ function UserList({ users }: { users: User[] }) {
         icon={<Users className="h-8 w-8" />}
         title="No users yet"
         description="Invite your first team member"
-        action={{ label: 'Invite User', onClick: () => router.visit('/users/invite') }}
+        action={{ label: 'Invite User', onClick: () => window.location.assign('/users/invite') }}
       />
     );
   }
@@ -191,57 +191,76 @@ function EmptyState({ icon, title, description, action }: {
 </button>
 ```
 
-## Form Pattern (Inertia.js)
+## Form Pattern (React Hook Form + Zod)
 
 ```tsx
-import { useForm } from '@inertiajs/react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMutation } from '@tanstack/react-query';
+import { z } from 'zod';
+import { toast } from 'sonner';
+
+const CreateUserSchema = z.object({
+  name: z.string().min(2, 'Name is required'),
+  email: z.string().email('Invalid email'),
+});
+
+type CreateUserForm = z.infer<typeof CreateUserSchema>;
 
 export default function CreateUser() {
-  const { data, setData, post, processing, errors, reset } = useForm({
-    name: '',
-    email: '',
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors },
+  } = useForm<CreateUserForm>({
+    resolver: zodResolver(CreateUserSchema),
   });
 
-  const submit = (e: React.FormEvent) => {
-    e.preventDefault();
-    post('/users', {
-      onSuccess: () => {
-        toast.success('User created!');
-        reset();
-      },
-      onError: () => toast.error('Failed to create user'),
-    });
-  };
+  const mutation = useMutation({
+    mutationFn: (data: CreateUserForm) =>
+      fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+      }).then((res) => {
+        if (!res.ok) throw new Error('Failed to create user');
+        return res.json();
+      }),
+    onSuccess: () => {
+      toast.success('User created!');
+      reset();
+    },
+    onError: () => toast.error('Failed to create user'),
+  });
 
   return (
-    <form onSubmit={submit} className="space-y-4">
+    <form onSubmit={handleSubmit((data) => mutation.mutate(data))} className="space-y-4">
       <div>
         <label className="block text-sm font-medium text-foreground mb-1">Name</label>
         <input
-          value={data.name}
-          onChange={e => setData('name', e.target.value)}
+          {...register('name')}
           className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground"
         />
-        {errors.name && <p className="mt-1 text-sm text-destructive">{errors.name}</p>}
+        {errors.name && <p className="mt-1 text-sm text-destructive">{errors.name.message}</p>}
       </div>
 
       <div>
         <label className="block text-sm font-medium text-foreground mb-1">Email</label>
         <input
           type="email"
-          value={data.email}
-          onChange={e => setData('email', e.target.value)}
+          {...register('email')}
           className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground"
         />
-        {errors.email && <p className="mt-1 text-sm text-destructive">{errors.email}</p>}
+        {errors.email && <p className="mt-1 text-sm text-destructive">{errors.email.message}</p>}
       </div>
 
       <button
         type="submit"
-        disabled={processing}
+        disabled={mutation.isPending}
         className="bg-primary text-primary-foreground px-6 py-2 rounded-lg hover:bg-primary-hover disabled:opacity-50 transition-colors"
       >
-        {processing ? (
+        {mutation.isPending ? (
           <span className="flex items-center gap-2">
             <Loader className="h-4 w-4 animate-spin" /> Creating...
           </span>
@@ -252,27 +271,44 @@ export default function CreateUser() {
 }
 ```
 
-## Optimistic Updates
+## Optimistic Updates (TanStack Query)
 
 ```tsx
-// Show result immediately, rollback on error
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
 function ToggleFavorite({ item }: { item: Item }) {
-  const [optimistic, setOptimistic] = useState(item.isFavorite);
-
-  const toggle = () => {
-    setOptimistic(!optimistic);  // Instant UI
-    router.post(`/items/${item.id}/favorite`, {}, {
-      preserveState: true,
-      onError: () => {
-        setOptimistic(item.isFavorite);  // Rollback
-        toast.error('Failed to update');
-      },
-    });
-  };
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: () =>
+      fetch(`/api/items/${item.id}/favorite`, { method: 'POST' }).then((res) => {
+        if (!res.ok) throw new Error('Failed');
+        return res.json();
+      }),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: ['items'] });
+      const previous = queryClient.getQueryData<Item[]>(['items']);
+
+      queryClient.setQueryData<Item[]>(['items'], (old) =>
+        old?.map((i) =>
+          i.id === item.id ? { ...i, isFavorite: !i.isFavorite } : i
+        )
+      );
+
+      return { previous };
+    },
+    onError: (_err, _vars, context) => {
+      queryClient.setQueryData(['items'], context?.previous);
+      toast.error('Failed to update');
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+    },
+  });
 
   return (
-    <button onClick={toggle} className="text-xl">
-      {optimistic ? '❤️' : '🤍'}
+    <button onClick={() => mutation.mutate()} className="text-xl">
+      {item.isFavorite ? '❤️' : '🤍'}
     </button>
   );
 }
@@ -294,5 +330,5 @@ function ToggleFavorite({ item }: { item: Item }) {
 1. **`if (loading) return <Spinner />`** — check `loading && !data` instead
 2. **Silent catch** — always toast/display errors to user
 3. **No empty state** — every list needs one
-4. **Clickable button during submit** — always `disabled={processing}`
+4. **Clickable button during submit** — always `disabled={isPending}` or `disabled={isSubmitting}`
 5. **Console.log-only errors** — user must see feedback

package/stacks/frontend/react/skills/tailwind-patterns/SKILL.md

@@ -15,7 +15,7 @@
 ## Setup (v4)
 
 ```css
-/* resources/css/app.css (Laravel + Inertia) */
+/* src/app/globals.css */
 @import "tailwindcss";
 
 @theme {

package/stacks/frontend/react/skills/zod-validation/SKILL.md

@@ -113,18 +113,38 @@ if (result.success) {
 
 ### Environment Variables
 
+> **Split server and client env schemas.** `NEXT_PUBLIC_*` is embedded in the browser bundle — NEVER put secrets there.
+
 ```tsx
-const EnvSchema = z.object({
-  NEXT_PUBLIC_API_URL: z.string().url(),
-  NEXT_PUBLIC_STRIPE_KEY: z.string().startsWith('pk_'),
+// lib/env.server.ts — Server-only secrets (NEVER import from client components)
+const ServerEnvSchema = z.object({
   DATABASE_URL: z.string().min(1),
+  OPENAI_KEY: z.string().startsWith('sk-'),
+  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
   NODE_ENV: z.enum(['development', 'production', 'test']),
 });
 
-// Validate at app startup
-export const env = EnvSchema.parse(process.env);
+export const serverEnv = ServerEnvSchema.parse({
+  DATABASE_URL: process.env['DATABASE_URL'],
+  OPENAI_KEY: process.env['OPENAI_KEY'],
+  STRIPE_SECRET_KEY: process.env['STRIPE_SECRET_KEY'],
+  NODE_ENV: process.env['NODE_ENV'],
+});
+
+// lib/env.client.ts — Public vars only (safe for browser)
+const ClientEnvSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_STRIPE_KEY: z.string().startsWith('pk_'),
+});
+
+export const clientEnv = ClientEnvSchema.parse({
+  NEXT_PUBLIC_APP_URL: process.env['NEXT_PUBLIC_APP_URL'],
+  NEXT_PUBLIC_STRIPE_KEY: process.env['NEXT_PUBLIC_STRIPE_KEY'],
+});
 ```
 
+**Rule:** If a variable contains a key, secret, token, or password, it MUST be in `ServerEnvSchema` without `NEXT_PUBLIC_` prefix.
+
 ### Reusable Schemas
 
 ```tsx
@@ -160,26 +180,72 @@ const ContactSchema = z.object({
 });
 ```
 
-## Integration with Laravel (Inertia.js)
+## Integration with Next.js Server Actions
 
 ```tsx
-// Frontend validates BEFORE sending to Laravel
-const StoreLeadSchema = z.object({
+'use server';
+
+import { z } from 'zod';
+
+const CreateLeadSchema = z.object({
   name: z.string().min(2),
-  email: EmailSchema,
-  domain_id: UUIDSchema,
+  email: z.string().email().toLowerCase().trim(),
+  domainId: z.string().uuid(),
 });
 
-// In component
-const handleSubmit = (formData: unknown) => {
-  const result = StoreLeadSchema.safeParse(formData);
+export async function createLead(formData: FormData) {
+  const result = CreateLeadSchema.safeParse({
+    name: formData.get('name'),
+    email: formData.get('email'),
+    domainId: formData.get('domainId'),
+  });
+
   if (!result.success) {
-    setErrors(result.error.flatten().fieldErrors);
-    return;
+    return { errors: result.error.flatten().fieldErrors };
   }
-  // Send validated data to Laravel
-  router.post('/leads', result.data);
-};
+
+  await db.lead.create({ data: result.data });
+  return { success: true };
+}
+```
+
+### Client-Side with React Hook Form
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const CreateLeadSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  domainId: z.string().uuid(),
+});
+
+type CreateLeadForm = z.infer<typeof CreateLeadSchema>;
+
+export function LeadForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<CreateLeadForm>({
+    resolver: zodResolver(CreateLeadSchema),
+  });
+
+  const onSubmit = async (data: CreateLeadForm) => {
+    await fetch('/api/leads', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+      {/* ... */}
+    </form>
+  );
+}
 ```
 
 ## FORBIDDEN