@mifort-solutions/qmetrix 1.0.0

package/src/e2e-server-guard.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Guards the e2e suite against a stale `next start` server and a poisoned
+ * prerender cache on the Playwright port.
+ *
+ * The PW config reuses an existing server locally (reuseExistingServer), so a
+ * server started BEFORE the latest `next build` keeps serving HTML that
+ * references chunk files which no longer exist on disk — JS fails to load,
+ * React never hydrates, and every interaction-dependent test times out.
+ * Worse, while such a server runs, its ISR revalidations WRITE old-build HTML
+ * into the new build's prerender cache (.next/server/app), so even a freshly
+ * started server then serves broken pages for those routes (Next serves the
+ * stale cache entry first and only re-renders in the background).
+ *
+ * Two modes:
+ *  - default: health-check a running server by fetching the home page and
+ *    requesting the /_next/static assets it references (a fresh server serves
+ *    its own assets; a stale one 404/500s them), then scan the prerender cache
+ *    for entries referencing assets missing from .next/static and purge them.
+ *  - --pre-build: a `next build` is about to run, which makes ANY currently
+ *    running local server stale-after-build (and lets it poison the new
+ *    build's cache via ISR). Kill it unconditionally.
+ *
+ * Outcomes (both modes): exit 0 when the port is safe for Playwright, exit 1
+ * with instructions when the port is held by something unrecognized. Runs from
+ * the npm scripts (test:e2e, coverage:e2e); invoking `playwright test`
+ * directly bypasses it. Skipped when PW_BASE_URL targets a remote site.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+const PORT = Number(process.env.PORT ?? 3000);
+const BASE = `http://localhost:${PORT}`;
+const MAX_ASSETS = 10;
+const PRE_BUILD = process.argv.includes('--pre-build');
+// Anchored on the consuming repo's cwd — every verb runs from the app root.
+const rootDir = process.cwd();
+const log = (msg) => console.log(`[e2e-server-guard] ${msg}`);
+
+if (process.env.PW_BASE_URL) {
+  log(`PW_BASE_URL is set (${process.env.PW_BASE_URL}) - remote run, nothing to guard.`);
+  process.exit(0);
+}
+
+const isConnRefused = (err) => err?.cause?.code === 'ECONNREFUSED' || err?.code === 'ECONNREFUSED';
+
+async function probeHome() {
+  try {
+    const res = await fetch(`${BASE}/`, { signal: AbortSignal.timeout(8000) });
+    if (!res.ok) {
+      return { state: 'stale', reason: `GET / returned HTTP ${res.status}` };
+    }
+    return { state: 'up', html: await res.text() };
+  } catch (err) {
+    if (isConnRefused(err)) {
+      return { state: 'free' };
+    }
+    return { state: 'stale', reason: `GET / failed (${err.cause?.code ?? err.name})` };
+  }
+}
+
+async function findBrokenAssets(html) {
+  const assets = [...new Set(html.match(/\/_next\/static\/[^"'\\ )?#]+\.(?:js|css)/g) ?? [])];
+  if (assets.length === 0) {
+    return [`no /_next/static assets found in the served HTML - not this app's Next server?`];
+  }
+  const broken = [];
+  for (const asset of assets.slice(0, MAX_ASSETS)) {
+    try {
+      const res = await fetch(BASE + asset, { signal: AbortSignal.timeout(8000) });
+      if (!res.ok) {
+        broken.push(`${asset} -> HTTP ${res.status}`);
+      }
+    } catch (err) {
+      broken.push(`${asset} -> ${err.cause?.code ?? err.name}`);
+    }
+  }
+  return broken;
+}
+
+function findListeningPids() {
+  if (process.platform === 'win32') {
+    const out = execFileSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf8' });
+    const re = new RegExp(`TCP\\s+\\S*:${PORT}\\s+\\S+\\s+LISTENING\\s+(\\d+)`, 'g');
+    return [...new Set([...out.matchAll(re)].map((m) => Number(m[1])))];
+  }
+  try {
+    const out = execFileSync('lsof', ['-ti', `tcp:${PORT}`, '-sTCP:LISTEN'], { encoding: 'utf8' });
+    return [...new Set(out.split('\n').filter(Boolean).map(Number))];
+  } catch {
+    return []; // lsof exits non-zero when nothing matches
+  }
+}
+
+function commandLineOf(pid) {
+  try {
+    if (process.platform === 'win32') {
+      return execFileSync(
+        'powershell',
+        [
+          '-NoProfile',
+          '-Command',
+          `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine`,
+        ],
+        { encoding: 'utf8' },
+      ).trim();
+    }
+    return execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function killPid(pid) {
+  if (process.platform === 'win32') {
+    execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+  } else {
+    process.kill(pid, 'SIGTERM');
+  }
+}
+
+async function waitForPortFree() {
+  for (let i = 0; i < 20; i++) {
+    try {
+      await fetch(`${BASE}/`, { signal: AbortSignal.timeout(1000) });
+    } catch (err) {
+      if (isConnRefused(err)) {
+        return true;
+      }
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+function killListeningServer(reason) {
+  log(`killing server on :${PORT}: ${reason}`);
+  const pids = findListeningPids();
+  if (pids.length === 0) {
+    log('could not find the owning process; free the port manually and retry.');
+    process.exit(1);
+  }
+  for (const pid of pids) {
+    const cmd = commandLineOf(pid);
+    // Only kill processes that are recognizably this stack's dev/prod server.
+    if (!/next|node/i.test(cmd)) {
+      log(
+        `port :${PORT} is held by PID ${pid} (${cmd || 'unknown command'}) - not a Next/Node server, refusing to kill it.`,
+      );
+      log('stop it manually (or set PW_BASE_URL to target it intentionally) and retry.');
+      process.exit(1);
+    }
+    log(`killing PID ${pid} (${cmd})`);
+    killPid(pid);
+  }
+}
+
+// --- prerender-cache integrity ------------------------------------------------
+// A stale server's ISR writes leave .next/server/app entries whose HTML/RSC
+// reference assets from the previous build. Detect them by checking every
+// /_next/static (or flight-payload "static/...") reference against the files
+// actually present in .next/static, and purge the whole route entry
+// (.html/.rsc/.meta/.segments) so the fresh server re-renders it on demand.
+
+function* walkFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(p);
+    } else {
+      yield p;
+    }
+  }
+}
+
+function staticRefsOf(text) {
+  const refs = new Set();
+  for (const m of text.match(/\/_next\/static\/[^"'\\ )?#]+/g) ?? []) {
+    refs.add(m.slice('/_next/static/'.length));
+  }
+  for (const m of text.match(/\bstatic\/(?:chunks|css|media)\/[^"'\\ )?#]+/g) ?? []) {
+    refs.add(m.slice('static/'.length));
+  }
+  return refs;
+}
+
+function purgePoisonedPrerenders() {
+  const appDir = path.join(rootDir, '.next', 'server', 'app');
+  const staticDir = path.join(rootDir, '.next', 'static');
+  const poisoned = new Set();
+  if (!existsSync(appDir) || !existsSync(staticDir)) {
+    return poisoned;
+  }
+  const segMarker = `.segments${path.sep}`;
+  for (const file of walkFiles(appDir)) {
+    if (!/\.(html|rsc)$/.test(file)) {
+      continue;
+    }
+    // Files inside <route>.segments/ belong to that route; purge at route level.
+    const base = file.includes(segMarker)
+      ? file.slice(0, file.indexOf(segMarker))
+      : file.replace(/\.(prefetch\.rsc|rsc|html)$/, '');
+    if (poisoned.has(base)) {
+      continue;
+    }
+    for (const ref of staticRefsOf(readFileSync(file, 'utf8'))) {
+      if (!existsSync(path.join(staticDir, ref))) {
+        poisoned.add(base);
+        log(`poisoned prerender: ${path.relative(rootDir, file)} references missing static/${ref}`);
+        break;
+      }
+    }
+  }
+  for (const base of poisoned) {
+    for (const suffix of ['.html', '.rsc', '.prefetch.rsc', '.meta']) {
+      rmSync(base + suffix, { force: true });
+    }
+    rmSync(base + '.segments', { recursive: true, force: true });
+    log(`purged stale prerender entry: ${path.relative(rootDir, base)}.* (re-rendered on demand)`);
+  }
+  if (poisoned.size === 0) {
+    log('prerender cache is consistent with .next/static.');
+  }
+  return poisoned;
+}
+
+// --- main ----------------------------------------------------------------------
+
+if (PRE_BUILD) {
+  // A rebuild is imminent: any running local server WILL be stale afterwards
+  // and would poison the new build's prerender cache via ISR writes.
+  if (findListeningPids().length === 0) {
+    log(`nothing listening on :${PORT} - safe to build.`);
+  } else {
+    killListeningServer('a new build is about to replace .next under it');
+    if (!(await waitForPortFree())) {
+      log(`port :${PORT} is still busy after kill; free it manually and retry.`);
+      process.exit(1);
+    }
+    log('server killed - safe to build.');
+  }
+  process.exit(0);
+}
+
+const probe = await probeHome();
+let needsKill = null;
+if (probe.state === 'stale') {
+  needsKill = probe.reason;
+} else if (probe.state === 'up') {
+  const broken = await findBrokenAssets(probe.html);
+  if (broken.length > 0) {
+    needsKill = `serves assets that fail to load:\n  ${broken.join('\n  ')}`;
+  }
+}
+
+if (needsKill) {
+  killListeningServer(needsKill);
+  if (!(await waitForPortFree())) {
+    log(`port :${PORT} is still busy after kill; free it manually and retry.`);
+    process.exit(1);
+  }
+  log('stale server killed - Playwright will start a fresh one.');
+  purgePoisonedPrerenders();
+} else if (probe.state === 'free') {
+  log(`nothing listening on :${PORT} - Playwright will start a fresh server.`);
+  purgePoisonedPrerenders();
+} else {
+  // Server looks healthy, but if the on-disk prerender cache held poisoned
+  // entries the server would still serve them (and may have them in memory) —
+  // in that case restart it on top of the purged cache.
+  const poisoned = purgePoisonedPrerenders();
+  if (poisoned.size > 0) {
+    killListeningServer('its in-memory cache may hold the purged poisoned entries');
+    if (!(await waitForPortFree())) {
+      log(`port :${PORT} is still busy after kill; free it manually and retry.`);
+      process.exit(1);
+    }
+    log('server restart forced - Playwright will start a fresh one on the purged cache.');
+  } else {
+    log(`server on :${PORT} serves its own assets - safe to reuse.`);
+  }
+}

package/src/optimize-images.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * Image optimizer — resize + recompress committed assets with sharp (bundled with Next 16).
+ *
+ * Downscales anything larger than --max-px (never upscales, keeps aspect ratio) and
+ * re-encodes at --quality. By default keeps each file's format and overwrites in place;
+ * with --format it writes a converted copy alongside the original (update references,
+ * then pass --replace to delete the source file).
+ *
+ * Usage:
+ *   node dev/scripts/optimize-images.mjs [targets…] [options]
+ *   npm run images:optimize -- public/images --format webp
+ *
+ * Targets: image files or directories, searched recursively (default: public/)
+ * Options:
+ *   --max-px <n>    longest side after resize (default 2560, no upscaling)
+ *   --quality <n>   encoder quality 1–100 (default 80)
+ *   --format <f>    keep | webp | avif | jpeg | png   (default keep)
+ *   --replace       after a --format conversion, delete the original file
+ *   --dry-run       encode and report savings, but write nothing
+ *
+ * SVG and GIF are skipped (vector / animation — not sharp's job).
+ */
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { readFile, writeFile, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import sharp from 'sharp';
+
+// libvips' file cache holds input handles open, which breaks in-place overwrites
+// on Windows (EBUSY/EPERM on write). We read inputs into buffers ourselves, but
+// disable the cache too so no handle ever lingers.
+sharp.cache(false);
+
+// Anchored on the consuming repo's cwd — every verb runs from the app root.
+const ROOT = process.cwd();
+
+const RASTER_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.avif']);
+const SKIPPED_EXT = new Set(['.svg', '.gif']);
+const FORMATS = new Set(['keep', 'webp', 'avif', 'jpeg', 'png']);
+
+/* ── CLI parsing ── */
+const argv = process.argv.slice(2);
+const targets = [];
+let maxPx = 2560;
+let quality = 80;
+let format = 'keep';
+let replace = false;
+let dryRun = false;
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--max-px') {
+    maxPx = Number(argv[++i]);
+  } else if (a === '--quality') {
+    quality = Number(argv[++i]);
+  } else if (a === '--format') {
+    format = String(argv[++i]).toLowerCase();
+  } else if (a === '--replace') {
+    replace = true;
+  } else if (a === '--dry-run') {
+    dryRun = true;
+  } else if (a.startsWith('--')) {
+    console.error(`Unknown option: ${a} (see header of dev/scripts/optimize-images.mjs)`);
+    process.exit(2);
+  } else {
+    targets.push(a);
+  }
+}
+if (!FORMATS.has(format) || !(maxPx > 0) || !(quality >= 1 && quality <= 100)) {
+  console.error('Invalid options — format keep|webp|avif|jpeg|png, max-px > 0, quality 1–100.');
+  process.exit(2);
+}
+if (targets.length === 0) {
+  targets.push('public');
+}
+
+/* ── helpers ── */
+const rel = (p) => path.relative(ROOT, p).split(path.sep).join('/');
+const fmtKB = (bytes) =>
+  bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : bytes < 1024
+      ? `${bytes} B`
+      : `${Math.round(bytes / 1024)} KB`;
+
+// Same-format recompression is lossy; don't rewrite a file for a marginal win.
+const MIN_GAIN = 0.05;
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      yield* walk(path.join(dir, entry.name));
+    } else {
+      yield path.join(dir, entry.name);
+    }
+  }
+}
+
+function collectFiles() {
+  const files = [];
+  for (const t of targets) {
+    const abs = path.isAbsolute(t) ? t : path.join(ROOT, t);
+    if (!existsSync(abs)) {
+      console.error(`✗ Not found: ${t}`);
+      process.exit(2);
+    }
+    if (statSync(abs).isDirectory()) {
+      files.push(...walk(abs));
+    } else {
+      files.push(abs);
+    }
+  }
+  return files.filter((f) => {
+    const ext = path.extname(f).toLowerCase();
+    if (SKIPPED_EXT.has(ext)) {
+      console.log(`  ⊘ ${rel(f)} — ${ext.slice(1)} skipped (not handled by this tool)`);
+      return false;
+    }
+    return RASTER_EXT.has(ext);
+  });
+}
+
+// PNG quality requires palette quantization; only engage it below lossless quality.
+function encode(pipeline, fmt) {
+  if (fmt === 'jpeg') {
+    return pipeline.jpeg({ quality, mozjpeg: true });
+  }
+  if (fmt === 'webp') {
+    return pipeline.webp({ quality });
+  }
+  if (fmt === 'avif') {
+    return pipeline.avif({ quality });
+  }
+  if (fmt === 'png') {
+    return quality < 100
+      ? pipeline.png({ compressionLevel: 9, adaptiveFiltering: true, palette: true, quality })
+      : pipeline.png({ compressionLevel: 9, adaptiveFiltering: true });
+  }
+  throw new Error(`No encoder for format "${fmt}"`);
+}
+
+const EXT_FOR = { jpeg: '.jpg', png: '.png', webp: '.webp', avif: '.avif' };
+
+async function optimize(file) {
+  const input = await readFile(file); // buffer in, so the source file holds no open handle
+  const inBytes = input.length;
+  const meta = await sharp(input).metadata();
+  const srcFormat = meta.format === 'jpg' ? 'jpeg' : meta.format;
+  const outFormat = format === 'keep' ? srcFormat : format;
+  if (!EXT_FOR[outFormat]) {
+    console.log(`  ⊘ ${rel(file)} — source format "${srcFormat}" not supported, skipped`);
+    return null;
+  }
+
+  const converting = outFormat !== srcFormat;
+  const willResize = Math.max(meta.width ?? 0, meta.height ?? 0) > maxPx;
+
+  // A palette PNG has already been through quantization (likely a previous run of
+  // this tool) — re-encoding would stack generation loss for pennies. Idempotency guard.
+  if (!converting && !willResize && srcFormat === 'png' && meta.isPalette) {
+    console.log(`  = ${rel(file)} — already quantized (${fmtKB(inBytes)})`);
+    return { saved: 0 };
+  }
+
+  const pipeline = sharp(input)
+    .rotate() // bake EXIF orientation in before any resize
+    .resize({ width: maxPx, height: maxPx, fit: 'inside', withoutEnlargement: true });
+  const buf = await encode(pipeline, outFormat).toBuffer();
+
+  const outFile = converting
+    ? path.join(path.dirname(file), path.basename(file, path.extname(file)) + EXT_FOR[outFormat])
+    : file;
+
+  // Same format and no resize needed: rewriting is a lossy generation — only
+  // worth it when the size win is real, not a rounding error.
+  if (!converting && !willResize && buf.length >= inBytes * (1 - MIN_GAIN)) {
+    console.log(`  = ${rel(file)} — already optimal (${fmtKB(inBytes)})`);
+    return { saved: 0 };
+  }
+
+  if (!dryRun) {
+    await writeFile(outFile, buf);
+    if (converting && replace) {
+      await unlink(file);
+    }
+  }
+
+  const pct = Math.round((1 - buf.length / inBytes) * 100);
+  const dims = willResize ? ` ${meta.width}×${meta.height}→≤${maxPx}px` : '';
+  const arrow = converting ? ` → ${rel(outFile)}` : '';
+  console.log(
+    `  ${dryRun ? '·' : '✓'} ${rel(file)}${arrow}${dims}  ${fmtKB(inBytes)} → ${fmtKB(buf.length)} (−${pct}%)${dryRun ? '  [dry-run]' : ''}`,
+  );
+  return { saved: inBytes - buf.length };
+}
+
+/* ── main ── */
+const files = collectFiles();
+console.log(
+  `\n==  Image optimizer  ==  (${files.length} files · max ${maxPx}px · q${quality} · format=${format}${dryRun ? ' · DRY RUN' : ''})\n`,
+);
+if (files.length === 0) {
+  console.log('Nothing to do.\n');
+  process.exit(0);
+}
+
+let totalSaved = 0;
+let failures = 0;
+for (const file of files) {
+  try {
+    const r = await optimize(file);
+    if (r) {
+      totalSaved += Math.max(0, r.saved);
+    }
+  } catch (err) {
+    failures++;
+    console.log(`  ✗ ${rel(file)} — ${err.message}`);
+  }
+}
+
+console.log(`\n${dryRun ? 'Would save' : 'Saved'} ${fmtKB(totalSaved)} total.`);
+if (format !== 'keep') {
+  console.log(
+    replace
+      ? 'Originals deleted (--replace) — update any code/markdown references to the new extension.'
+      : 'Converted copies written alongside originals — update references, then re-run with --replace.',
+  );
+}
+console.log('');
+process.exit(failures ? 1 : 0);