create-website-build-kit 0.1.14 → 0.1.16

package/template/scripts/md-to-pdf.mjs

@@ -27,7 +27,34 @@
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
 import { dirname, basename, resolve } from 'node:path';
 
-import puppeteer from 'puppeteer';
+/*
+ * ⚠ puppeteer IS A TRANSITIVE DEPENDENCY, NOT A DECLARED ONE. The comment above
+ *   is true only while `pa11y-ci` is a devDependency of this project. Run pa11y
+ *   as `npx --yes pa11y-ci` instead — which a project reasonably might — and
+ *   puppeteer is never installed here at all.
+ *
+ *   A fork that did exactly that compensated by hunting for a puppeteer inside
+ *   `~/.npm/_npx`, found a stale one whose bundled Chrome would not launch, and
+ *   timed out after thirty seconds with nothing pointing at the cause.
+ *
+ *   So say it plainly rather than let a bare import throw ERR_MODULE_NOT_FOUND:
+ *   a script whose dependency is a side effect of how you happened to run a
+ *   different script is a script that breaks later, on someone else's machine,
+ *   for reasons that look unrelated.
+ */
+let puppeteer;
+try {
+  puppeteer = (await import('puppeteer')).default;
+} catch {
+  console.error(
+    `\nmd-to-pdf needs puppeteer, which is not installed.\n\n` +
+      `  It normally arrives with pa11y-ci, so this usually means pa11y-ci was\n` +
+      `  removed from devDependencies, or is being run as \`npx --yes pa11y-ci\`\n` +
+      `  rather than installed.\n\n` +
+      `  Fix: npm install --save-dev puppeteer\n`,
+  );
+  process.exit(1);
+}
 
 const [, , input, outputArg] = process.argv;
 if (!input) {

package/template/scripts/optimize-media.mjs

@@ -16,9 +16,18 @@
 import sharp from 'sharp';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/*
+ * ⚠ THE PROJECT ROOT IS THE CWD, as it is in every other script here.
+ *
+ *   This resolved from the SCRIPT's own location. In every supported flow the
+ *   two are the same directory — `npm run media` runs with the cwd at the
+ *   package root — so the change is a no-op in use. What it was not was
+ *   testable: the script read its own media/source/ no matter where it was
+ *   pointed, so a fixture could not exercise it at all, and the run that added
+ *   a non-zero exit had nothing proving the exit fires.
+ */
+const ROOT = process.cwd();
 const SRC = path.join(ROOT, 'media/source');
 const OUT = path.join(ROOT, 'public/img');
 const MANIFEST = path.join(ROOT, 'src/data/image-manifest.json');
@@ -56,7 +65,25 @@ const WEBP = { quality: 78, effort: 6 };
 const AVIF = { quality: 55, effort: 4 };
 const FORMATS = ['avif', 'webp'];
 
-const RASTER = /\.(jpe?g|png|webp|tiff?)$/i;
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+
+/*
+ * ⚠ heic/heif ARE HERE ON PURPOSE. libvips in the sharp this kit already ships
+ *   reads them — check with `node -e "console.log(require('sharp').format.heif)"`.
+ *   Leaving them out meant the single likeliest wrong format, a photo straight
+ *   off an iPhone, was discarded by our own regex while the library underneath
+ *   handled it fine. It produced no output, no warning and no manifest entry.
+ */
+const RASTER = /\.(jpe?g|png|webp|tiff?|heic|heif)$/i;
+
+/* Sources are committed forever. Output is capped by the width ladder, so a
+   huge original costs visitors nothing and costs the REPO permanently — say so
+   in those words, or someone "fixes" a page-speed problem that does not exist. */
+const BIG_PIXELS = 24_000_000;
+const BIG_BYTES = 8 * 1024 * 1024;
 
 /*
  * ── DO NOT RESET THIS TO {} ────────────────────────────────────────────────
@@ -362,11 +389,45 @@ const before = await bytes(SRC);
 console.log('optimizing media…');
 await copyBrand(files.filter((f) => f.includes(`${path.sep}brand${path.sep}`)));
 
-for (const file of files.filter((f) => RASTER.test(f))) {
+/*
+ * ⚠ THE RUN MUST NAME EVERYTHING IT DID NOT PRODUCE.
+ *
+ *   This loop used to be `files.filter(RASTER)`. Anything else was dropped with
+ *   no output, no warning and no manifest entry — so a `.heic` in media/source/
+ *   simply was not on the site, and the failure surfaced much later as <Img>
+ *   throwing "no manifest entry for …" against a file plainly sitting in the
+ *   repo. That reads as a bug in the kit rather than a rejected upload.
+ *
+ *   And there was no try/catch, so one corrupt file aborted the run midway —
+ *   after outputs were written and the manifest was partly updated, leaving the
+ *   manifest describing a state on disk that no longer matched it.
+ */
+const skipped = [];
+const failed = [];
+const oversized = [];
+
+for (const file of files) {
   if (file.includes(`${path.sep}brand${path.sep}`)) continue;
-  if (file.includes(`${path.sep}certifications${path.sep}`)) await emitSingle(file);
-  else if (file.includes(`${path.sep}blog${path.sep}`)) await emitResponsive(file, BLOG_WIDTHS);
-  else await emitResponsive(file, PHOTO_WIDTHS);
+  const rel = path.relative(SRC, file);
+
+  if (!RASTER.test(file)) {
+    skipped.push(rel);
+    continue;
+  }
+
+  try {
+    const { size } = await fs.stat(file);
+    const meta = await sharp(file).metadata();
+    if (size > BIG_BYTES || (meta.width ?? 0) * (meta.height ?? 0) > BIG_PIXELS) {
+      oversized.push(`${rel}  ${meta.width}x${meta.height}, ${mb(size)}`);
+    }
+
+    if (file.includes(`${path.sep}certifications${path.sep}`)) await emitSingle(file);
+    else if (file.includes(`${path.sep}blog${path.sep}`)) await emitResponsive(file, BLOG_WIDTHS);
+    else await emitResponsive(file, PHOTO_WIDTHS);
+  } catch (err) {
+    failed.push(`${rel}  ← ${String(err.message).split('\n')[0]}`);
+  }
 }
 
 await emitFavicons();
@@ -378,3 +439,29 @@ await fs.writeFile(MANIFEST, JSON.stringify(manifest, null, 2) + '\n');
 const after = await bytes(OUT);
 console.log(`\nsource ${mb(before)}  →  dist ${mb(after)}  (${Math.round((1 - after / before) * 100)}% smaller)`);
 console.log(`${Object.keys(manifest).length} images in manifest`);
+
+/* A report, not an error. A PDF or a .txt in media/source/ is legitimate — the
+   kit's own comp lives there — so this says what produced no image and lets the
+   reader judge. Only a genuine processing failure exits non-zero. */
+if (skipped.length) {
+  console.log(`\n${YELLOW}!${RESET} ${skipped.length} file(s) produced no image (not a raster format):`);
+  for (const f of skipped) console.log(`    ${DIM}${f}${RESET}`);
+}
+
+if (oversized.length) {
+  console.log(`\n${YELLOW}!${RESET} ${oversized.length} oversized source(s) — the SITE is unaffected:`);
+  for (const f of oversized) console.log(`    ${DIM}${f}${RESET}`);
+  console.log(
+    `    ${DIM}Output is capped by the width ladder, so visitors never download these.\n` +
+      `    The cost is the repository, which carries them forever.${RESET}`,
+  );
+}
+
+if (failed.length) {
+  console.error(`\n${RED}✗ ${failed.length} file(s) failed to process:${RESET}`);
+  for (const f of failed) console.error(`    ${f}`);
+  console.error(
+    `\n  ${DIM}Every other file was still written and the manifest is complete for them.${RESET}\n`,
+  );
+  process.exit(1);
+}

package/template/src/components/Img.astro

@@ -9,6 +9,7 @@
  * content migration.
  */
 import manifest from '../data/image-manifest.json';
+import { isPickerPath, toImageKey } from '../lib/image-key';
 
 interface Props {
   /** Manifest key, e.g. "photos/hero-home". */
@@ -36,13 +37,29 @@ const {
   style,
 } = Astro.props;
 
-const entry = (manifest as Record<string, { src: string; srcset: string; width: number; height: number; widths?: number[]; avifSrcset?: string | null }>)[name];
+/* A CMS picker returns `/img/photos/hero-1200.webp`, never `photos/hero`.
+   Normalising here is what lets an image field be a real picker instead of a
+   free-text box asking the client to type a manifest key from memory. */
+const key = toImageKey(name);
+const entry = (manifest as Record<string, { src: string; srcset: string; width: number; height: number; widths?: number[]; avifSrcset?: string | null }>)[key];
 
 if (!entry) {
   // Fail the build, not the page. A missing image is a content bug and should
   // never reach a deploy as a silently broken <img>.
+  //
+  // ⚠ THE THROWN TEXT IS PURE ASCII ON PURPOSE. The Cloudflare adapter puts a
+  //   prerender failure into the `x-astro-prerender-error` HTTP HEADER, and a
+  //   header carrying non-ASCII warns loudly and arrives mangled: an em dash
+  //   came back as `â`. Comments may use the house style; anything inside a
+  //   thrown string may not. See docs/traps.md.
   throw new Error(
-    `Img: no manifest entry for "${name}". Run \`npm run media\` after adding it to media/source/.`,
+    isPickerPath(name)
+      ? `Img: "${name}" was uploaded straight into public/img/, which is where the media pipeline ` +
+        `WRITES, so it has no responsive variants, no width/height and no manifest entry.\n\n` +
+        `Point the CMS media source at media/source/ (what the pipeline READS), re-upload, ` +
+        `then run \`npm run media\`.\n\n` +
+        `The last good deploy is still live; this change just will not appear.`
+      : `Img: no manifest entry for "${name}" (resolved to "${key}"). Run \`npm run media\` after adding it to media/source/.`,
   );
 }
 

package/template/src/lib/image-key.ts

@@ -0,0 +1,47 @@
+/**
+ * Turn a public image PATH back into the manifest KEY it came from.
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────
+ * `<Img>` resolves a manifest key — `photos/hero`. A CMS image picker cannot
+ * return one: it browses files and returns the public path of what it found,
+ * `/img/photos/hero-1200.webp`, because it has no idea a manifest exists.
+ *
+ * Without this, every image field in a CMS-managed site has to be a plain
+ * string with a description asking a non-technical editor to type a key from
+ * memory. That is not an editable field, it is a quiz — and it is why image
+ * editing was the part of the CMS that clients could never actually use.
+ *
+ * The two can meet because `optimize-media.mjs` writes exactly one shape:
+ *
+ *     /img/  +  <key>  -<width>.<ext>
+ *
+ * so the mapping back is exact rather than a guess.
+ *
+ * ── THREE PROPERTIES THAT MAKE IT SAFE ─────────────────────────────────────
+ * 1. **Which variant the editor clicks does not matter.** `-480` and `-1800`
+ *    normalise to the same key and render the identical full srcset.
+ * 2. **A key ending in a digit survives.** The width strip is anchored to the
+ *    extension, so `photos/gift-card-slider-1`, reached via `…-1-480.webp`,
+ *    comes back whole. An unanchored `-\d+` would eat the `-1`.
+ * 3. ⚠ **It must not assume `.webp`.** The kit emits AVIF alongside WebP and
+ *    social cards are `.jpg`, so the extension strip stays generic.
+ */
+
+/** `/img/photos/hero-1200.webp` → `photos/hero`. Anything else is returned as-is. */
+export const toImageKey = (nameOrPath: string): string =>
+  isPickerPath(nameOrPath)
+    ? nameOrPath
+        .replace(/^\/img\//, '')
+        .replace(/-\d+(?=\.[a-z0-9]+$)/i, '')
+        .replace(/\.[a-z0-9]+$/i, '')
+    : nameOrPath;
+
+/**
+ * Did this come from a media picker rather than being a manifest key?
+ *
+ * Used to tell an editor what actually went wrong. `/img/` is where the
+ * pipeline WRITES, so a value pointing there is either a processed variant
+ * (fine — `toImageKey` handles it) or a file uploaded straight into the output
+ * directory, which has no variants and no manifest entry at all.
+ */
+export const isPickerPath = (nameOrPath: string): boolean => nameOrPath.startsWith('/img/');