start-vibing-stacks 2.20.0 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.20.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

@@ -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/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