start-vibing-stacks 2.19.0 → 2.20.0

package/dist/setup.js

@@ -187,6 +187,17 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = 'Installed CI workflow templates';
             }
         }
+        // 11e. Copy stack-level helper scripts (e.g. nodejs/scripts/check-route-slugs.mjs)
+        // copyDirRecursive is non-destructive by default: existing files in the target
+        // project's scripts/ dir are preserved unless --force is passed.
+        const stackScriptsDir = join(PACKAGE_ROOT, 'stacks', config.stack, 'scripts');
+        if (existsSync(stackScriptsDir)) {
+            const projectScriptsDir = join(projectDir, 'scripts');
+            const copied = copyDirRecursive(stackScriptsDir, projectScriptsDir, options.force);
+            if (copied > 0) {
+                spinner.text = `Installed ${copied} stack helper script(s) to scripts/`;
+            }
+        }
         // 12. Copy commands
         const sharedCommandsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'commands');
         if (existsSync(sharedCommandsDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/skills/quality-gate/SKILL.md

@@ -24,12 +24,19 @@ vendor/bin/php-cs-fixer fix --dry-run    # Code style
 
 ### Node.js Gates
 ```bash
-bun run typecheck    # TypeScript errors
-bun run lint         # ESLint
-bun run test         # Vitest
-bun run build        # Build verification
+bun run typecheck                          # TypeScript errors
+bun run lint                               # ESLint
+bun run test                               # Vitest
+node scripts/check-route-slugs.mjs         # Next.js — only run if framework=nextjs
+bun run build                              # Build verification (must come AFTER route-slugs)
 ```
 
+> **Next.js note.** `next build` does NOT validate dynamic-segment slug
+> consistency (e.g. `[id]` and `[userId]` under the same parent). The
+> `check-route-slugs.mjs` script must run **before** `build` to catch this
+> statically — see `nextjs-app-router` skill, section "Dynamic Route Slug
+> Consistency".
+
 ## Gate Results
 
 | Result | Action |

package/stacks/nodejs/scripts/check-route-slugs.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * check-route-slugs.mjs
+ *
+ * Static validator for Next.js App Router dynamic-segment naming.
+ *
+ * Catches the "You cannot use different slug names for the same dynamic path"
+ * runtime error BEFORE it ships, because `next build` does not catch it.
+ *
+ * Rule: inside the same parent directory, every bracket-named child
+ * (`[id]`, `[...slug]`, `[[...slug]]`) MUST share the same inner identifier.
+ *
+ * Examples:
+ *
+ *   OK     app/users/[userId]/page.tsx
+ *          app/users/[userId]/posts/page.tsx
+ *
+ *   FAIL   app/users/[id]/page.tsx
+ *          app/users/[userId]/posts/page.tsx     <-- different slug, same parent
+ *
+ * Usage:
+ *   node scripts/check-route-slugs.mjs            # auto-detect ./app and ./src/app
+ *   node scripts/check-route-slugs.mjs ./app      # explicit root(s)
+ *
+ * Exit codes:
+ *   0  OK
+ *   1  conflicting slug names detected
+ *   2  no app directory found (skipped, not an error in non-Next.js repos)
+ */
+
+import { readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+
+const BRACKET_RE = /^\[\[?\.\.\.?([A-Za-z0-9_]+)\]?\]$|^\[([A-Za-z0-9_]+)\]$/;
+
+function extractSlugName(dirName) {
+  const m = dirName.match(BRACKET_RE);
+  if (!m) return null;
+  return m[1] ?? m[2] ?? null;
+}
+
+async function listChildDirs(parent) {
+  const entries = await readdir(parent, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+async function walk(root, conflicts) {
+  const children = await listChildDirs(root);
+
+  const bracketChildren = children
+    .map((name) => ({ name, slug: extractSlugName(name) }))
+    .filter((c) => c.slug !== null);
+
+  if (bracketChildren.length > 1) {
+    const slugs = new Set(bracketChildren.map((c) => c.slug));
+    if (slugs.size > 1) {
+      conflicts.push({
+        parent: root,
+        children: bracketChildren.map((c) => c.name),
+      });
+    }
+  }
+
+  for (const child of children) {
+    await walk(join(root, child), conflicts);
+  }
+}
+
+async function detectRoots(args) {
+  if (args.length > 0) return args.map((p) => resolve(p));
+  const candidates = ['app', 'src/app'].map((p) => resolve(process.cwd(), p));
+  return candidates.filter((p) => existsSync(p));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const roots = await detectRoots(args);
+
+  if (roots.length === 0) {
+    console.log('[route-slugs] no app/ or src/app/ directory found — skipped.');
+    process.exit(2);
+  }
+
+  const conflicts = [];
+  for (const root of roots) {
+    const s = await stat(root).catch(() => null);
+    if (!s?.isDirectory()) continue;
+    await walk(root, conflicts);
+  }
+
+  if (conflicts.length > 0) {
+    console.error('');
+    console.error('  ROUTE SLUG CONFLICT (next.js will crash at runtime)');
+    console.error('  ' + '─'.repeat(60));
+    console.error('');
+    console.error(
+      '  Next.js requires that every bracket-named sibling under the SAME'
+    );
+    console.error(
+      '  parent directory uses the SAME inner slug name. Mixing names'
+    );
+    console.error(
+      '  produces: "You cannot use different slug names for the same'
+    );
+    console.error('  dynamic path".');
+    console.error('');
+    for (const c of conflicts) {
+      const rel = relative(process.cwd(), c.parent) || '.';
+      console.error(`  in: ${rel}/`);
+      for (const child of c.children) {
+        console.error(`    ├── ${child}`);
+      }
+      console.error('');
+    }
+    console.error('  Fix: pick ONE slug name per resource (e.g. [userId]) and');
+    console.error('       rename every conflicting sibling to match.');
+    console.error('');
+    process.exit(1);
+  }
+
+  const scanned = roots.map((r) => relative(process.cwd(), r) || '.').join(', ');
+  console.log(`[route-slugs] OK — no slug conflicts in: ${scanned}`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[route-slugs] script failed:', err);
+  process.exit(1);
+});

package/stacks/nodejs/skills/nextjs-app-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nextjs-app-router
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Next.js App Router — Modern Patterns
@@ -27,6 +27,77 @@ app/
     └── route.ts        # API route handler
 ```
 
+---
+
+## Dynamic Route Slug Consistency (CRITICAL — silent build killer)
+
+> **Next.js validates dynamic-segment slug names at REQUEST TIME, not at build time.** `next build` / `bun run build` **does not catch** this class of bug. It blows up the first time anyone hits the route in production with:
+>
+> ```
+> Error: You cannot use different slug names for the same dynamic path ('id' !== 'userId').
+> ```
+
+### The Rule
+
+Inside the **same parent directory**, every `[bracket]` child segment MUST use the **same** inner name. Pick one slug name per resource and reuse it through every nested route under it.
+
+```
+# BROKEN — same parent (app/users/), different slug names
+app/users/[id]/page.tsx
+app/users/[userId]/posts/page.tsx        ← runtime crash
+
+# CORRECT — one canonical slug per resource
+app/users/[userId]/page.tsx
+app/users/[userId]/posts/page.tsx
+app/users/[userId]/posts/[postId]/page.tsx
+```
+
+This also applies to catch-all (`[...slug]`) and optional catch-all (`[[...slug]]`) — you may not mix a `[id]` and `[...rest]` as siblings of the same parent.
+
+### Pre-Flight Check (run BEFORE creating any new dynamic route)
+
+```bash
+# Quick visual scan — list every dynamic segment with its depth
+find src/app app -type d -name '[[]*[]]' 2>/dev/null \
+  | awk -F/ '{print NF":"$0}' | sort
+```
+
+Eyeball the output: any two paths that share a prefix up to depth `N-1` and diverge into different `[name]` at depth `N` are the bug.
+
+### Programmatic Check (CI gate — mandatory)
+
+The stack ships a Bun script at `scripts/check-route-slugs.mjs`. Add it to `package.json` and wire it into the quality gate **before** `build`:
+
+```jsonc
+{
+  "scripts": {
+    "routes:check": "bun scripts/check-route-slugs.mjs",
+    "prebuild": "bun run routes:check",
+    "build": "next build"
+  }
+}
+```
+
+Why `prebuild`: makes the check unskippable for anyone running `bun run build` locally, in Vercel, or in CI. The check completes in milliseconds and exits non-zero on the first conflict, with the offending parent dir and conflicting slugs in the error message.
+
+### When to Run
+
+- ☑ **Before creating** any new `[something]/page.tsx` or `[something]/route.ts`
+- ☑ **Before any commit** touching `app/**/[*]/**`
+- ☑ **In CI** before `bun run build`
+- ☑ **As `prebuild`** in `package.json` so local builds also catch it
+
+### Convention — name your slugs by resource, not by position
+
+| Resource | Slug |
+|---|---|
+| User | `[userId]` |
+| Organization / tenant | `[orgId]` or `[tenantId]` |
+| Post / article | `[postId]` |
+| Instance ID (Evolution API, webhook key) | `[instanceKey]` (or whatever you commit to — pick once) |
+
+Generic `[id]` is acceptable only at the root of a resource (`app/users/[id]/...`) **if and only if** you stay with `[id]` through every nested segment under it. Mixing `[id]` and `[userId]` under the same parent is the bug.
+
 ## Server vs Client Components
 
 ```tsx
@@ -106,6 +177,152 @@ export async function POST(request: NextRequest) {
 }
 ```
 
+## Webhook Handler — Critical Path (avoid retry storms)
+
+> A webhook receiver is a **critical path you do not control**. The provider (Stripe, GitHub, Evolution, Meta, etc.) will retry — often aggressively, often forever — every non-`2xx`. Any error you let propagate becomes their problem AND yours.
+
+### The Three Rules
+
+1. **Verify signature with the RAW body BEFORE parsing JSON.** Parsing first leaks payload validity into your error path and can let unsigned traffic through.
+2. **Acknowledge fast (return 2xx within ≤ 5 s).** Persist the event, hand it off to a queue / `waitUntil` / background task, then return. The HTTP handler does NOT do business logic.
+3. **Idempotency by provider event ID.** Same event arriving twice (retries, replays) MUST be a no-op. Store the event ID with a unique index.
+
+### Reference Receiver (Next.js Route Handler)
+
+```ts
+// app/api/webhooks/[provider]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import crypto from 'node:crypto';
+
+export const runtime = 'nodejs'; // crypto.timingSafeEqual + raw body
+export const dynamic = 'force-dynamic';
+
+const SECRET = process.env['WEBHOOK_SECRET']!;
+
+function verify(rawBody: string, signature: string | null): boolean {
+  if (!signature) return false;
+  const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
+  const a = Buffer.from(signature);
+  const b = Buffer.from(expected);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+export async function POST(req: NextRequest) {
+  // 1) RAW body — never req.json() before signature check
+  const rawBody = await req.text();
+  const signature = req.headers.get('x-signature');
+
+  if (!verify(rawBody, signature)) {
+    // Signature failure is the ONLY 4xx we return. Provider will not retry 401.
+    return new NextResponse('invalid signature', { status: 401 });
+  }
+
+  // 2) Parse AFTER signature passes
+  let event: { id: string; type: string; data: unknown };
+  try {
+    event = JSON.parse(rawBody);
+  } catch {
+    // Malformed body from an authenticated source = log + 200.
+    // Returning 400/500 here triggers infinite retries for a payload we cannot process anyway.
+    logger.warn({ rawBody }, 'webhook.parse_failed');
+    return new NextResponse('accepted', { status: 200 });
+  }
+
+  // 3) Idempotency — store-or-skip on event.id (unique index)
+  try {
+    await db.webhookEvent.create({
+      data: { id: event.id, type: event.type, payload: event, status: 'pending' },
+    });
+  } catch (e) {
+    if (isUniqueViolation(e)) {
+      // Duplicate delivery — already accepted. Ack and move on.
+      return new NextResponse('duplicate', { status: 200 });
+    }
+    // DB down: signal the provider to retry (this IS our fault).
+    logger.error({ err: e, eventId: event.id }, 'webhook.persist_failed');
+    return new NextResponse('storage error', { status: 503 });
+  }
+
+  // 4) Hand off async. NEVER await business logic here.
+  //    Options, in order of preference:
+  //      (a) push to a queue (BullMQ, Inngest, QStash, SQS)
+  //      (b) Vercel: `waitUntil(processEvent(event))` — runs after response
+  //      (c) trigger an internal API call with `fetch(..., { keepalive: true })`
+  await queue.publish('webhook.received', { eventId: event.id });
+
+  // 5) Always 2xx if we got this far. Provider stops retrying.
+  return NextResponse.json({ received: true });
+}
+```
+
+### The Async Processor (separate from the receiver)
+
+The processor is where downstream calls happen. **It must absorb its own failures** — never let them bubble back into the HTTP receiver:
+
+```ts
+// jobs/process-webhook.ts
+import CircuitBreaker from 'opossum';
+
+const downstream = new CircuitBreaker(callDownstreamAPI, {
+  timeout: 5_000,
+  errorThresholdPercentage: 50,
+  resetTimeout: 30_000,
+});
+
+export async function processWebhook(eventId: string) {
+  const event = await db.webhookEvent.findUniqueOrThrow({ where: { id: eventId } });
+  if (event.status === 'processed') return; // re-entrancy safety
+
+  try {
+    await downstream.fire(event.payload);
+    await db.webhookEvent.update({
+      where: { id: eventId },
+      data: { status: 'processed', processedAt: new Date() },
+    });
+  } catch (err) {
+    // Mark for retry from OUR side (queue redelivery + backoff),
+    // NOT from the provider's side. Provider already got 2xx.
+    await db.webhookEvent.update({
+      where: { id: eventId },
+      data: {
+        status: 'failed',
+        attempts: { increment: 1 },
+        lastError: serializeError(err),
+      },
+    });
+    logger.error({ err, eventId }, 'webhook.process_failed');
+    throw err; // queue will backoff + retry per OUR policy
+  }
+}
+```
+
+See `error-handling` Pattern 5 for circuit breaker tuning and Pattern 4 for retry+backoff.
+
+### FORBIDDEN — Webhook Handlers
+
+| Anti-pattern | Why it's lethal |
+|---|---|
+| `await req.json()` before signature verification | Signature is computed on the raw body bytes; framework re-serialization breaks it. Also accepts unsigned traffic into your parser. |
+| Doing the business logic inline in the handler | Provider timeout (≤ 5–30 s) → they retry while you're still processing → duplicate writes. |
+| Returning `5xx` on downstream failures | Provider retries forever, queue floods, your downstream gets even more load. Ack 2xx, retry from your side. |
+| Returning `4xx` on parse / business errors | Same retry storm. Only `4xx` justified is `401` for bad signature. |
+| No idempotency key | First retry creates a duplicate user / duplicate charge / duplicate message. |
+| Logging the full payload | PII / secrets in logs. Log the event ID + type; redact `data.*`. |
+| One `/api/webhooks` for all providers | Each provider has its own signature scheme, secrets, retry policy. Isolate per-route (`/api/webhooks/[provider]`). |
+| Trusting `X-Forwarded-For` for provider IP allowlist | Use signature verification, not IP allowlisting. Provider IPs rotate. |
+
+### Pre-Commit Checklist (Webhook Routes)
+
+- [ ] Signature verified on the **raw body** before any parsing
+- [ ] `timingSafeEqual` used for signature comparison (no `===`)
+- [ ] Provider event ID stored with a unique index → idempotency
+- [ ] Handler returns 2xx within ~1 s on the success path
+- [ ] Business logic delegated to queue / `waitUntil` / background task
+- [ ] Downstream calls wrapped in circuit breaker + retry+backoff
+- [ ] Logs include `eventId` + `provider` + `type`; payload `data` redacted
+- [ ] Tested: duplicate delivery → 200 (no duplicate side-effect)
+- [ ] Tested: invalid signature → 401, never reaches the parser
+
 ## Metadata
 
 ```tsx
@@ -227,3 +444,7 @@ export async function createCheckout(priceId: string) {
 6. **`NEXT_PUBLIC_` with API keys, secrets, or tokens** — secrets leak to browser bundle
 7. **Calling external APIs from client components** — use Route Handlers as proxy
 8. **`process.env['SECRET']` in `'use client'` files** — only `NEXT_PUBLIC_*` vars work client-side
+9. **Mixing `[id]` / `[userId]` / `[someId]` as siblings of the same parent dir** — runtime crash; `next build` does NOT catch it. Run `bun run routes:check` (see "Dynamic Route Slug Consistency")
+10. **Webhook business logic inline in the Route Handler** — ack 2xx fast, process async (see "Webhook Handler — Critical Path")
+11. **Skipping signature verification or parsing JSON before verifying** — always verify the raw body first
+12. **Returning 5xx from a webhook on a downstream failure** — triggers provider retry storms; ack 2xx and retry from your side

package/stacks/nodejs/stack.json

@@ -20,7 +20,8 @@
     { "name": "TypeCheck", "command": "bun run typecheck", "required": true, "order": 1 },
     { "name": "Lint", "command": "bun run lint", "required": true, "order": 2 },
     { "name": "Tests", "command": "bun run test", "required": true, "order": 3 },
-    { "name": "Build", "command": "bun run build", "required": true, "order": 4 }
+    { "name": "RouteSlugs", "command": "node scripts/check-route-slugs.mjs", "required": true, "order": 4, "appliesTo": ["nextjs"], "description": "Static Next.js dynamic-route slug consistency check. `next build` does not catch this class of bug." },
+    { "name": "Build", "command": "bun run build", "required": true, "order": 5 }
   ],
   "frameworks": [
     {

package/stacks/nodejs/workflows/ci.yml

@@ -35,6 +35,17 @@ jobs:
       - name: Unit tests
         run: bun run test
 
+      - name: Next.js route slug consistency
+        # `next build` does NOT catch mismatched dynamic-segment names
+        # (e.g. mixing [id] and [userId] under the same parent). This
+        # script catches it statically before build, in milliseconds.
+        # Skips with exit 2 on non-Next.js repos (treated as success here).
+        run: |
+          if [ -f scripts/check-route-slugs.mjs ]; then
+            node scripts/check-route-slugs.mjs || code=$?
+            if [ "${code:-0}" = "1" ]; then exit 1; fi
+          fi
+
       - name: Build
         run: bun run build