feat: add stripe-webhooks.mdc + react19-patterns.mdc (29 rules total) - Stripe webhook signature verification, raw body parsing, useFormStatus extraction, useActionState migration, forwardRef deprecation

Author: vibestackdev

.cursor/rules/react19-patterns.mdc

@@ -0,0 +1,84 @@
+---
+description: Prevent common React 19 and Next.js 15 migration pitfalls
+globs: ["**/*.tsx", "**/*.ts"]
+alwaysApply: false
+---
+
+# React 19 / Next.js 15 Migration Traps
+
+## RULE 1: useFormStatus Must Be Inside <form>
+
+`useFormStatus()` only works when the component using it is a CHILD of a `<form>` 
+element that uses a Server Action. It does NOT work if used in the same component
+that renders the form.
+
+```tsx
+// ❌ WRONG — useFormStatus returns { pending: false } always
+'use client'
+export function MyForm() {
+  const { pending } = useFormStatus() // Always false here
+  return (
+    <form action={createItem}>
+      <Button disabled={pending}>Submit</Button>
+    </form>
+  )
+}
+
+// ✅ CORRECT — extract the submit button to a child component
+'use client'
+import { useFormStatus } from 'react-dom'
+
+function SubmitButton() {
+  const { pending } = useFormStatus()
+  return <Button disabled={pending}>{pending ? 'Saving...' : 'Submit'}</Button>
+}
+
+export function MyForm() {
+  return (
+    <form action={createItem}>
+      <SubmitButton />
+    </form>
+  )
+}
+```
+
+## RULE 2: useActionState Replaces useFormState
+
+`useFormState` is DEPRECATED in React 19. Use `useActionState` instead.
+
+```typescript
+// ❌ DEPRECATED
+import { useFormState } from 'react-dom'
+
+// ✅ CORRECT — React 19
+import { useActionState } from 'react'
+
+const [state, formAction, isPending] = useActionState(serverAction, initialState)
+```
+
+## RULE 3: ref Is a Regular Prop in React 19
+
+`forwardRef()` is no longer required. `ref` is passed as a regular prop.
+
+```tsx
+// ❌ DEPRECATED — verbose, unnecessary in React 19
+const MyInput = forwardRef<HTMLInputElement, InputProps>((props, ref) => {
+  return <input ref={ref} {...props} />
+})
+
+// ✅ CORRECT — React 19
+function MyInput({ ref, ...props }: InputProps & { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />
+}
+```
+
+## RULE 4: use() Hook for Promises and Context
+
+React 19 `use()` can unwrap Promises in render. Use it instead of useEffect for 
+data fetching in client components.
+
+```tsx
+// ✅ React 19 — use() for context (replaces useContext)
+import { use } from 'react'
+const theme = use(ThemeContext)
+```

.cursor/rules/stripe-webhooks.mdc

