Nextjs Bundle Optimizer

{
  "package_manager": "",
  "app_dir": "",
  "build_command": "",
  "test_command": "",
  "typecheck_command": "",
  "budget_dir": ".bundle-budgets",
  "_setup_instructions": {
    "package_manager": "One of: npm, pnpm, yarn, bun. Detect from lockfile if unsure (pnpm-lock.yaml, yarn.lock, bun.lockb, package-lock.json).",
    "app_dir": "Absolute or relative path to the Next.js app root (the dir containing next.config.{js,ts}). Use '.' if running from inside the app.",
    "build_command": "Command that runs `next build`. Examples: 'npm run build', 'pnpm build', 'yarn build'. Leave blank to default to '<package_manager> run build'.",
    "test_command": "Command that runs the test suite. Examples: 'npm test', 'pnpm vitest run', 'jest --ci'. Leave blank to skip test verification.",
    "typecheck_command": "Command that type-checks without emitting. Default: 'npx tsc --noEmit'. Override if the project uses a different command (e.g. 'pnpm run typecheck').",
    "budget_dir": "Optional. Directory (relative to the Next.js app) where per-route bundle budgets live. Default: '.bundle-budgets'. Not strictly required for the iteration loop."
  }
}

{
  "version": "1.0.3",
  "organization": "dot-skills",
  "technology": "Next.js 16",
  "discipline": "composition",
  "type": "automation",
  "date": "May 2026",
  "abstract": "Data-driven optimization loop for Next.js 16 bundle size and build time. Orchestrates `next experimental-analyze`, build timing, type checks, and tests to make verifiable improvements one change at a time. Enforces baseline → analyze → diagnose → apply → measure → compare → verify discipline with hard PASS/FAIL gates so each commit is a confirmed improvement.",
  "references": [
    "https://nextjs.org/docs/app/guides/package-bundling",
    "https://nextjs.org/docs/app/api-reference/cli/next",
    "https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache",
    "https://nextjs.org/docs/app/api-reference/config/next-config-js/optimizePackageImports",
    "https://nextjs.org/docs/app/api-reference/turbopack",
    "https://nextjs.org/docs/app/guides/upgrading/version-16",
    "https://nextjs.org/docs/app/guides/lazy-loading"
  ]
}

#!/usr/bin/env bash
# _common.sh — shared helpers for nextjs-bundle-optimizer scripts.
# Sourced, not executed. Use: source "$(dirname "$0")/_common.sh"
set -euo pipefail

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
CONFIG_FILE="${CLAUDE_PLUGIN_DATA:-$SKILL_DIR}/config.json"

if [[ ! -f "$CONFIG_FILE" ]]; then
  echo "ERROR: config.json not found at $CONFIG_FILE" >&2
  echo "Run: bash scripts/baseline.sh --setup" >&2
  exit 1
fi

require_jq() {
  command -v jq >/dev/null 2>&1 || {
    echo "ERROR: jq is required. Install: brew install jq" >&2
    exit 1
  }
}

cfg() {
  jq -r --arg k "$1" '.[$k] // empty' "$CONFIG_FILE"
}

PKG_MANAGER="$(cfg package_manager)"
APP_DIR="$(cfg app_dir)"
BUILD_CMD="$(cfg build_command)"
TEST_CMD="$(cfg test_command)"
TYPECHECK_CMD="$(cfg typecheck_command)"
BUDGET_DIR="$(cfg budget_dir)"

PKG_MANAGER="${PKG_MANAGER:-npm}"
APP_DIR="${APP_DIR:-.}"
BUILD_CMD="${BUILD_CMD:-${PKG_MANAGER} run build}"
TEST_CMD="${TEST_CMD:-${PKG_MANAGER} test}"
TYPECHECK_CMD="${TYPECHECK_CMD:-npx tsc --noEmit}"
BUDGET_DIR="${BUDGET_DIR:-.bundle-budgets}"

ensure_clean_git() {
  pushd "$APP_DIR" >/dev/null
  if [[ -n "$(git status --porcelain 2>/dev/null || true)" ]]; then
    echo "ERROR: working tree is dirty. Commit or stash before measuring." >&2
    echo "Reason: an iteration's result must be attributable to a single change." >&2
    popd >/dev/null
    exit 1
  fi
  popd >/dev/null
}

