start-vibing-stacks 2.19.0 → 2.21.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.21.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,28 @@ 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
+node scripts/check-build-scripts.mjs       # No dev-only tools in deploy scripts
+bun run build                              # Build verification (must come AFTER both checks)
 ```
 
+> **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".
+
+> **Vercel/Docker deploy note.** Build environments strip `devDependencies`
+> (`NODE_ENV=production` → `npm install --omit=dev`). Any binary called
+> from `scripts.build` / `prebuild` / `postinstall` that's only in
+> `devDependencies` (e.g. `tsx`, `ts-node`, `vitest`) will crash the
+> deploy with `command not found / exit 127`. `check-build-scripts.mjs`
+> catches this statically — see `nextjs-app-router` skill, section
+> "Build Script Hygiene".
+
 ## Gate Results
 
 | Result | Action |

package/stacks/nodejs/scripts/check-build-scripts.mjs

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * check-build-scripts.mjs
+ *
+ * Static validator for package.json#scripts that run at deploy time.
+ *
+ * Catches the "tsx: command not found / Error: Command 'npm run build'
+ * exited with 127" class of bug, which appears on Vercel, Docker
+ * (`npm ci --omit=dev`), and any CI that runs with `NODE_ENV=production`.
+ *
+ * Rule: any binary invoked from `build`, `prebuild`, `postbuild`,
+ * `start`, `postinstall`, `prepare`, or `prepublishOnly` MUST be one of:
+ *   - a Node-builtin (`node`, plain shell)
+ *   - prefixed with `npx` / `bunx` / `pnpm exec`
+ *   - the package's own `bin` entry
+ *   - present in `dependencies` (NOT just `devDependencies`)
+ *   - a plain-Node script: `node scripts/foo.mjs`
+ *
+ * Usage:
+ *   node scripts/check-build-scripts.mjs            # auto-detect ./package.json
+ *   node scripts/check-build-scripts.mjs ./pkg/dir  # explicit dir
+ *
+ * Exit codes:
+ *   0  OK
+ *   1  dev-only tool referenced from a deploy-time script
+ *   2  no package.json found (skipped)
+ */
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+
+// Scripts that run during install/build on Vercel, Docker, npm publish, etc.
+// `postinstall` runs even with `--omit=dev`, so its commands MUST resolve from prod deps.
+const DEPLOY_TIME_SCRIPTS = [
+  'build',
+  'prebuild',
+  'postbuild',
+  'start',
+  'postinstall',
+  'prepare',
+  'prepublishOnly',
+];
+
+// Tools that are conventionally dev-only. If the script invokes one of these
+// directly (without `npx`/`bunx`) AND it's not in `dependencies`, that's the bug.
+const DEV_ONLY_TOOLS = new Set([
+  'tsx',
+  'ts-node',
+  'tsc',
+  'typescript',
+  'vitest',
+  'jest',
+  'mocha',
+  'ava',
+  'tap',
+  'eslint',
+  'prettier',
+  'biome',
+  'rome',
+  'tsup',
+  'esbuild',
+  'rollup',
+  'webpack',
+  'rspack',
+  'parcel',
+  'tailwindcss',
+  'postcss',
+  'sass',
+  'less',
+  'concurrently',
+  'nodemon',
+  'pm2',
+]);
+
+// Tokens that are NEVER a binary invocation (control flow, shell built-ins, etc.)
+const NON_BINARY_TOKENS = new Set([
+  '&&',
+  '||',
+  ';',
+  '|',
+  '&',
+  '>',
+  '<',
+  '>>',
+  '<<',
+  '!',
+  '$',
+  '(',
+  ')',
+  '{',
+  '}',
+  'if',
+  'then',
+  'else',
+  'fi',
+  'for',
+  'do',
+  'done',
+  'while',
+  'case',
+  'esac',
+  'cd',
+  'echo',
+  'export',
+  'true',
+  'false',
+  'cat',
+  'rm',
+  'cp',
+  'mv',
+  'mkdir',
+  'test',
+  'sh',
+  'bash',
+  'zsh',
+  'set',
+]);
+
+// Wrapper commands that defer to a separate binary (their first arg is the actual tool,
+// which we want to evaluate against the same rules).
+const WRAPPERS = new Set(['npx', 'bunx', 'pnpm', 'yarn', 'cross-env', 'env']);
+
+/**
+ * Strip shell quoting and split a command line into bare tokens.
+ * Naive but adequate for typical package.json scripts.
+ */
+function tokenize(line) {
+  const out = [];
+  let cur = '';
+  let quote = null;
+  for (const ch of line) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (cur) {
+        out.push(cur);
+        cur = '';
+      }
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/**
+ * Walk a script command and return the list of "first-binary" tokens that
+ * would actually be invoked. Handles `&&`, `||`, `;`, and a small set of
+ * wrappers (npx, bunx, cross-env).
+ *
+ * Returns Array<{ binary: string, prefixedByWrapper: boolean }>
+ */
+function extractInvocations(command) {
+  const tokens = tokenize(command);
+  const invocations = [];
+
+  let expectBinary = true; // start of a sub-command
+  let wrapperPrefix = false;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+
+    if (t === '&&' || t === '||' || t === ';' || t === '|') {
+      expectBinary = true;
+      wrapperPrefix = false;
+      continue;
+    }
+
+    // Skip env-var assignments like FOO=bar baz
+    if (expectBinary && /^[A-Z_][A-Z0-9_]*=/.test(t)) {
+      continue;
+    }
+
+    if (!expectBinary) continue;
+
+    // Wrappers: their "real" binary is the next token
+    if (WRAPPERS.has(t)) {
+      wrapperPrefix = true;
+      // for `pnpm exec` / `pnpm run` style, eat the sub-word
+      if (t === 'pnpm' && tokens[i + 1] === 'exec') {
+        i++;
+        continue;
+      }
+      if (t === 'yarn' && tokens[i + 1] === 'dlx') {
+        i++;
+        continue;
+      }
+      // for `cross-env FOO=bar baz` we need to skip env assignments too
+      if (t === 'cross-env' || t === 'env') {
+        let j = i + 1;
+        while (j < tokens.length && /^[A-Z_][A-Z0-9_]*=/.test(tokens[j])) j++;
+        if (j < tokens.length) {
+          invocations.push({ binary: tokens[j], prefixedByWrapper: false });
+        }
+        i = j;
+        expectBinary = false;
+        wrapperPrefix = false;
+        continue;
+      }
+      continue;
+    }
+
+    if (NON_BINARY_TOKENS.has(t)) {
+      // Don't reset expectBinary for stuff like `echo`; treat as inert
+      continue;
+    }
+
+    invocations.push({ binary: t, prefixedByWrapper: wrapperPrefix });
+    expectBinary = false;
+    wrapperPrefix = false;
+  }
+
+  return invocations;
+}
+
+/**
+ * Returns true if the binary is "safe" — Node-builtin invocation, or
+ * resolves from prod dependencies (or the package's own bin).
+ */
+function isSafe(binary, prefixedByWrapper, ctx) {
+  if (prefixedByWrapper) return true;
+  if (binary === 'node') return true;
+  // Direct script: `./scripts/x.sh`, `node ./scripts/x.mjs` — wrapped above
+  if (binary.startsWith('./') || binary.startsWith('/')) return true;
+  // Module via `node --import`: `node scripts/foo.mjs` is already handled above
+
+  // Package's own bin
+  if (ctx.ownBins.has(binary)) return true;
+
+  // Prod dep (the package itself may install a bin)
+  if (ctx.prodDeps.has(binary)) return true;
+
+  // Subpackages of a prod dep (rare but valid: `next-bundle-analyzer` → `next` group)
+  // — handled by direct match above for typical cases.
+
+  // Some prod deps install differently-named bins (e.g. `typescript` → `tsc`).
+  // We can't statically know these without crawling node_modules, so the
+  // heuristic falls back on the DEV_ONLY_TOOLS deny-list for the well-known
+  // offenders.
+  return !DEV_ONLY_TOOLS.has(binary);
+}
+
+async function readJSON(path) {
+  const raw = await readFile(path, 'utf8');
+  return JSON.parse(raw);
+}
+
+async function detectRoot(args) {
+  if (args.length > 0) return resolve(args[0]);
+  return process.cwd();
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const root = await detectRoot(args);
+  const pkgPath = join(root, 'package.json');
+
+  if (!existsSync(pkgPath)) {
+    console.log('[build-scripts] no package.json found — skipped.');
+    process.exit(2);
+  }
+
+  const pkg = await readJSON(pkgPath);
+  const scripts = pkg.scripts ?? {};
+  const prodDeps = new Set(Object.keys(pkg.dependencies ?? {}));
+  const devDeps = new Set(Object.keys(pkg.devDependencies ?? {}));
+  const ownBins = new Set(
+    typeof pkg.bin === 'string' ? [pkg.name] : Object.keys(pkg.bin ?? {})
+  );
+  const ctx = { prodDeps, devDeps, ownBins };
+
+  const findings = [];
+
+  for (const scriptName of DEPLOY_TIME_SCRIPTS) {
+    const cmd = scripts[scriptName];
+    if (!cmd) continue;
+
+    const invocations = extractInvocations(cmd);
+    for (const inv of invocations) {
+      if (isSafe(inv.binary, inv.prefixedByWrapper, ctx)) continue;
+      const inDev = devDeps.has(inv.binary);
+      findings.push({
+        script: scriptName,
+        command: cmd,
+        binary: inv.binary,
+        inDev,
+      });
+    }
+  }
+
+  if (findings.length > 0) {
+    console.error('');
+    console.error('  BUILD SCRIPT HYGIENE FAILURE (deploy will crash with exit 127)');
+    console.error('  ' + '─'.repeat(60));
+    console.error('');
+    console.error(
+      '  These deploy-time scripts call a binary that will not be'
+    );
+    console.error(
+      '  available on Vercel/Docker (NODE_ENV=production strips devDeps).'
+    );
+    console.error('');
+    for (const f of findings) {
+      console.error(`  scripts.${f.script}  →  ${f.command}`);
+      console.error(`    missing binary: "${f.binary}"`);
+      if (f.inDev) {
+        console.error(
+          `    → "${f.binary}" is in devDependencies; deploy install omits devDeps`
+        );
+      } else {
+        console.error(
+          `    → "${f.binary}" is not in dependencies and not a known wrapper`
+        );
+      }
+      console.error('');
+    }
+    console.error('  Fix (in order of preference):');
+    console.error(
+      '    1. Convert any TS helper to .mjs and call via `node scripts/x.mjs`'
+    );
+    console.error(
+      '    2. Move the tool to `dependencies` if it is genuinely needed at runtime'
+    );
+    console.error(
+      '    3. Prefix with `npx`/`bunx` (slower, network-dependent)'
+    );
+    console.error(
+      '    4. As LAST RESORT, set Vercel `installCommand: "npm install --include=dev"`'
+    );
+    console.error('');
+    process.exit(1);
+  }
+
+  const pkgRel = relative(process.cwd(), pkgPath) || 'package.json';
+  console.log(`[build-scripts] OK — no dev-only tools in deploy-time scripts (${pkgRel})`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[build-scripts] script failed:', err);
+  process.exit(1);
+});

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/bun-runtime/SKILL.md

@@ -1,12 +1,32 @@
 ---
 name: bun-runtime
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Bun Runtime — Fast JavaScript Runtime
 
 **ALWAYS invoke when using Bun for scripts, packages, bundling, or testing.**
 
+## Deploy-Time Asymmetry (READ FIRST)
+
+> Bun's local install is generous (installs ALL deps by default). Vercel /
+> CI builds are strict (`NODE_ENV=production` → devDeps stripped). A
+> `package.json#scripts.build` that calls `tsx`, `ts-node`, `vitest`,
+> `eslint`, or `tsc` directly will work locally and fail at deploy with
+> `sh: line 1: <tool>: command not found / Error: Command "npm run build"
+> exited with 127`.
+
+**Rule.** Anything invoked from `scripts.build` / `prebuild` /
+`postinstall` / `prepare` must be either:
+
+- in `dependencies` (not `devDependencies`)
+- prefixed with `bunx` / `npx` (slower, fragile)
+- a plain Node script: `node scripts/foo.mjs`
+
+For one-off utilities the `.mjs` route is best — see
+`nextjs-app-router` skill, section "Build Script Hygiene". The stack
+ships `scripts/check-build-scripts.mjs` to catch this statically.
+
 ## Package Management
 
 ```bash

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

@@ -1,6 +1,6 @@
 ---
 name: nextjs-app-router
-version: 1.0.0
+version: 1.2.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,293 @@ 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
+
+---
+
+## Build Script Hygiene (Vercel / CI — silent deploy killer)
+
+> **Vercel sets `NODE_ENV=production` during deploy**, which causes `npm
+> install` to **omit `devDependencies`**. Any binary your `build` /
+> `prebuild` / `postinstall` script invokes must be resolvable from
+> `dependencies` (or `node_modules/.bin` shipped via a prod dep) —
+> otherwise you get `sh: line 1: <tool>: command not found` and
+> `Error: Command "npm run build" exited with 127` at deploy time, even
+> though `bun run build` worked locally.
+
+This is **not** a Next.js bug. Same trap exists on Vercel Functions,
+Netlify, Cloudflare Pages, Railway, Render, Fly.io, AWS Amplify, Docker
+multi-stage builds, and any CI runner that respects `NODE_ENV` or runs
+`npm ci --omit=dev`.
+
+### Common Offenders (devDep tools invoked from `scripts`)
+
+| Tool | Typical wrong usage | Why it breaks |
+|---|---|---|
+| `tsx` | `"build": "tsx scripts/seed.ts && next build"` | `tsx` is dev-only; not installed on Vercel |
+| `ts-node` | `"prebuild": "ts-node ./gen.ts"` | Same — `ts-node` rarely in `dependencies` |
+| `tsc` | `"prebuild": "tsc -p tsconfig.gen.json"` | `typescript` is conventionally a devDep |
+| `vitest` / `jest` | `"prebuild": "vitest run"` | Test runners are dev-only |
+| `eslint` / `prettier` / `biome` | `"build": "eslint . && next build"` | Linters are dev-only |
+| `tailwindcss` (CLI) | `"build": "tailwindcss -i ... && next build"` | Next.js handles Tailwind via its compiler; the standalone CLI is dev-only |
+| `prisma` | `"postinstall": "prisma generate"` | **OK** only if `prisma` is in `dependencies` (it should be) — generation needs the CLI on every install |
+
+### The Rule
+
+Anything referenced in `scripts.build`, `scripts.prebuild`,
+`scripts.postbuild`, `scripts.start`, `scripts.postinstall`,
+`scripts.prepare`, `scripts.prepublishOnly` must be one of:
+
+1. A Node-builtin (`node`, plain shell)
+2. Prefixed with `npx` / `bunx` / `pnpm exec` (downloads on demand — slow, fragile)
+3. The package's own `bin` entry
+4. Present in `dependencies` (not just `devDependencies`)
+5. A plain-Node script: `node scripts/foo.mjs` (zero deps; works everywhere)
+
+### Fix Vectors (in order of preference)
+
+#### 1. Convert TS scripts to zero-dep `.mjs` (BEST for tiny utilities)
+
+```jsonc
+// BEFORE — fails on Vercel
+{ "scripts": { "prebuild": "tsx scripts/check-routes.ts" } }
+
+// AFTER — works everywhere, no devDep needed
+{ "scripts": { "prebuild": "node scripts/check-routes.mjs" } }
+```
+
+Use modern Node features (`node:fs/promises`, top-level `await`,
+`import.meta`). Bun, Node 20+, and every CI runner support `.mjs`
+natively.
+
+#### 2. Move the tool to `dependencies` (when you genuinely need the runtime tool)
+
+```bash
+# Prisma client generation — needs the CLI on every install
+bun remove -D prisma
+bun add prisma
+```
+
+Costs: larger node_modules in prod. Acceptable for runtime-needed CLIs
+(`prisma`, sometimes `tsx` if you have many TS scripts).
+
+#### 3. Configure Vercel to install devDeps (LAST RESORT — global override)
+
+```jsonc
+// vercel.json
+{ "installCommand": "npm install --include=dev" }
+```
+
+This **doubles** the install size for every deploy. Only use when you
+have a real TypeScript build pipeline that can't be migrated to `.mjs`.
+
+#### 4. Compile TS scripts ahead of time (advanced)
+
+Bundle TS utilities to `.js` with `tsup`/`esbuild` during dev, commit
+the output, run the `.js` in build. Useful for big script suites; for
+one-off utilities the `.mjs` approach is simpler.
+
+### Why "It Works on My Machine"
+
+| Environment | Behavior |
+|---|---|
+| Local `bun install` | Installs ALL deps by default (including devDeps) |
+| Local `bun run build` | `node_modules/.bin/tsx` exists → succeeds |
+| Local `npm install` (no flags) | Installs ALL deps (devDeps included unless `NODE_ENV=production`) |
+| Vercel build step | Runs with `NODE_ENV=production` → devDeps **stripped** → `tsx` missing |
+| Docker `FROM node:20` + `npm ci --omit=dev` | Same as Vercel |
+| GitHub Actions default | Installs ALL deps unless workflow explicitly sets `NODE_ENV=production` |
+
+The asymmetry is the trap. Local dev and CI accidentally agree; deploy
+disagrees. Catch it statically.
+
+### Static Check (CI gate — mandatory)
+
+The stack ships `scripts/check-build-scripts.mjs` (zero deps). It parses
+`package.json`, walks every deploy-time script (`build`, `prebuild`,
+`postbuild`, `start`, `postinstall`, `prepare`, `prepublishOnly`),
+tokenises the command, and flags any token that is:
+
+- A known dev-only tool name (`tsx`, `ts-node`, `vitest`, `eslint`, ...)
+- AND not prefixed with `npx`/`bunx`/`pnpm exec`/`node`
+- AND not present in `dependencies`
+
+Wire it as `prebuild` AND in CI:
+
+```jsonc
+{
+  "scripts": {
+    "routes:check": "node scripts/check-route-slugs.mjs",
+    "build:check":  "node scripts/check-build-scripts.mjs",
+    "prebuild":     "bun run routes:check && bun run build:check",
+    "build":        "next build"
+  }
+}
+```
+
+### Stack-shipped Scripts MUST Be `.mjs`
+
+When this stack scaffolds a helper script (`check-route-slugs.mjs`,
+`check-build-scripts.mjs`, anything in `scripts/`), it is **always**
+plain `.mjs` runnable via `node`. **Never** use `.ts` requiring `tsx`
+or `ts-node`. The whole point of these scripts is to run during
+build — they have to work on Vercel.
+
+### Pre-Commit Checklist (Build Scripts)
+
+- [ ] `package.json#scripts.build` has no `tsx` / `ts-node` / dev-only CLI
+- [ ] `package.json#scripts.prebuild` (if any) is also clean
+- [ ] `package.json#scripts.postinstall` (runs on Vercel during install) is also clean
+- [ ] Any helper script in `scripts/` is `.mjs`, runnable via plain `node`
+- [ ] If a runtime tool is genuinely needed (e.g. `prisma generate`), it lives in `dependencies`, not `devDependencies`
+- [ ] Tested with `NODE_ENV=production npm ci && npm run build` locally before deploy
+
+---
+
 ## Metadata
 
 ```tsx
@@ -227,3 +585,9 @@ 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
+13. **Calling `tsx` / `ts-node` / `vitest` / `eslint` directly from `scripts.build` or `scripts.prebuild`** — Vercel strips devDeps; build fails with exit 127. Convert to `.mjs` or move to `dependencies` (see "Build Script Hygiene")
+14. **Shipping helper scripts as `.ts`** — they cannot run on Vercel without `tsx` in `dependencies`. Use `.mjs` and plain `node`

package/stacks/nodejs/stack.json

@@ -20,7 +20,9 @@
     { "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": "BuildScripts", "command": "node scripts/check-build-scripts.mjs", "required": true, "order": 5, "description": "Static check that scripts.build/prebuild/postinstall do not call dev-only binaries (tsx, ts-node, vitest, eslint, ...) — Vercel/Docker strip devDeps and the build crashes with exit 127." },
+    { "name": "Build", "command": "bun run build", "required": true, "order": 6 }
   ],
   "frameworks": [
     {

package/stacks/nodejs/workflows/ci.yml

@@ -35,6 +35,28 @@ 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-script hygiene (no devDeps in deploy scripts)
+        # Vercel/Docker strip devDependencies during install. Any binary
+        # invoked from build/prebuild/postinstall MUST be in dependencies
+        # or be a plain `node script.mjs` call. Catches the
+        # "tsx: command not found / exited 127" class of bug.
+        run: |
+          if [ -f scripts/check-build-scripts.mjs ]; then
+            node scripts/check-build-scripts.mjs || code=$?
+            if [ "${code:-0}" = "1" ]; then exit 1; fi
+          fi
+
       - name: Build
         run: bun run build