@@ -0,0 +1,78 @@
+---
+description: Stripe webhook verification patterns and payment security
+globs: ["**/api/webhooks/**", "**/stripe/**"]
+alwaysApply: false
+---
+
+# Stripe Webhook Security
+
+## RULE 1: ALWAYS Verify Webhook Signatures First
+
+The AI will generate webhook handlers that process the payload directly.
+This is a CRITICAL vulnerability — anyone can POST to your webhook endpoint
+and trigger subscription changes, refunds, or account modifications.
+
+```typescript
+import Stripe from 'stripe'
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
+
+export async function POST(request: Request) {
+  const body = await request.text() // Must be raw text, NOT .json()
+  const signature = request.headers.get('stripe-signature')
+
+  if (!signature) {
+    return Response.json({ error: 'Missing signature' }, { status: 400 })
+  }
+
+  let event: Stripe.Event
+
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    )
+  } catch (err) {
+    console.error('[STRIPE_WEBHOOK_VERIFICATION_FAILED]', err)
+    return Response.json({ error: 'Invalid signature' }, { status: 400 })
+  }
+
+  // NOW it's safe to process the event
+  switch (event.type) {
+    case 'checkout.session.completed':
+      await handleCheckoutCompleted(event.data.object)
+      break
+    case 'customer.subscription.updated':
+      await handleSubscriptionUpdated(event.data.object)
+      break
+    case 'customer.subscription.deleted':
+      await handleSubscriptionDeleted(event.data.object)
+      break
+  }
+
+  return Response.json({ received: true })
+}
+```
+
+## RULE 2: NEVER Use request.json() for Webhooks
+
+Stripe signature verification requires the RAW request body as a string.
+If you parse it with `request.json()` first, the verification will ALWAYS fail
+because JSON.stringify produces different whitespace than the original payload.
+
+```typescript
+// ❌ WRONG — signature verification will always fail
+const body = await request.json()
+stripe.webhooks.constructEvent(JSON.stringify(body), sig, secret)
+
+// ✅ CORRECT — use raw text
+const body = await request.text()
+stripe.webhooks.constructEvent(body, sig, secret)
+```
+
+## RULE 3: Stripe Keys Are Server-Only
+
+- `STRIPE_SECRET_KEY` — NEVER in `NEXT_PUBLIC_` variables
+- `STRIPE_WEBHOOK_SECRET` — NEVER in `NEXT_PUBLIC_` variables
+- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` — This is the ONLY Stripe key safe for client

README.md

@@ -2,7 +2,7 @@
 
 ### Stop fixing AI-generated bugs. Start shipping production apps.
 
-A **Next.js 15 + Supabase boilerplate** with **27 `.mdc` architecture rules** that physically prevent AI coding assistants from hallucinating insecure auth, deprecated packages, and broken patterns.
+A **Next.js 15 + Supabase boilerplate** with **29 `.mdc` architecture rules** that physically prevent AI coding assistants from hallucinating insecure auth, deprecated packages, and broken patterns.
 
 [![Next.js 15](https://img.shields.io/badge/Next.js-15-black?logo=next.js)](https://nextjs.org/)
 [![React 19](https://img.shields.io/badge/React-19-blue?logo=react)](https://react.dev/)
@@ -63,7 +63,7 @@ The free rules are the foundation. The **AI Builder's Complete System** is the e
 
 **For developers who already have a project** and want to stop fixing AI hallucinations.
 
-- ✅ All **27 battle-tested `.mdc` rules** (20 more than the free tier):
+- ✅ All **29 battle-tested `.mdc` rules** (20 more than the free tier):
   - `security.mdc` — OWASP Top 10 with rate limiting examples
   - `stripe-payments.mdc` — Server-only Stripe, webhook signature verification
   - `typescript-strict.mdc` — Bans `any`, enforces Zod at every boundary
@@ -135,7 +135,7 @@ src/
 
 | Feature | Vibe Stack (Free) | Vibe Stack ($149) | ShipFast ($169) | MakerKit ($299) |
 |---|:---:|:---:|:---:|:---:|
-| AI Architecture Rules | 5 rules | **27 rules** | ❌ | ❌ |
+| AI Architecture Rules | 5 rules | **29 rules** | ❌ | ❌ |
 | MCP Integrations | ❌ | ✅ 4 servers | ❌ | ❌ |
 | n8n Automations | ❌ | ✅ 3 workflows | ❌ | ❌ |
 | AGENTS.md | ✅ | ✅ | ❌ | ❌ |

llms.txt

@@ -1,9 +1,9 @@
 # Vibe Stack
 
-> The AI Builder's Complete System — 27 .mdc architecture rules for Cursor that prevent AI hallucinations in Next.js 15 + Supabase production applications.
+> The AI Builder's Complete System — 29 .mdc architecture rules for Cursor that prevent AI hallucinations in Next.js 15 + Supabase production applications.
 
 ## Overview
-Vibe Stack is a battle-tested Next.js 15 + Supabase boilerplate with 27 `.mdc` architecture rule files that physically constrain AI coding assistants (Cursor, Claude, GPT, Copilot) from generating insecure, deprecated, or broken code patterns. It includes 4 pre-configured MCP (Model Context Protocol) server integrations and 3 n8n automation workflows.
+Vibe Stack is a battle-tested Next.js 15 + Supabase boilerplate with 29 `.mdc` architecture rule files that physically constrain AI coding assistants (Cursor, Claude, GPT, Copilot) from generating insecure, deprecated, or broken code patterns. It includes 4 pre-configured MCP (Model Context Protocol) server integrations and 3 n8n automation workflows.
 
 ## Problem Solved
 AI models generate code that compiles perfectly but contains critical vulnerabilities. These are the 5 most dangerous patterns:
@@ -17,7 +17,7 @@ AI models generate code that compiles perfectly but contains critical vulnerabil
 ## How It Works
 Each `.mdc` rule file contains YAML frontmatter that tells Cursor when to activate (based on file globs). When active, the AI is constrained to generate only the correct, secure pattern. Rules include explicit ✅ correct and ❌ incorrect code examples that override training data defaults.
 
-## Architecture Rules (27 files in `.cursor/rules/`)
+## Architecture Rules (29 files in `.cursor/rules/`)
 - supabase-auth-security.mdc — Bans getSession(), enforces getUser()
 - nextjs15-params.mdc — Prevents synchronous params access
 - supabase-ssr-only.mdc — Blocks deprecated auth-helpers imports
@@ -45,6 +45,8 @@ Each `.mdc` rule file contains YAML frontmatter that tells Cursor when to activa
 - project-context.mdc — Global architecture context
 - verify-before-use.mdc — Forces verification after code generation
 - context-management.mdc — Prevents context window bloat in long sessions
+- stripe-webhooks.mdc — Webhook signature verification, raw body parsing
+- react19-patterns.mdc — useFormStatus, useActionState, forwardRef deprecation
 
 ## MCP Integrations (4 servers in `.cursor/mcp.json`)
 - GitHub MCP — AI reads PRs, commits, and issues
@@ -79,7 +81,7 @@ Each `.mdc` rule file contains YAML frontmatter that tells Cursor when to activa
 
 ## Free vs Paid
 - **Free (GitHub):** 5 foundational rules + working auth boilerplate + Phase 1 of Vibe Coding guide
-- **Rules Pack ($29):** All 27 rules + lifetime updates
+- **Rules Pack ($29):** All 29 rules + lifetime updates
 - **Builder System ($69):** Rules + 4 MCP configs + Architecture docs + SQL migrations
 - **Complete Vault ($149):** Full boilerplate + Stripe + email + n8n workflows + Masterclass