detect_next_version() {
  pushd "$APP_DIR" >/dev/null
  local v
  v="$(jq -r '.dependencies.next // .devDependencies.next // empty' package.json 2>/dev/null || true)"
  popd >/dev/null
  echo "${v#^}" | awk -F. '{print $1}'
}

detect_bundler() {
  pushd "$APP_DIR" >/dev/null
  local major
  major="$(detect_next_version || echo 0)"
  if [[ "$major" -ge 16 ]]; then
    echo "turbopack"
  else
    local turbo
    turbo="$(jq -r '.scripts.build // empty' package.json | grep -c -- '--turbopack' || true)"
    if [[ "$turbo" -gt 0 ]]; then
      echo "turbopack"
    else
      echo "webpack"
    fi
  fi
  popd >/dev/null
}

now_iso() { date -u +"%Y-%m-%dT%H-%M-%SZ"; }

human_bytes() {
  awk -v b="$1" 'BEGIN{
    units="B KB MB GB"; split(units,u," ");
    i=1; while(b>=1024 && i<4){b/=1024; i++}
    printf("%.1f %s\n", b, u[i])
  }'
}

#!/usr/bin/env bash
# analyze.sh — Run the bundle analyzer and extract top offenders.
# Usage: bash scripts/analyze.sh [iteration-name]
# Defaults iteration-name to a timestamp. Output: iterations/{name}/findings.json
set -euo pipefail

source "$(dirname "$0")/_common.sh"
require_jq

cd "$APP_DIR"

ITER_NAME="${1:-$(now_iso)}"
OUT_DIR="$SKILL_DIR/iterations/$ITER_NAME"
mkdir -p "$OUT_DIR"

BUNDLER="$(detect_bundler)"
NEXT_MAJOR="$(detect_next_version)"

echo "→ Analyze run: $ITER_NAME ($BUNDLER, next $NEXT_MAJOR)"

if [[ ! -d .next ]]; then
  echo "ERROR: .next/ missing. Run scripts/baseline.sh or scripts/measure.sh first." >&2
  exit 1
fi

if [[ "$BUNDLER" == "turbopack" ]] && [[ "$NEXT_MAJOR" -ge 16 ]]; then
  if [[ ! -d .next/diagnostics/analyze ]]; then
    echo "→ Running next experimental-analyze --output"
    npx next experimental-analyze --output
  fi
  if [[ -d .next/diagnostics/analyze ]]; then
    cp -R .next/diagnostics/analyze "$OUT_DIR/analyze"
  fi
else
  echo "→ Turbopack analyzer not available (webpack mode or Next < 16)."
  echo "  Using build-manifest only. Install @next/bundle-analyzer for richer data."
fi

# Build findings.json — the structured input for diagnose.sh.
# We work from build-manifest data which is always available.
node - "$OUT_DIR" <<'NODE'
const fs = require('fs');
const path = require('path');
const outDir = process.argv[2];
const root = process.cwd();
function readJson(p){ try{ return JSON.parse(fs.readFileSync(p,'utf8')); }catch{ return null; } }

const buildManifest = readJson(path.join(root, '.next/build-manifest.json')) || {};
const appBuildManifest = readJson(path.join(root, '.next/app-build-manifest.json')) || {};

