start-vibing-stacks 2.20.0 → 2.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.20.0",
+  "version": "2.22.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/debugging-patterns/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: debugging-patterns
-version: 1.0.0
+version: 1.1.0
+description: Universal debugging strategies plus the "Bundle, not Backend"
+  triage for silent wrong-component renders (HTTP 200, empty server logs,
+  wrong default export shipped). Pairs with `inertia-react` "Vite Build
+  Gotchas" section.
 ---
 
 # Debugging Patterns
@@ -34,6 +38,72 @@ node --inspect script.js
 DEBUG=* node script.js
 ```
 
+## Bundle, not Backend (silent wrong-component / wrong-output renders)
+
+> **When the server returns HTTP 200, server logs are empty, and the browser
+> still renders the wrong content — STOP debugging the server.** The bug is
+> in the bundle. This is the #1 source of "Sonnet runs in circles for 90
+> minutes" debugging sessions.
+
+### Symptoms that point to the bundle, not the server
+
+| Symptom | Why it implicates the bundle |
+|---|---|
+| HTTP 200 on every request, browser shows wrong content | Server is producing correct payload; client is misresolving it |
+| Empty server logs (Laravel/Node/Python) | No exception was thrown; backend is genuinely correct |
+| The wrong component/page/template is rendered | Default export of the loaded chunk is not the expected one |
+| Reverting the last `vite.config.js` / `webpack.config.js` / `rollup.config.js` change fixes it | Build graph is the locus |
+| Only happens after `npm run build` (dev works) | Production chunking heuristics differ from dev's per-file modules |
+| Different routes resolve to the same JS asset URL | Resolve-map collision in `import.meta.glob` / module federation |
+
+### Triage protocol (5 steps, ~3 minutes)
+
+1. **Confirm the payload** — DevTools → Network → click the HTML/XHR request
+   for the broken route → inspect the response. If the server-side identifier
+   (`component:` for Inertia, route name for Next.js RSC, etc.) is the EXPECTED
+   one, the server is correct. Move to step 2.
+2. **Find the JS chunk that loaded** — in the same Network tab, look at the
+   `.js` requests that fired after the page request. For SPA frameworks, one
+   of them is the page chunk. Note its URL/hash.
+3. **Inspect the chunk's `default` export** — open the chunk URL in a new tab,
+   `Ctrl+F` for `default:` / `export{` / `as default}`. Identify the actual
+   component name being exported.
+4. **Compare** — if (chunk's default export) ≠ (server's component identifier),
+   confirmed: the bug is in the bundle. Possible causes (in order of likelihood):
+   - `manualChunks` collided with an `entry` chunk (Rollup/Rolldown silently
+     dropped a group — see `inertia-react §Vite Build Gotchas`)
+   - Two files with the same default export name caused a hash reuse
+   - A barrel/re-export chain has the wrong file at the top
+   - Tree-shaking removed the expected export because it was only referenced
+     conditionally
+5. **Bisect on the build config** — revert the last commit that touched
+   `vite.config.*`, `rollup.config.*`, `webpack.config.*`, `next.config.*`,
+   `turbo.json`, or any chunking-related setting. If the bug disappears,
+   you've located it. Do NOT debug the server.
+
+### Common causes (multi-stack)
+
+| Stack | Pattern | Fix reference |
+|---|---|---|
+| Laravel + Inertia + Vite | Same module in `laravel.input[]` AND `Pages/**` glob | `inertia-react §Vite Build Gotchas` |
+| Next.js App Router | Server/Client component boundary mis-resolved by bundler split | Check `'use client'` placement, then `next.config.mjs` |
+| Module Federation | Remote chunk hash mismatch after redeploy | Force remote re-fetch, check `shared` deps versions |
+| Webpack 5 | `splitChunks.cacheGroups` overlap with `entry` | Same class of bug as Vite manualChunks |
+| esbuild | Two CJS modules with same `module.exports.default` deduped | Set `format: 'esm'` or use named exports |
+
+### Validators that catch the bug at build time
+
+If a `scripts/check-vite-manifest.mjs` exists in the project (shipped by
+`start-vibing-stacks` for PHP/Laravel projects), run it after every build:
+
+```bash
+node scripts/check-vite-manifest.mjs
+```
+
+It cross-references `laravel.input[]` against `import.meta.glob` patterns and
+fails the build if any module appears in both — which is the Laravel/Inertia
+specific shape of "Bundle, not Backend."
+
 ## Anti-Patterns
 
 | Don't | Do |
@@ -42,3 +112,6 @@ DEBUG=* node script.js
 | Fix symptom, not cause | Trace to root cause |
 | Skip writing test for fix | Always add regression test |
 | Leave debug code in commit | Clean before commit |
+| Debug the server when HTTP 200 + empty logs + wrong content | Triage as "Bundle, not Backend" — start from the chunk graph |
+| Trust that `manualChunks` / `splitChunks` always honors your grouping | Bundlers silently drop groups when they collide with entry chunks |
+| Move on after one `npm run build` succeeded | Run the manifest validator; bundlers don't warn on collision |

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

@@ -28,7 +28,8 @@ 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)
+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
@@ -37,6 +38,14 @@ bun run build                              # Build verification (must come AFTER
 > 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/frontend/react-inertia/skills/inertia-react/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: inertia-react
-version: 2.0.0
+version: 2.1.0
 description: LEGACY skill — Inertia.js + React frontend integration with
   Laravel-rendered pages. Use ONLY in pre-existing Inertia projects. For NEW
   projects use the `react-api` frontend stack (`axios-laravel-api` +
-  `react-api-standards`) which decouples render from data fetching.
+  `react-api-standards`) which decouples render from data fetching. v2.1.0 adds
+  the "Vite Build Gotchas" section covering the `manualChunks` × entry-chunk
+  × `resolvePageComponent` glob interaction that produces silent
+  wrong-component renders (production post-mortem 2026-05).
 ---
 
 # Inertia.js + React Integration (LEGACY)
@@ -343,6 +346,138 @@ router.reload({ only: ['stats'] }); // Partial reload
 - Access shared props via `usePage().props`
 - `processing` boolean from `useForm` for button loading states
 
+## Vite Build Gotchas (Inertia-specific)
+
+> **Production post-mortem 2026-05.** Reverting/rebuilding `vite.config.js`
+> chunking in an Inertia + Laravel project can produce a **silent wrong-component
+> render** (Login renders HttpErrorPage with HTTP 200, no console errors, empty
+> Laravel logs). The bug lives in the bundle graph, not the server.
+
+### The three-way collision
+
+```
+laravel-vite-plugin       ┐
+  laravel({ input: [      │  Anything here becomes an ENTRY chunk.
+    '.../HttpErrorPage'   │  Rollup/Rolldown ALWAYS prioritizes entries.
+  ]})                     ┘
+
+@inertiajs/react          ┐
+  resolvePageComponent(   │  Builds a STATIC resolve-map at build time
+    `./Pages/${name}.jsx`,│  via import.meta.glob. The map points each
+    import.meta.glob(     │  Page path to whatever chunk hash Rollup
+      './Pages/**/*.jsx') │  ended up putting that module in.
+  )                       ┘
+
+build.rollupOptions       ┐
+  .manualChunks(id) {     │  This is ADVISORY. Returning 'pages-auth' for
+    if (/Auth\//.test(id))│  a module that is ALSO an entry has NO EFFECT.
+      return 'pages-auth' │  The grouping is silently dropped — no warning.
+  }                       ┘
+```
+
+When the same module (e.g. `HttpErrorPage.jsx`) is:
+
+1. listed in `laravel.input[]` (because `app.blade.php` has a direct
+   `@vite('resources/js/Pages/.../HttpErrorPage.jsx')` for the error layout), AND
+2. caught by `manualChunks` returning `'pages-auth'`,
+
+…Rollup/Rolldown creates a **standalone entry chunk** containing ONLY
+`HttpErrorPage`. The `pages-auth` group is reduced to that one module, and the
+`import.meta.glob` resolve-map points **every sibling** (`Login`, `Register`,
+`ForgotPassword`, …) at that same chunk hash. The siblings' code is discarded.
+
+Symptom: `Inertia::render('Auth/Login', …)` returns 200 OK with a valid Inertia
+payload. The browser fetches the chunk listed in the resolve-map. That chunk's
+`default` export is `HttpErrorPage`. The error page is rendered. Backend is
+perfect; frontend lies.
+
+### Rule 1 — Never duplicate a module between `laravel.input` and the glob
+
+If a page MUST be referenced directly by `@vite()` in a blade file (typical
+cases: error pages, mail templates rendered server-side, OG/share-image
+renderers), it becomes an entry chunk. You have two options:
+
+- **A. Exclude it from the glob** — change `resolvePageComponent`'s glob to
+  ignore that path, OR
+- **B. Short-circuit `manualChunks` BEFORE any grouping rule** so the entry
+  chunk's identity is preserved without polluting a group.
+
+Pattern B (preferred — works without touching the Inertia bootstrap):
+
+```js
+// vite.config.js
+build: {
+    rollupOptions: {
+        output: {
+            manualChunks(id) {
+                if (!id.includes('/resources/js/Pages/')) return;
+
+                // Entry chunks referenced directly by @vite() in blade MUST
+                // return undefined here — BEFORE any grouping rule.
+                // Otherwise the group is collapsed into the entry and the
+                // import.meta.glob resolve-map points siblings at the wrong
+                // chunk hash. See "Vite Build Gotchas" in inertia-react skill.
+                if (id.includes('/Pages/OtherPages/HttpErrorPage')) return;
+
+                if (id.includes('/Pages/Auth/') || id.includes('/Pages/OtherPages/')) {
+                    return 'pages-auth';
+                }
+                if (id.includes('/Pages/Dashboard/')) {
+                    return 'pages-dashboard';
+                }
+            },
+        },
+    },
+},
+```
+
+### Rule 2 — `manualChunks` is advisory; entries always win
+
+There is no warning when Rollup/Rolldown ignores a `manualChunks` return value
+for an entry module. The validation MUST be done out-of-band on `manifest.json`
+after every build (see `scripts/check-vite-manifest.mjs` shipped by
+`start-vibing-stacks`).
+
+### Rule 3 — Validate `public/build/manifest.json` after every `vite build`
+
+```bash
+# 1. Quick eyeball
+cat public/build/manifest.json | jq 'keys'
+
+# 2. Automated (shipped script)
+node scripts/check-vite-manifest.mjs public/build/manifest.json vite.config.js
+```
+
+The script cross-references `laravel.input[]` against the `Pages/**` glob and
+fails (non-zero exit) on any collision.
+
+### Rule 4 — Smoke-test after any `vite.config.js` change touching `build`
+
+Three-step browser check for one critical route per page group:
+
+1. DevTools → Network → click the Inertia XHR → read the `component:` field
+   in the JSON response.
+2. Click the JS asset request that followed → open the resolved chunk URL.
+3. Search for `default:` / `export{ ... as default}` in that chunk. The
+   component name MUST match the server's `component:`.
+
+If they don't match, the bug is in the chunk graph. Revert the last
+`vite.config.js` change before debugging anything else.
+
+### Why Sonnet (and humans) get stuck on this class of bug
+
+| Layer | What it looks like | Why it misleads |
+|---|---|---|
+| Laravel logs | Empty | Backend is genuinely correct |
+| `manifest.json` | Valid, every input has an entry | Manifest doesn't enforce uniqueness across groups |
+| Browser network tab | 200 OK on every request | The wrong JS arrives successfully |
+| Console | Clean | The rendered component is valid React |
+
+Triage rule of thumb: **when wrong-component render happens with HTTP 200 and
+empty server logs, the bug is in the bundle. Start from the chunk graph, not
+from Laravel.** This is captured as the "Bundle, not Backend" pattern in
+`debugging-patterns`.
+
 ## Forbidden Patterns
 
 | Pattern | Reason | Use Instead |
@@ -354,3 +489,6 @@ router.reload({ only: ['stats'] }); // Partial reload
 | `window.location` for navigation | Full page reload | `router.visit()` |
 | `Inertia::render()` after POST | Breaks Inertia protocol | `redirect()->route()` |
 | Loading all translations globally | Performance waste | On-demand per page route |
+| Same module in `laravel.input[]` AND `Pages/**` glob | Rollup collapses the manual chunk group into the entry; resolve-map points siblings at the wrong chunk (silent wrong-component render) | Short-circuit `manualChunks` with early `return undefined` for entry pages |
+| `manualChunks` grouping pages without running `check-vite-manifest.mjs` | Grouping is advisory and silently ignored for entry chunks | Always run the validator after touching `build.rollupOptions` |
+| Trusting empty Laravel logs as "no bug" | Server can be 100% correct while the bundle ships the wrong default export | Use the "Bundle, not Backend" triage in `debugging-patterns` |

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/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.1.0
+version: 1.2.0
 ---
 
 # Next.js App Router — Modern Patterns
@@ -323,6 +323,147 @@ See `error-handling` Pattern 5 for circuit breaker tuning and Pattern 4 for retr
 - [ ] 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
@@ -448,3 +589,5 @@ export async function createCheckout(priceId: string) {
 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

@@ -21,7 +21,8 @@
     { "name": "Lint", "command": "bun run lint", "required": true, "order": 2 },
     { "name": "Tests", "command": "bun run test", "required": true, "order": 3 },
     { "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 }
+    { "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

@@ -46,6 +46,17 @@ jobs:
             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
 

package/stacks/php/scripts/check-vite-manifest.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+/**
+ * check-vite-manifest.mjs
+ *
+ * Static validator for Vite + laravel-vite-plugin builds that catches the
+ * "entry chunk collides with manualChunks group" bug in Inertia/React apps.
+ *
+ * Production post-mortem 2026-05: a `vite.config.js` "perf" change added
+ *   manualChunks(id) { if (/Auth\//.test(id)) return 'pages-auth' }
+ * while `laravel.input[]` already listed `Pages/.../HttpErrorPage.jsx`
+ * (referenced directly via `@vite()` in `app.blade.php` for the error layout).
+ * Rollup/Rolldown silently dropped the manualChunks group, kept only the
+ * entry, and the `import.meta.glob` resolve-map in `resolvePageComponent`
+ * ended up pointing every sibling page (Login, Register, ForgotPassword) at
+ * the same single-module entry chunk. Server sent `component: 'Auth/Login'`,
+ * browser rendered HttpErrorPage. HTTP 200. Empty Laravel logs.
+ *
+ * Rules enforced (all silent failures in Rollup/Rolldown by default):
+ *
+ *   R1. Every path in `laravel.input[]` MUST appear in `manifest.json` with
+ *       `isEntry: true`.
+ *   R2. Any `laravel.input[]` path that ALSO matches a `import.meta.glob`
+ *       pattern in the project's JS is a COLLISION. Either exclude it from
+ *       the glob, OR short-circuit `manualChunks` with an early
+ *       `return undefined` before grouping rules.
+ *   R3. Any file under `resources/js/Pages/` that appears as `isEntry: true`
+ *       in the manifest is suspect — entry pages must be inspected (they
+ *       collapse manualChunks groups). If the file is referenced direct via
+ *       `@vite()` in blade, document it; otherwise treat as a build leak.
+ *
+ * Usage:
+ *   node scripts/check-vite-manifest.mjs                     # auto-detect
+ *   node scripts/check-vite-manifest.mjs <manifest> <vite.config>
+ *
+ * Auto-detect order (when no args):
+ *   manifest:   public/build/manifest.json,
+ *               public/build/.vite/manifest.json
+ *   vite.config: vite.config.js, vite.config.mjs, vite.config.ts
+ *
+ * Exit codes:
+ *   0  OK (or no Vite/manifest found — skipped)
+ *   1  collision (entry × glob) detected
+ *   2  manifest missing an `isEntry: true` for a declared input
+ *   3  malformed input (could not parse vite.config or manifest)
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join, relative, dirname, basename } from 'node:path';
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+
+// ── Auto-detect paths ────────────────────────────────────────────────────
+const MANIFEST_CANDIDATES = [
+  'public/build/manifest.json',
+  'public/build/.vite/manifest.json',
+];
+const CONFIG_CANDIDATES = [
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.ts',
+];
+
+const manifestPath = args[0]
+  ? resolve(cwd, args[0])
+  : MANIFEST_CANDIDATES.map((p) => resolve(cwd, p)).find(existsSync);
+
+const configPath = args[1]
+  ? resolve(cwd, args[1])
+  : CONFIG_CANDIDATES.map((p) => resolve(cwd, p)).find(existsSync);
+
+if (!manifestPath) {
+  console.error(
+    '[check-vite-manifest] No manifest.json found. ' +
+      'Run `npm run build` first, then re-run this check.',
+  );
+  process.exit(0); // Skip silently if no build artifact yet.
+}
+
+if (!configPath) {
+  console.error(
+    '[check-vite-manifest] No vite.config.{js,mjs,ts} found. Skipping.',
+  );
+  process.exit(0);
+}
+
+// ── Load manifest ────────────────────────────────────────────────────────
+let manifest;
+try {
+  manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+} catch (e) {
+  console.error(
+    `[check-vite-manifest] Could not parse ${relative(cwd, manifestPath)}: ${e.message}`,
+  );
+  process.exit(3);
+}
+
+// ── Load vite.config ─────────────────────────────────────────────────────
+let configSrc;
+try {
+  configSrc = await readFile(configPath, 'utf8');
+} catch (e) {
+  console.error(`[check-vite-manifest] Could not read ${configPath}: ${e.message}`);
+  process.exit(3);
+}
+
+// ── Extract laravel({ input: [...] }) ────────────────────────────────────
+// Tolerant regex: matches `laravel({ ... input: [ '...', "..." ] ... })`
+// across multiple lines. Also catches the helper form
+// `laravel(['resources/css/app.css', 'resources/js/app.jsx'])`.
+function extractLaravelInputs(src) {
+  const inputs = new Set();
+
+  // Form A: laravel({ input: [...] })
+  const formA = /laravel\s*\(\s*\{[\s\S]*?input\s*:\s*\[([\s\S]*?)\][\s\S]*?\}\s*\)/g;
+  for (const m of src.matchAll(formA)) {
+    const arr = m[1];
+    for (const sm of arr.matchAll(/['"`]([^'"`]+)['"`]/g)) inputs.add(sm[1]);
+  }
+
+  // Form B: laravel([ ... ])  (shorthand)
+  const formB = /laravel\s*\(\s*\[([\s\S]*?)\]\s*\)/g;
+  for (const m of src.matchAll(formB)) {
+    const arr = m[1];
+    for (const sm of arr.matchAll(/['"`]([^'"`]+)['"`]/g)) inputs.add(sm[1]);
+  }
+
+  return [...inputs];
+}
+
+// ── Extract import.meta.glob patterns from JS sources ────────────────────
+// We scan the bootstrap entries listed in laravel.input plus any obvious
+// Inertia files (app.jsx, app.tsx, ssr.jsx, ssr.tsx, bootstrap.js) under
+// resources/js/.
+async function findInertiaGlobs(laravelInputs) {
+  const candidates = new Set();
+  for (const input of laravelInputs) {
+    if (/\.(jsx?|tsx?)$/.test(input)) candidates.add(input);
+  }
+  for (const f of ['app.jsx', 'app.tsx', 'ssr.jsx', 'ssr.tsx', 'bootstrap.js']) {
+    const p = `resources/js/${f}`;
+    if (existsSync(resolve(cwd, p))) candidates.add(p);
+  }
+
+  const patterns = [];
+  for (const rel of candidates) {
+    const abs = resolve(cwd, rel);
+    if (!existsSync(abs)) continue;
+    const src = await readFile(abs, 'utf8');
+
+    // resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx'))
+    // We just want every `import.meta.glob('...')` literal.
+    for (const m of src.matchAll(
+      /import\.meta\.glob\s*\(\s*\[?\s*['"`]([^'"`]+)['"`]/g,
+    )) {
+      patterns.push({ file: rel, pattern: m[1] });
+    }
+    // Multi-pattern form: import.meta.glob(['./Pages/**/*.jsx', './Other/**/*.jsx'])
+    const multi = /import\.meta\.glob\s*\(\s*\[([\s\S]*?)\]/g;
+    for (const m of src.matchAll(multi)) {
+      for (const sm of m[1].matchAll(/['"`]([^'"`]+)['"`]/g)) {
+        patterns.push({ file: rel, pattern: sm[1] });
+      }
+    }
+  }
+  return patterns;
+}
+
+// Convert a `import.meta.glob` pattern (relative to its host file) into an
+// absolute prefix + suffix matcher. Globs supported: `**`, `*`, and explicit
+// `{jsx,tsx,vue,svelte}` extension brace groups.
+function compileGlob(hostFile, pattern) {
+  const hostDir = dirname(resolve(cwd, hostFile));
+  // Resolve `./` and `../` segments against the host directory.
+  let absPattern = resolve(hostDir, pattern);
+  absPattern = absPattern.replace(/\\/g, '/'); // Windows safety
+
+  // Build a regex from the glob.
+  // Step 1: expand brace groups `{a,b,c}`.
+  const expandBraces = (str) => {
+    const m = str.match(/\{([^{}]+)\}/);
+    if (!m) return [str];
+    const opts = m[1].split(',');
+    const out = [];
+    for (const o of opts) {
+      out.push(...expandBraces(str.slice(0, m.index) + o + str.slice(m.index + m[0].length)));
+    }
+    return out;
+  };
+
+  // Step 2: convert each expansion into a regex.
+  const regexes = expandBraces(absPattern).map((expanded) => {
+    const reSrc = expanded
+      .replace(/[.+^$()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '__GLOBSTAR__')
+      .replace(/\*/g, '[^/]*')
+      .replace(/__GLOBSTAR__/g, '.*');
+    return new RegExp(`^${reSrc}$`);
+  });
+
+  return { pattern, hostFile, regexes };
+}
+
+function globMatches(compiled, absPath) {
+  const normalized = absPath.replace(/\\/g, '/');
+  return compiled.regexes.some((re) => re.test(normalized));
+}
+
+// ── Run validation ───────────────────────────────────────────────────────
+const laravelInputs = extractLaravelInputs(configSrc);
+if (laravelInputs.length === 0) {
+  console.error(
+    '[check-vite-manifest] Could not find laravel({ input: [...] }) in ' +
+      relative(cwd, configPath) +
+      '. Skipping (is this a Laravel + Vite project?).',
+  );
+  process.exit(0);
+}
+
+const errors = [];
+const warnings = [];
+
+// R1. Every laravel.input MUST be in the manifest as isEntry.
+for (const input of laravelInputs) {
+  const entry = manifest[input];
+  if (!entry) {
+    errors.push({
+      rule: 'R1',
+      msg: `Input "${input}" declared in laravel.input but absent from manifest. Did the build fail?`,
+    });
+    continue;
+  }
+  if (!entry.isEntry) {
+    errors.push({
+      rule: 'R1',
+      msg: `Input "${input}" present in manifest but NOT marked isEntry. Check laravel-vite-plugin version.`,
+    });
+  }
+}
+
+// R2 + R3. Cross-reference laravel.input against glob patterns.
+const globs = await findInertiaGlobs(laravelInputs);
+if (globs.length > 0) {
+  const compiledGlobs = globs.map((g) => compileGlob(g.file, g.pattern));
+
+  for (const input of laravelInputs) {
+    if (!/\.(jsx?|tsx?)$/.test(input)) continue; // skip CSS, etc.
+    const absInput = resolve(cwd, input);
+    for (const cg of compiledGlobs) {
+      if (globMatches(cg, absInput)) {
+        errors.push({
+          rule: 'R2',
+          msg:
+            `Collision: "${input}" is BOTH in laravel.input[] AND matched by ` +
+            `import.meta.glob("${cg.pattern}") in ${cg.hostFile}. ` +
+            `Rollup/Rolldown will silently collapse the manualChunks group ` +
+            `containing this module, leaving the glob resolve-map pointing ` +
+            `siblings at the wrong chunk hash. Either remove from ` +
+            `laravel.input[], exclude from the glob, or add early ` +
+            `\`return undefined\` for this module in manualChunks.`,
+        });
+      }
+    }
+  }
+}
+
+// R3. Pages/ files marked as isEntry that are NOT in laravel.input.
+// These mean someone added an entry chunk indirectly (e.g. dynamic import
+// promoted to entry by chunking heuristics) — worth flagging.
+const declaredInputSet = new Set(laravelInputs);
+for (const [key, entry] of Object.entries(manifest)) {
+  if (!entry.isEntry) continue;
+  if (declaredInputSet.has(key)) continue;
+  if (key.includes('resources/js/Pages/')) {
+    warnings.push({
+      rule: 'R3',
+      msg:
+        `Suspicious entry chunk: "${key}" is under Pages/ and marked ` +
+        `isEntry=true but NOT declared in laravel.input[]. This usually ` +
+        `means the bundler promoted it to entry to break a circular import ` +
+        `or because manualChunks excluded it. Verify the resolve-map of ` +
+        `import.meta.glob still points other pages at THIS chunk's siblings, ` +
+        `not at this chunk.`,
+    });
+  }
+}
+
+// ── Report ───────────────────────────────────────────────────────────────
+const tag = '[check-vite-manifest]';
+
+if (warnings.length > 0) {
+  for (const w of warnings) console.warn(`${tag} WARN  ${w.rule}: ${w.msg}`);
+}
+
+if (errors.length === 0) {
+  console.log(
+    `${tag} OK  ${laravelInputs.length} input(s), ${globs.length} glob(s), ` +
+      `${Object.keys(manifest).length} manifest entries — no collisions.`,
+  );
+  process.exit(0);
+}
+
+for (const e of errors) console.error(`${tag} FAIL  ${e.rule}: ${e.msg}`);
+console.error(
+  `\n${tag} Manifest validation failed: ${errors.length} error(s). ` +
+    `See "Vite Build Gotchas" in the inertia-react skill for the fix pattern.`,
+);
+process.exit(errors.some((e) => e.rule === 'R1') ? 2 : 1);

package/stacks/php/skills/inertia-react/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: inertia-react
-version: 2.0.0
+version: 2.1.0
 description: LEGACY skill — Inertia.js + React with Laravel-rendered pages. Use
   ONLY in pre-existing projects already built on Inertia. For NEW projects use
   `laravel-api-architecture` + `axios-laravel-api` + `react-api-standards`
-  (API-first React SPA, no controller-rendered pages).
+  (API-first React SPA, no controller-rendered pages). v2.1.0 adds the "Vite
+  Build Gotchas" section covering the manualChunks × entry-chunk ×
+  resolvePageComponent glob collision (silent wrong-component render
+  post-mortem 2026-05).
 ---
 
 # Inertia.js + React — Laravel Frontend (LEGACY)
@@ -207,6 +210,124 @@ export interface PaginatedData<T> {
 }
 ```
 
+## Vite Build Gotchas (Inertia-specific)
+
+> **Production post-mortem 2026-05.** A `vite.config.js` "perf" change adding
+> `manualChunks` to group `Pages/Auth/*` produced a silent wrong-component
+> render: `Inertia::render('Auth/Login', ...)` returned HTTP 200 OK but the
+> browser rendered the error page. Laravel logs were empty. Bug lived
+> entirely in the bundle graph.
+
+### The three-way collision
+
+```
+laravel-vite-plugin      ┐  laravel({ input: [...HttpErrorPage] })
+                         │  → module becomes an ENTRY chunk
+                         │    Rollup/Rolldown ALWAYS prioritizes entries.
+
+@inertiajs/react         ┐  resolvePageComponent(..., import.meta.glob(
+                         │    './Pages/**/*.jsx'))
+                         │  → builds a STATIC resolve-map at build time
+                         │    pointing each Page path to its chunk hash.
+
+build.rollupOptions      ┐  manualChunks(id) { if (Auth) return 'pages-auth' }
+                         │  → ADVISORY ONLY. Returning a group for a module
+                         │    that's already an entry has NO EFFECT and
+                         │    emits NO WARNING.
+```
+
+When the same module (e.g. `HttpErrorPage.jsx`) is BOTH:
+
+1. listed in `laravel.input[]` (typical: error pages referenced directly via
+   `@vite()` in `resources/views/app.blade.php` or a layout), AND
+2. caught by a `manualChunks` rule (e.g. `pages-auth`),
+
+…Rollup/Rolldown creates a **standalone entry chunk** with only that one
+module. The `pages-auth` group collapses into that entry. The
+`import.meta.glob` resolve-map points **every sibling page**
+(`Login`, `Register`, `ForgotPassword`, …) at the same chunk hash. The
+siblings' source is discarded.
+
+Symptom: server sends `component: 'Auth/Login'`, browser loads the chunk,
+chunk's `default` export is `HttpErrorPage`, error page renders. Server 100%
+correct; bundle ships the wrong default export.
+
+### Rule 1 — Never duplicate a module between `laravel.input` and the `Pages/**` glob
+
+Either exclude the entry page from the Inertia glob, OR short-circuit
+`manualChunks` BEFORE any grouping rule to preserve the entry's identity.
+Preferred pattern (no change to Inertia bootstrap):
+
+```js
+// vite.config.js
+build: {
+    rollupOptions: {
+        output: {
+            manualChunks(id) {
+                if (!id.includes('/resources/js/Pages/')) return;
+
+                // Entry chunks referenced directly by @vite() in blade MUST
+                // return undefined here — BEFORE any grouping rule. Otherwise
+                // the manualChunks group is collapsed into the entry and the
+                // import.meta.glob resolve-map points siblings at the wrong
+                // chunk hash. Production post-mortem 2026-05.
+                if (id.includes('/Pages/OtherPages/HttpErrorPage')) return;
+
+                if (id.includes('/Pages/Auth/') || id.includes('/Pages/OtherPages/')) {
+                    return 'pages-auth';
+                }
+                if (id.includes('/Pages/Dashboard/')) {
+                    return 'pages-dashboard';
+                }
+            },
+        },
+    },
+},
+```
+
+### Rule 2 — `manualChunks` is advisory; entries always win
+
+There is no warning when Rollup/Rolldown ignores a `manualChunks` return value
+for an entry module. Validation MUST be done out-of-band on `manifest.json`
+after every build.
+
+### Rule 3 — Validate `public/build/manifest.json` after every `vite build`
+
+`start-vibing-stacks` ships `scripts/check-vite-manifest.mjs` (wired as the
+`ViteManifest` quality gate at order 5):
+
+```bash
+node scripts/check-vite-manifest.mjs public/build/manifest.json vite.config.js
+```
+
+The script cross-references `laravel.input[]` against `Pages/**` glob patterns
+and fails (non-zero exit) on any collision.
+
+### Rule 4 — Smoke-test after any `vite.config.js` change touching `build`
+
+For one critical route per page group:
+
+1. DevTools → Network → click the Inertia XHR → read `component:` in the JSON.
+2. Click the JS asset request that follows → open the resolved chunk URL.
+3. Search for `default:` / `export{ ... as default}` in that chunk. The
+   exported component name MUST match the server's `component:`.
+
+If they don't match, revert the last `vite.config.js` change before debugging
+anything else.
+
+### Why this class of bug is so misleading
+
+| Layer | What it looks like | Why it misleads |
+|---|---|---|
+| Laravel logs | Empty | Backend is genuinely correct |
+| `manifest.json` | Valid, every input has an entry | Manifest doesn't enforce uniqueness across groups |
+| Browser network | 200 OK on every request | The wrong JS arrives successfully |
+| Console | Clean | The rendered component is valid React |
+
+Triage rule: **wrong-component render with HTTP 200 and empty server logs =
+bug is in the bundle, not the server.** See `debugging-patterns §Bundle, not
+Backend`.
+
 ## FORBIDDEN
 
 1. **API routes for Inertia pages** — use `Inertia::render()` in controllers
@@ -214,3 +335,6 @@ export interface PaginatedData<T> {
 3. **Fetching data in useEffect** — pass as props from controller
 4. **Duplicating validation** — validate in FormRequest, show errors from `useForm`
 5. **`any` types for page props** — always type with `interface Props extends PageProps`
+6. **Same module in `laravel.input[]` and `Pages/**` glob** — Rollup collapses the manual chunk group into the entry; resolve-map silently points siblings at the wrong chunk hash (wrong-component render with HTTP 200)
+7. **`manualChunks` grouping pages without running `check-vite-manifest.mjs`** — grouping is advisory and silently ignored for entry chunks
+8. **Trusting empty Laravel logs as "no bug"** — server can be 100% correct while the bundle ships the wrong `default` export

package/stacks/php/stack.json

@@ -19,7 +19,8 @@
     { "name": "PHPStan", "command": "vendor/bin/phpstan analyse --level=6", "required": true, "order": 1 },
     { "name": "PHPUnit", "command": "vendor/bin/phpunit", "required": true, "order": 2 },
     { "name": "TypeCheck", "command": "npx tsc --noEmit", "required": true, "order": 3 },
-    { "name": "Lint", "command": "npx eslint resources/js/", "required": false, "order": 4 }
+    { "name": "Lint", "command": "npx eslint resources/js/", "required": false, "order": 4 },
+    { "name": "ViteManifest", "command": "node scripts/check-vite-manifest.mjs", "required": false, "order": 5 }
   ],
   "frameworks": [
     {

package/templates/CLAUDE-php.md

@@ -310,6 +310,22 @@ const stripePublishable = import.meta.env.VITE_STRIPE_KEY;   // pk_...
 | `useEffect` to derive state | Anti-pattern — use `useMemo` |
 | Skipping skeleton/empty/error states | Bad UX — all three are mandatory per page |
 
+### Vite Build (CRITICAL — silent bug class)
+
+> **Production post-mortem 2026-05.** A bad `manualChunks` rule can produce
+> silent wrong-component renders (HTTP 200, empty Laravel logs, browser
+> shows the error page when server asked for `Auth/Login`). Bug lives in the
+> bundle graph, not the server. See `inertia-react §Vite Build Gotchas` and
+> `debugging-patterns §Bundle, not Backend`.
+
+| Action | Reason |
+|--------|--------|
+| Same module in `laravel.input[]` and `Pages/**` glob | Rollup/Rolldown silently collapses the manualChunks group into the entry chunk; `import.meta.glob` resolve-map points siblings at the wrong hash |
+| `manualChunks` grouping pages without short-circuit for entry pages | `manualChunks` is advisory — entries always win, with no warning. Add early `return undefined` for any page also listed in `laravel.input[]` |
+| Skipping `node scripts/check-vite-manifest.mjs` after `vite build` | Bundler emits no warning on collision; manual validation is the only signal |
+| Debugging Laravel/server when HTTP 200 + empty logs + wrong content | Triage as "Bundle, not Backend" — start from the JS chunk's `default` export, not the controller |
+| Adding new `@vite('resources/js/Pages/...')` direct reference in blade without auditing `vite.config.js` | Promoting a page to entry chunk while it's still in the Inertia glob is the exact collision shape |
+
 ## UI/UX Design Intelligence
 
 > When the project has a frontend, the **UI/UX Pro Max** skill is auto-installed. It provides 67 UI styles, 161 color palettes, 57 font pairings, and 161 industry-specific reasoning rules. It activates automatically for any UI/UX task.