function fileSize(rel){
  const p = path.join(root, '.next', rel.replace(/^\/_next\//,'').replace(/^_next\//,''));
  try { return fs.statSync(p).size; } catch { return 0; }
}

// Per-chunk size index
const chunkSizes = {};
const seen = new Set();
function indexChunks(map){
  for (const chunks of Object.values(map || {})) {
    for (const c of (chunks || [])) {
      if (seen.has(c)) continue;
      seen.add(c);
      chunkSizes[c] = fileSize(c);
    }
  }
}
indexChunks(buildManifest.pages);
indexChunks(appBuildManifest.pages);

// Chunks used by many routes (shared / framework)
const usage = {};
function tallyUsage(map){
  for (const [route, chunks] of Object.entries(map || {})) {
    for (const c of (chunks || [])) {
      usage[c] = usage[c] || { routes: new Set(), bytes: chunkSizes[c] || 0 };
      usage[c].routes.add(route);
    }
  }
}
tallyUsage(buildManifest.pages);
tallyUsage(appBuildManifest.pages);

const topChunks = Object.entries(chunkSizes)
  .sort((a,b) => b[1] - a[1])
  .slice(0, 20)
  .map(([chunk, bytes]) => ({
    chunk,
    bytes,
    used_by_routes: Array.from(usage[chunk]?.routes || []).slice(0, 8),
    route_count: (usage[chunk]?.routes.size) || 0,
  }));

// Heaviest routes
function routeWeights(map, prefix){
  return Object.entries(map || {}).map(([route, chunks]) => ({
    route: `${prefix}${route}`,
    bytes: (chunks || []).reduce((a, c) => a + (chunkSizes[c] || 0), 0),
    chunk_count: (chunks || []).length,
  }));
}
const heaviestRoutes = [
  ...routeWeights(buildManifest.pages, 'pages:'),
  ...routeWeights(appBuildManifest.pages, 'app:'),
].sort((a,b) => b.bytes - a.bytes).slice(0, 15);

// Hints to feed diagnose.sh
const hints = [];
for (const c of topChunks.slice(0, 10)) {
  if (c.route_count >= 3) hints.push({ kind: 'shared-heavy', chunk: c.chunk, bytes: c.bytes, route_count: c.route_count });
  else hints.push({ kind: 'route-heavy', chunk: c.chunk, bytes: c.bytes, used_by_routes: c.used_by_routes });
}

// Treemap JSON, if Turbopack analyzer produced it (best-effort — schema is experimental)
const treemapJson = path.join(outDir, 'analyze', 'data.json');
let treemap = null;
if (fs.existsSync(treemapJson)) {
  treemap = readJson(treemapJson);
}

fs.writeFileSync(
  path.join(outDir, 'findings.json'),
  JSON.stringify({
    iteration: path.basename(outDir),
    ts: new Date().toISOString(),
    top_chunks: topChunks,
    heaviest_routes: heaviestRoutes,
    hints,
    has_treemap: !!treemap,
  }, null, 2)
);
NODE

# Build a structured bundle.json snapshot matching baseline format (for compare.sh)
node - "$OUT_DIR" <<'NODE'
const fs = require('fs');
const path = require('path');
const outDir = process.argv[2];
const root = process.cwd();
function readJson(p){ try{ return JSON.parse(fs.readFileSync(p,'utf8')); }catch{ return null; } }
const buildManifest = readJson(path.join(root, '.next/build-manifest.json')) || {};
const appBuildManifest = readJson(path.join(root, '.next/app-build-manifest.json')) || {};
function fileSize(rel){
  const p = path.join(root, '.next', rel.replace(/^\/_next\//,'').replace(/^_next\//,''));
  try { return fs.statSync(p).size; } catch { return 0; }
}
function sumRoute(chunks){ return (chunks||[]).reduce((a,c) => a + fileSize(c), 0); }
const routes = {};
for (const [route, chunks] of Object.entries(buildManifest.pages || {})) {
  routes[`pages:${route}`] = { chunks: chunks.length, bytes: sumRoute(chunks) };
}
for (const [route, chunks] of Object.entries(appBuildManifest.pages || {})) {
  routes[`app:${route}`] = { chunks: chunks.length, bytes: sumRoute(chunks) };
}
fs.writeFileSync(path.join(outDir, 'bundle.json'), JSON.stringify({ routes, ts: new Date().toISOString() }, null, 2));
NODE

echo ""
echo "✓ Findings saved to $OUT_DIR/findings.json"
echo ""
jq -r '
  "Top chunks (largest):",
  (.top_chunks[:5] | .[] | "  \(.bytes | tostring) B  \(.chunk)  (×\(.route_count) routes)"),
  "",
  "Heaviest routes:",
  (.heaviest_routes[:5] | .[] | "  \(.bytes | tostring) B  \(.route) (\(.chunk_count) chunks)")
' "$OUT_DIR/findings.json"

echo ""
echo "Next: bash scripts/diagnose.sh $OUT_DIR/findings.json"

#!/usr/bin/env bash
# baseline.sh — Establish the reference snapshot for bundle size + build time.
# Usage:
#   bash scripts/baseline.sh            # measure baseline
#   bash scripts/baseline.sh --setup    # interactively populate config.json
#   bash scripts/baseline.sh --dry-run  # print what would happen, no build
set -euo pipefail

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

if [[ "${1:-}" == "--setup" ]]; then
  CONFIG_FILE="${CLAUDE_PLUGIN_DATA:-$SKILL_DIR}/config.json"
  if [[ -f "$CONFIG_FILE" ]] && [[ -n "$(jq -r '.app_dir // empty' "$CONFIG_FILE" 2>/dev/null)" ]]; then
    echo "config.json already populated at $CONFIG_FILE"
    echo "Edit it directly to change values, or delete and re-run --setup."
    exit 0
  fi
  echo "Setup is intended to be driven by the agent via AskUserQuestion."
  echo "Required fields: package_manager, app_dir, build_command, test_command, typecheck_command, budget_dir"
  echo "See config.json _setup_instructions for guidance."
  exit 0
fi

source "$(dirname "$0")/_common.sh"
require_jq

DRY_RUN=0
[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=1

cd "$APP_DIR"

ensure_clean_git

BUNDLER="$(detect_bundler)"
NEXT_MAJOR="$(detect_next_version)"
TS="$(now_iso)"
OUT_DIR="$SKILL_DIR/baselines/$TS"

echo "→ Baseline run: $TS"
echo "  app_dir:    $APP_DIR"
echo "  bundler:    $BUNDLER"
echo "  next major: $NEXT_MAJOR"
echo "  output:     $OUT_DIR"

if [[ $DRY_RUN -eq 1 ]]; then
  echo "(dry-run) would: rm -rf .next && $BUILD_CMD && save snapshot"
  exit 0
fi

mkdir -p "$OUT_DIR"

echo "→ Clearing .next/ for a cold build (baseline must be reproducible)"
rm -rf .next

echo "→ Running production build"
BUILD_LOG="$OUT_DIR/build.log"
build_start=$(date +%s)
if ! bash -c "$BUILD_CMD" 2>&1 | tee "$BUILD_LOG"; then
  echo "ERROR: baseline build failed. Fix the build before baselining." >&2
  exit 1
fi
build_end=$(date +%s)
build_duration=$((build_end - build_start))

echo "→ Build OK in ${build_duration}s. Running bundle analyzer."
ANALYZE_OUT=".next/diagnostics/analyze"

if [[ "$BUNDLER" == "turbopack" ]] && [[ "$NEXT_MAJOR" -ge 16 ]]; then
  if ! npx next experimental-analyze --output 2>&1 | tee -a "$BUILD_LOG"; then
    echo "WARN: experimental-analyze failed; falling back to manifest-only snapshot." >&2
    ANALYZE_OUT=""
  fi
else
  echo "  Detected non-Turbopack project. Skipping experimental-analyze."
  echo "  For webpack mode, install @next/bundle-analyzer and re-run with ANALYZE=true."
  ANALYZE_OUT=""
fi

# Capture artifacts the comparison step relies on.
if [[ -n "$ANALYZE_OUT" ]] && [[ -d "$ANALYZE_OUT" ]]; then
  cp -R "$ANALYZE_OUT" "$OUT_DIR/analyze"
fi

# build-manifest.json: route → chunk list. Available for both bundlers.
[[ -f .next/build-manifest.json ]] && cp .next/build-manifest.json "$OUT_DIR/build-manifest.json"
[[ -f .next/app-build-manifest.json ]] && cp .next/app-build-manifest.json "$OUT_DIR/app-build-manifest.json"

# Sum chunk sizes per route from the manifest. This is what we'll diff iteration-over-iteration.
node - <<'NODE' > "$OUT_DIR/bundle.json"
const fs = require('fs');
const path = require('path');
const root = process.cwd();
function readJson(p){ try{ return JSON.parse(fs.readFileSync(p,'utf8')); }catch{ return null; } }
const buildManifest = readJson(path.join(root, '.next/build-manifest.json')) || {};
const appBuildManifest = readJson(path.join(root, '.next/app-build-manifest.json')) || {};
const staticDir = path.join(root, '.next/static');
function fileSize(rel){
  const p = path.join(root, '.next', rel.replace(/^\/_next\//, '').replace(/^_next\//,''));
  try { return fs.statSync(p).size; } catch { return 0; }
}
function sumRoute(chunks){
  return (chunks||[]).reduce((acc, c) => acc + fileSize(c), 0);
}
const routes = {};
for (const [route, chunks] of Object.entries(buildManifest.pages || {})) {
  routes[`pages:${route}`] = { chunks: chunks.length, bytes: sumRoute(chunks) };
}
for (const [route, chunks] of Object.entries(appBuildManifest.pages || {})) {
  routes[`app:${route}`] = { chunks: chunks.length, bytes: sumRoute(chunks) };
}
process.stdout.write(JSON.stringify({ routes, ts: new Date().toISOString() }, null, 2));
NODE

# Timing snapshot
jq -n \
  --arg ts "$TS" \
  --arg bundler "$BUNDLER" \
  --argjson build_seconds "$build_duration" \
  '{ts: $ts, bundler: $bundler, build_seconds: $build_seconds, cache: "cold"}' \
  > "$OUT_DIR/timing.json"

# Mark this as the current baseline (symlink for quick reference)
ln -sfn "$OUT_DIR" "$SKILL_DIR/baselines/current"

echo ""
echo "✓ Baseline saved to $OUT_DIR"
echo "  build_seconds: ${build_duration}"
echo "  routes:        $(jq '.routes | length' "$OUT_DIR/bundle.json")"
echo ""
echo "Next: bash scripts/analyze.sh"

#!/usr/bin/env bash
# compare.sh — Diff a measurement against the baseline.
# Usage:
#   bash scripts/compare.sh                          # latest iteration vs baselines/current
#   bash scripts/compare.sh <baseline> <current>     # explicit paths
# Exit codes:
#   0 = improvement or no change
#   1 = overall regression (per-route increases beyond budget OR total grew)
#   2 = baseline or current missing
set -euo pipefail

source "$(dirname "$0")/_common.sh"
require_jq

BASELINE_DIR="${1:-$SKILL_DIR/baselines/current}"
CURRENT_DIR="${2:-}"

if [[ -z "$CURRENT_DIR" ]]; then
  CURRENT_DIR="$(ls -td "$SKILL_DIR"/iterations/*/ 2>/dev/null | head -n1 || true)"
fi

if [[ ! -f "$BASELINE_DIR/bundle.json" ]]; then
  echo "ERROR: baseline bundle.json missing at $BASELINE_DIR" >&2
  echo "Run: bash scripts/baseline.sh" >&2
  exit 2
fi
if [[ -z "$CURRENT_DIR" ]] || [[ ! -f "${CURRENT_DIR%/}/bundle.json" ]]; then
  echo "ERROR: current bundle.json missing." >&2
  echo "Run: bash scripts/measure.sh" >&2
  exit 2
fi
CURRENT_DIR="${CURRENT_DIR%/}"

echo "→ Comparing"
echo "  baseline: $BASELINE_DIR"
echo "  current:  $CURRENT_DIR"
echo ""

# Per-route delta — show top changes by absolute size.
RESULT=$(
node - "$BASELINE_DIR/bundle.json" "$CURRENT_DIR/bundle.json" <<'NODE'
const fs = require('fs');
const b = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
const c = JSON.parse(fs.readFileSync(process.argv[3], 'utf8'));
const routes = new Set([...Object.keys(b.routes||{}), ...Object.keys(c.routes||{})]);
const deltas = [];
let totalB = 0, totalC = 0;
for (const r of routes){
  const before = b.routes[r]?.bytes ?? 0;
  const after  = c.routes[r]?.bytes ?? 0;
  totalB += before; totalC += after;
  if (before === after) continue;
  deltas.push({ route: r, before, after, delta: after - before, pct: before === 0 ? 100 : ((after - before)/before * 100) });
}
deltas.sort((a,b) => Math.abs(b.delta) - Math.abs(a.delta));
const overall = totalC - totalB;
const overallPct = totalB === 0 ? 0 : (overall / totalB * 100);
function fmt(n){ const s = n>=0?'+':''; if (Math.abs(n)>=1024*1024) return `${s}${(n/1024/1024).toFixed(2)} MB`; if (Math.abs(n)>=1024) return `${s}${(n/1024).toFixed(1)} KB`; return `${s}${n} B`; }
console.log(`Total: ${(totalB/1024).toFixed(1)} KB → ${(totalC/1024).toFixed(1)} KB  (${fmt(overall)}, ${overallPct.toFixed(1)}%)`);
console.log('');
console.log('Top 15 route deltas:');
for (const d of deltas.slice(0, 15)){
  const arrow = d.delta < 0 ? '↓' : '↑';
  console.log(`  ${arrow} ${fmt(d.delta).padEnd(12)} ${d.pct.toFixed(1).padStart(6)}%   ${d.route}`);
}
console.log('');
// Timing delta if available
try {
  const tb = JSON.parse(fs.readFileSync(process.argv[2].replace('bundle.json','timing.json'), 'utf8'));
  const tc = JSON.parse(fs.readFileSync(process.argv[3].replace('bundle.json','timing.json'), 'utf8'));
  const td = (tc.build_seconds||0) - (tb.build_seconds||0);
  console.log(`Build time: ${tb.build_seconds}s → ${tc.build_seconds}s  (${td>=0?'+':''}${td}s)`);
} catch {}
// Machine-readable summary for callers
process.stderr.write(JSON.stringify({ overall_bytes_delta: overall, overall_pct: overallPct, regressions: deltas.filter(d=>d.delta>0), wins: deltas.filter(d=>d.delta<0) }) + '\n');
process.exit(overall > 0 ? 1 : 0);
NODE
)
EXIT=$?
echo "$RESULT"
exit $EXIT

#!/usr/bin/env bash
# diagnose.sh — Map findings to optimization recipes.
# Usage: bash scripts/diagnose.sh [path/to/findings.json]
# Defaults to the most recent iteration's findings.json.
# Output: stdout — prioritized recipe list with pointers into references/optimizations.md.
set -euo pipefail

source "$(dirname "$0")/_common.sh"
require_jq

FINDINGS="${1:-}"
if [[ -z "$FINDINGS" ]]; then
  FINDINGS="$(ls -td "$SKILL_DIR"/iterations/*/findings.json 2>/dev/null | head -n1 || true)"
fi

if [[ -z "$FINDINGS" ]] || [[ ! -f "$FINDINGS" ]]; then
  echo "ERROR: no findings.json. Run scripts/analyze.sh first." >&2
  exit 1
fi

echo "→ Diagnosing $FINDINGS"
echo ""

# Look at top chunks and heaviest routes, classify each, suggest a recipe.
# Classification is heuristic; the agent should still verify by inspecting
# the analyzer treemap or the import chain.

node - "$FINDINGS" <<'NODE'
const fs = require('fs');
const findings = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));

const recipes = [];

// Heuristic: very large shared chunk used by ≥3 routes → barrel-import or polyfill bloat
// Heuristic: huge route-specific chunk → check for accidental client component / heavy dep
// Heuristic: many small chunks → fine, ignore

function fmt(n){
  if (n >= 1024*1024) return `${(n/1024/1024).toFixed(2)} MB`;
  if (n >= 1024) return `${(n/1024).toFixed(1)} KB`;
  return `${n} B`;
}

const SHARED_THRESHOLD = 100 * 1024;     // 100 KB
const ROUTE_THRESHOLD  = 200 * 1024;     // 200 KB
const DOMINANT_CHUNK   = 50 * 1024;      // a single chunk >50KB is worth investigating

for (const c of findings.top_chunks) {
  if (c.bytes < DOMINANT_CHUNK) continue;
  const shared = c.route_count >= 3;
  const isPolyfillish = /polyfill|core-js|legacy/i.test(c.chunk);
  const isFramework  = /framework|main|webpack-runtime|polyfills/i.test(c.chunk);

  if (isFramework && !isPolyfillish) {
    recipes.push({
      priority: 'LOW',
      finding: `${fmt(c.bytes)} framework chunk: ${c.chunk}`,
      recipe: 'framework-chunks',
      why: 'Framework chunks are mostly fixed cost. Only worth touching if extraordinarily large.',
    });
    continue;
  }
  if (isPolyfillish) {
    recipes.push({
      priority: 'HIGH',
      finding: `${fmt(c.bytes)} polyfill-related chunk: ${c.chunk}`,
      recipe: 'polyfill-bloat',
      why: 'Polyfills compound across routes. Tightening browserslist usually has the biggest single-change impact.',
    });
    continue;
  }
  if (shared && c.bytes > SHARED_THRESHOLD) {
    recipes.push({
      priority: 'HIGH',
      finding: `${fmt(c.bytes)} shared chunk used by ${c.route_count} routes: ${c.chunk}`,
      recipe: 'shared-heavy-dep',
      why: 'A heavy dep imported across many routes multiplies the cost. Investigate import chain in the analyzer treemap.',
    });
    continue;
  }
  if (!shared && c.bytes > ROUTE_THRESHOLD) {
    recipes.push({
      priority: 'MEDIUM',
      finding: `${fmt(c.bytes)} route-specific chunk: ${c.chunk} (routes: ${c.used_by_routes.join(', ')})`,
      recipe: 'heavy-client-component',
      why: 'Could be a wrong-side import (server lib in client) or a candidate for next/dynamic + ssr:false.',
    });
    continue;
  }
}

// Per-route weight checks
for (const r of findings.heaviest_routes.slice(0, 5)) {
  if (r.bytes > 500 * 1024) {
    recipes.push({
      priority: 'HIGH',
      finding: `${fmt(r.bytes)} route bundle: ${r.route}`,
      recipe: 'large-route-bundle',
      why: 'Routes over ~500KB hurt LCP/TTI on mobile. Open the analyzer treemap for this route and look at the largest module.',
    });
  } else if (r.bytes > 250 * 1024) {
    recipes.push({
      priority: 'MEDIUM',
      finding: `${fmt(r.bytes)} route bundle: ${r.route}`,
      recipe: 'large-route-bundle',
      why: 'Approaching the warning threshold; opportunistic optimization worthwhile.',
    });
  }
}

if (recipes.length === 0) {
  console.log('No obvious offenders. Bundle is in good shape.');
  console.log('Consider build-time optimizations — see references/optimizations.md#build-time.');
  process.exit(0);
}

// Sort by priority HIGH > MEDIUM > LOW
const order = { HIGH: 0, MEDIUM: 1, LOW: 2 };
recipes.sort((a,b) => order[a.priority] - order[b.priority]);

console.log('Recommended recipes (apply ONE at a time, then measure + verify):');
console.log('');
for (let i = 0; i < recipes.length; i++) {
  const r = recipes[i];
  console.log(`${i+1}. [${r.priority}] ${r.finding}`);
  console.log(`   Recipe:  references/optimizations.md#${r.recipe}`);
  console.log(`   Why:     ${r.why}`);
  console.log('');
}

console.log('After applying one recipe:');
console.log('  bash scripts/measure.sh');
console.log('  bash scripts/compare.sh');
console.log('  bash scripts/verify.sh');
NODE

#!/usr/bin/env bash
# measure.sh — Re-build and re-measure after applying a change.
# Usage:
#   bash scripts/measure.sh [iteration-name]
#   bash scripts/measure.sh --warm   # do NOT delete .next; measures incremental build
# Default: cold build (rm -rf .next) for apples-to-apples vs the baseline.
set -euo pipefail

source "$(dirname "$0")/_common.sh"
require_jq

cd "$APP_DIR"

WARM=0
ITER_NAME=""
for arg in "$@"; do
  case "$arg" in
    --warm) WARM=1 ;;
    --dry-run) echo "(dry-run) would: build, analyze, write iteration snapshot"; exit 0 ;;
    *) ITER_NAME="$arg" ;;
  esac
done
ITER_NAME="${ITER_NAME:-$(now_iso)}"

OUT_DIR="$SKILL_DIR/iterations/$ITER_NAME"
mkdir -p "$OUT_DIR"

BUNDLER="$(detect_bundler)"
NEXT_MAJOR="$(detect_next_version)"

echo "→ Measure run: $ITER_NAME ($BUNDLER)"
if [[ $WARM -eq 0 ]]; then
  echo "  Cold build (rm -rf .next)"
  rm -rf .next
else
  echo "  Warm build (reusing existing .next/cache)"
fi

BUILD_LOG="$OUT_DIR/build.log"
build_start=$(date +%s)
if ! bash -c "$BUILD_CMD" 2>&1 | tee "$BUILD_LOG"; then
  echo "ERROR: build failed. This means the most recent change broke the build." >&2
  echo "Action: revert and try a different recipe." >&2
  jq -n --arg ts "$ITER_NAME" '{ts:$ts, status:"build_failed"}' > "$OUT_DIR/timing.json"
  exit 1
fi
build_end=$(date +%s)
build_duration=$((build_end - build_start))

jq -n \
  --arg ts "$ITER_NAME" \
  --arg bundler "$BUNDLER" \
  --argjson build_seconds "$build_duration" \
  --arg cache "$([[ $WARM -eq 1 ]] && echo warm || echo cold)" \
  '{ts:$ts, bundler:$bundler, build_seconds:$build_seconds, cache:$cache, status:"ok"}' \
  > "$OUT_DIR/timing.json"

# Delegate the bundle snapshot + findings extraction to analyze.sh.
bash "$SKILL_DIR/scripts/analyze.sh" "$ITER_NAME"

echo ""
echo "✓ Measurement complete: $OUT_DIR"
echo "  build_seconds: ${build_duration}"
echo ""
echo "Next: bash scripts/compare.sh"

#!/usr/bin/env bash
# verify.sh — Hard verification: build + types + tests + no overall regression.
# Usage: bash scripts/verify.sh
# Exit 0 = safe to commit. Exit 1 = revert.
set -euo pipefail

source "$(dirname "$0")/_common.sh"
require_jq

cd "$APP_DIR"

PASS=0
FAIL=0

# Note on arithmetic: ((PASS++)) returns exit 1 when PASS starts at 0 (post-increment
# of 0), which trips `set -e`. Use PASS=$((PASS+1)) instead.

run_check() {
  local label="$1"; shift
  echo "→ $label"
  if "$@"; then
    echo "  PASS: $label"
    PASS=$((PASS+1))
  else
    echo "  FAIL: $label"
    FAIL=$((FAIL+1))
  fi
}

# 1. Build (cold for a fair comparison; skip if measure.sh already left a fresh .next)
if [[ ! -f .next/build-manifest.json ]] && [[ ! -f .next/app-build-manifest.json ]]; then
  rm -rf .next
  run_check "next build" bash -c "$BUILD_CMD"
else
  echo "→ Skipping rebuild (fresh .next/ from measure.sh)"
  PASS=$((PASS+1))
fi

# 2. Type check — counts as FAIL if it fails (no `|| true` swallowing).
run_check "typecheck ($TYPECHECK_CMD)" bash -c "$TYPECHECK_CMD"

# 3. Tests (only if a test command is configured AND there are test files)
if [[ -n "$TEST_CMD" ]]; then
  if find . -maxdepth 4 -type d \( -name node_modules -o -name .next -o -name .git \) -prune -o \
       -type f \( -name '*.test.*' -o -name '*.spec.*' \) -print -quit 2>/dev/null | grep -q .; then
    run_check "tests ($TEST_CMD)" bash -c "$TEST_CMD"
  else
    echo "→ No test files detected; skipping $TEST_CMD"
    PASS=$((PASS+1))
  fi
fi

# 4. No overall bundle regression vs baseline
if [[ -d "$SKILL_DIR/baselines/current" ]]; then
  echo "→ Bundle regression check vs baselines/current"
  # compare.sh exits 1 on regression. Don't let set -e abort us before we record FAIL.
  set +e
  bash "$SKILL_DIR/scripts/compare.sh" >/dev/null
  cmp_exit=$?
  set -e
  if [[ $cmp_exit -eq 0 ]]; then
    echo "  PASS: no overall regression"
    PASS=$((PASS+1))
  else
    echo "  FAIL: overall bundle grew. See: bash scripts/compare.sh"
    FAIL=$((FAIL+1))
  fi
else
  echo "→ No baseline yet; skipping regression check"
fi

echo ""
echo "Results: $PASS passed, $FAIL failed"
if [[ $FAIL -gt 0 ]]; then
  echo ""
  echo "Verify FAILED. Recommended action: git revert the last change and try a different recipe."
  exit 1
fi

echo ""
echo "Verify PASSED. Safe to commit."
echo "Suggested: git add -A && git commit -m 'optim: <recipe applied>'"
exit 0