snappy-prerender 2.6.0-rc.2

package/src/core/config.js

@@ -0,0 +1,320 @@
+import fs from 'node:fs';
+import os from 'node:os';
+
+/**
+ * Upper bound applied to the derived default concurrency. Browser pages are memory
+ * heavy, so the pool is capped even on machines with many cores; users can override
+ * with the `concurrency` option.
+ */
+export const MAX_DEFAULT_CONCURRENCY = 8;
+
+const LOG_LEVELS = ['silent', 'error', 'warn', 'info', 'debug'];
+const BROWSER_CHOICES = ['auto', 'chrome', 'msedge', 'chromium'];
+const INLINE_CSS_STRATEGIES = [false, true, 'inline', 'critical'];
+const CSP_MODES = ['off', 'strict'];
+const SAVE_AS_CHOICES = ['html', 'png', 'jpeg'];
+const CRITICAL_CSS_PRELOAD = ['body', 'media', 'swap', 'swap-high', 'swap-low', 'js', 'js-lazy'];
+const NULLABLE_KEYS = [
+  'storageState',
+  'readySelector',
+  'waitFor',
+  'maxDepth',
+  'notFoundRoute',
+  'maxRoutes',
+  'userAgent',
+  'destination',
+  'browserDownloadHash',
+  'url',
+  'serveCmd',
+];
+const ARRAY_KEYS = ['include', 'exclude', 'allowedHosts', 'browserArgs', 'ignoreForPreload'];
+
+export const DEFAULTS = Object.freeze({
+  sourceDir: 'dist',
+  destination: null,
+  base: '/',
+  include: ['/'],
+  exclude: [],
+  crawl: true,
+  maxDepth: null,
+  maxRoutes: null,
+  concurrency: null,
+  timeout: 30000,
+  quietPeriod: 500,
+  scrollStepDelay: 100,
+  shutdownTimeout: 5000,
+  readyFlag: '__prerenderReady',
+  readySelector: null,
+  waitFor: null,
+  viewport: Object.freeze({ width: 1280, height: 720 }),
+  storageState: null,
+  userAgent: 'SnappyPrerender',
+  browser: 'auto',
+  browserDownload: true,
+  browserDownloadHash: null,
+  browserArgs: [],
+  headless: true,
+  ignoreHTTPSErrors: false,
+  blockThirdParty: false,
+  allowedHosts: [],
+  freezeAnimations: true,
+  scrollToBottom: false,
+  captureRuntimeStyles: true,
+  captureFormState: true,
+  saveAs: 'html',
+  csp: 'off',
+  inlineCss: false,
+  criticalCssPreload: 'media',
+  minifyHtml: false,
+  minifyCss: false,
+  removeBlobs: true,
+  removeStyleTags: false,
+  removeScriptTags: false,
+  asyncScriptTags: false,
+  externalScripts: false,
+  preconnectThirdParty: true,
+  preloadImages: false,
+  preloadManifest: false,
+  ignoreForPreload: ['service-worker.js'],
+  cacheAjaxRequests: false,
+  maxCachedBytes: 5 * 1024 * 1024,
+  flatOutput: false,
+  notFoundRoute: '/404',
+  verify: true,
+  failOnHydrationError: false,
+  failOnRerender: false,
+  failOnPageError: false,
+  metadata: null,
+  failOnError: true,
+  dryRun: false,
+  logLevel: 'info',
+  url: null,
+  serveCmd: null,
+  serveCmdTimeout: 30000,
+});
+
+// Options whose default is boolean but which accept other shapes, so their own validators
+// below decide what is allowed.
+const MULTI_TYPE_KEYS = new Set(['inlineCss', 'minifyHtml', 'minifyCss']);
+
+// Every boolean option is validated, derived from the defaults so a new flag cannot be
+// forgotten in a hand-maintained list.
+const BOOLEAN_KEYS = Object.entries(DEFAULTS)
+  .filter(([key, value]) => typeof value === 'boolean' && !MULTI_TYPE_KEYS.has(key))
+  .map(([key]) => key);
+
+/**
+ * Merges user options over defaults and normalises the values the rest of the
+ * pipeline relies on, so downstream modules never repeat coercion logic.
+ */
+export function resolveConfig(userOptions = {}) {
+  const config = { ...DEFAULTS, ...userOptions };
+  for (const key of NULLABLE_KEYS) config[key] = config[key] ?? null;
+  for (const key of ARRAY_KEYS) config[key] = toArray(config[key]);
+  config.viewport = { ...DEFAULTS.viewport, ...(userOptions.viewport ?? {}) };
+  config.base = normaliseBase(config.base);
+  config.concurrency =
+    userOptions.concurrency ??
+    Math.max(1, Math.min(os.availableParallelism(), MAX_DEFAULT_CONCURRENCY));
+  config.includeProvided = userOptions.include !== undefined;
+  // The CSP dial decides the defaults for the pieces that can move. Explicit options still
+  // win, so a project can take 'strict' and put one part back.
+  if (userOptions.externalScripts === undefined) config.externalScripts = config.csp === 'strict';
+  if (userOptions.criticalCssPreload === undefined) {
+    config.criticalCssPreload = config.csp === 'strict' ? false : 'media';
+  }
+  config.warnings = [];
+  validateConfig(config);
+  return config;
+}
+
+/**
+ * Ensures the base path always carries a leading and trailing slash so route and
+ * URL helpers can strip or append it without branching on user input shape.
+ */
+export function normaliseBase(base) {
+  if (typeof base !== 'string' || base.length === 0) {
+    throw new TypeError('base must be a non-empty string');
+  }
+  let value = base.startsWith('/') ? base : `/${base}`;
+  if (!value.endsWith('/')) value = `${value}/`;
+  return value;
+}
+
+/**
+ * Reports whether a browser option is a filesystem path rather than a channel
+ * choice. Shared by validation and browser resolution so both agree on the shape.
+ */
+export function isExecutablePath(value) {
+  return typeof value === 'string' && (value.includes('/') || value.includes('\\'));
+}
+
+// Normalises a single value or list option into an array, treating null as empty.
+function toArray(value) {
+  if (value === null || value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Fails fast on configuration mistakes before any browser or server work starts,
+ * so misconfiguration surfaces as a clear message instead of a mid-run timeout.
+ */
+export function validateConfig(config) {
+  // Validates that a pattern list only holds strings or RegExp instances.
+  const patternList = (list, name) => {
+    for (const entry of list) {
+      const valid = typeof entry === 'string' || entry instanceof RegExp;
+      if (!valid) throw new TypeError(`${name} entries must be strings or RegExp instances`);
+    }
+  };
+  // Validates that a plain list only holds strings.
+  const stringList = (list, name) => {
+    for (const entry of list) {
+      if (typeof entry !== 'string') throw new TypeError(`${name} entries must be strings`);
+    }
+  };
+  // Validates that an optional value is either absent or a string.
+  const nullableString = (key) => {
+    if (config[key] !== null && typeof config[key] !== 'string') {
+      throw new TypeError(`${key} must be a string or null`);
+    }
+  };
+  // Validates that a flag option is a real boolean.
+  const booleanOption = (key) => {
+    if (typeof config[key] !== 'boolean') throw new TypeError(`${key} must be a boolean`);
+  };
+
+  patternList(config.include, 'include');
+  patternList(config.exclude, 'exclude');
+  stringList(config.allowedHosts, 'allowedHosts');
+  stringList(config.browserArgs, 'browserArgs');
+  stringList(config.ignoreForPreload, 'ignoreForPreload');
+  for (const key of ['readyFlag', 'readySelector', 'waitFor', 'notFoundRoute']) nullableString(key);
+  for (const key of ['userAgent', 'destination']) nullableString(key);
+  for (const key of BOOLEAN_KEYS) booleanOption(key);
+
+  if (config.browserDownloadHash !== null && !/^[a-f0-9]{64}$/i.test(config.browserDownloadHash)) {
+    throw new TypeError('browserDownloadHash must be a 64 character SHA-256 hex digest');
+  }
+
+  if (!Number.isInteger(config.concurrency) || config.concurrency < 1) {
+    throw new TypeError('concurrency must be a positive integer');
+  }
+  for (const key of [
+    'timeout',
+    'quietPeriod',
+    'scrollStepDelay',
+    'shutdownTimeout',
+    'serveCmdTimeout',
+  ]) {
+    if (!Number.isFinite(config[key]) || config[key] <= 0) {
+      throw new TypeError(`${key} must be a positive number of milliseconds`);
+    }
+  }
+  if (config.maxDepth !== null && (!Number.isInteger(config.maxDepth) || config.maxDepth < 0)) {
+    throw new TypeError('maxDepth must be null or a non-negative integer');
+  }
+  if (config.maxRoutes !== null && (!Number.isInteger(config.maxRoutes) || config.maxRoutes < 1)) {
+    throw new TypeError('maxRoutes must be null or a positive integer');
+  }
+  if (!Number.isFinite(config.maxCachedBytes) || config.maxCachedBytes <= 0) {
+    throw new TypeError('maxCachedBytes must be a positive number of bytes');
+  }
+  for (const key of ['width', 'height']) {
+    if (!Number.isInteger(config.viewport[key]) || config.viewport[key] < 1) {
+      throw new TypeError(`viewport.${key} must be a positive integer`);
+    }
+  }
+  if (!LOG_LEVELS.includes(config.logLevel)) {
+    throw new TypeError(`logLevel must be one of: ${LOG_LEVELS.join(', ')}`);
+  }
+  if (!BROWSER_CHOICES.includes(config.browser) && !isExecutablePath(config.browser)) {
+    throw new TypeError(
+      `browser must be one of: ${BROWSER_CHOICES.join(', ')} or a path to an executable`,
+    );
+  }
+  if (config.storageState !== null) {
+    if (typeof config.storageState !== 'string' || !fs.existsSync(config.storageState)) {
+      throw new TypeError('storageState must point to an existing Playwright storage state file');
+    }
+  }
+  if (config.serveCmd !== null && !config.url) {
+    throw new TypeError(
+      'url is required when serveCmd is set, so the crawler knows where to connect',
+    );
+  }
+  if (config.url !== null && !/^https?:\/\//.test(config.url)) {
+    throw new TypeError('url must be an absolute http(s) URL');
+  }
+  if (!INLINE_CSS_STRATEGIES.includes(config.inlineCss)) {
+    throw new TypeError("inlineCss must be false, true, 'inline' or 'critical'");
+  }
+  if (!CSP_MODES.includes(config.csp)) {
+    throw new TypeError(`csp must be one of: ${CSP_MODES.join(', ')}`);
+  }
+  if (
+    config.criticalCssPreload !== false &&
+    !CRITICAL_CSS_PRELOAD.includes(config.criticalCssPreload)
+  ) {
+    throw new TypeError(
+      `criticalCssPreload must be false or one of: ${CRITICAL_CSS_PRELOAD.join(', ')}`,
+    );
+  }
+  for (const key of ['minifyHtml', 'minifyCss']) {
+    const value = config[key];
+    const valid =
+      typeof value === 'boolean' ||
+      (typeof value === 'object' && value !== null && !Array.isArray(value));
+    if (!valid) throw new TypeError(`${key} must be a boolean or an options object`);
+  }
+  if (!SAVE_AS_CHOICES.includes(config.saveAs)) {
+    throw new TypeError(`saveAs must be one of: ${SAVE_AS_CHOICES.join(', ')}`);
+  }
+  validateMetadata(config);
+}
+
+// The metadata keys the head component reads, so a typo is reported instead of ignored.
+const METADATA_KEYS = new Set([
+  'siteUrl',
+  'siteName',
+  'titleTemplate',
+  'defaultImage',
+  'trailingSlash',
+  'base',
+]);
+
+/**
+ * Validates the defaults handed to the head component, so a typo surfaces at config time
+ * rather than as metadata that silently points at the build server.
+ */
+function validateMetadata(config) {
+  const metadata = config.metadata;
+  if (metadata === null) return;
+  if (typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new TypeError('metadata must be null or an options object');
+  }
+  for (const key of Object.keys(metadata)) {
+    if (!METADATA_KEYS.has(key)) throw new TypeError(`metadata.${key} is not a recognised option`);
+  }
+  for (const key of METADATA_KEYS) {
+    const value = metadata[key];
+    if (value !== undefined && value !== null && typeof value !== 'string') {
+      throw new TypeError(`metadata.${key} must be a string`);
+    }
+  }
+  if (metadata.siteUrl && !/^https?:\/\//.test(metadata.siteUrl)) {
+    throw new TypeError('metadata.siteUrl must be an absolute http(s) URL');
+  }
+  if (metadata.base && !metadata.base.startsWith('/')) {
+    throw new TypeError('metadata.base must start with a slash, for example /app/');
+  }
+  if (metadata.trailingSlash && !['preserve', 'always', 'never'].includes(metadata.trailingSlash)) {
+    throw new TypeError("metadata.trailingSlash must be 'preserve', 'always' or 'never'");
+  }
+  if (metadata.titleTemplate && !metadata.titleTemplate.includes('%s')) {
+    config.warnings ??= [];
+    config.warnings.push(
+      'metadata.titleTemplate has no %s placeholder, so the title is left as the page set it',
+    );
+  }
+}

package/src/core/destination.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Prepares the directory the run writes into. When a destination is configured the
+ * built output is copied there first, so assets are present next to the generated
+ * HTML and the source directory stays untouched. An existing destination is reported
+ * before it is overwritten, and entries that cannot be copied are counted.
+ */
+export async function prepareDestination({ sourceDir, destination, log }) {
+  if (!destination || path.resolve(destination) === path.resolve(sourceDir)) {
+    return sourceDir;
+  }
+  const existing = await fs.readdir(destination).catch(() => []);
+  if (existing.length > 0) {
+    log?.warn(
+      `destination ${destination} is not empty (${existing.length} entries); existing files may be overwritten`,
+    );
+  }
+  const skipped = await copyTree(sourceDir, destination);
+  if (skipped > 0) {
+    log?.warn(`skipped ${skipped} non-file entr(ies) while copying ${sourceDir} to ${destination}`);
+  }
+  log?.debug(`copied ${sourceDir} to ${destination}`);
+  return destination;
+}
+
+/**
+ * Recursively copies a directory tree. Implemented directly rather than with
+ * fs.cp so behaviour does not depend on an experimental Node API. Returns how many
+ * entries were skipped because they are neither files nor directories, such as symlinks.
+ */
+async function copyTree(source, target) {
+  await fs.mkdir(target, { recursive: true });
+  const entries = await fs.readdir(source, { withFileTypes: true });
+  let skipped = 0;
+  for (const entry of entries) {
+    const from = path.join(source, entry.name);
+    const to = path.join(target, entry.name);
+    if (entry.isDirectory()) skipped += await copyTree(from, to);
+    else if (entry.isFile()) await fs.copyFile(from, to);
+    else skipped += 1;
+  }
+  return skipped;
+}

package/src/core/form-state.js

@@ -0,0 +1,23 @@
+/**
+ * Syncs live form control state into markup attributes. React writes checked and
+ * selected as DOM properties, which do not survive serialisation, so a prerendered
+ * checkbox or select would come back in its default state until the bundle hydrates.
+ * The result matches what React's own server rendering emits for controlled inputs.
+ */
+export async function captureFormState(page) {
+  await page.evaluate(() => {
+    // Writes or clears an attribute so the serialised markup matches the live DOM.
+    const syncAttribute = (element, attribute, enabled) => {
+      if (enabled) element.setAttribute(attribute, '');
+      else element.removeAttribute(attribute);
+    };
+
+    const choices = document.querySelectorAll('input[type="radio" i], input[type="checkbox" i]');
+    for (const control of choices) {
+      syncAttribute(control, 'checked', control.checked);
+    }
+    for (const option of document.querySelectorAll('option')) {
+      syncAttribute(option, 'selected', option.selected);
+    }
+  });
+}

package/src/core/index.js

@@ -0,0 +1,2 @@
+export { DEFAULTS, resolveConfig } from './config.js';
+export { prerender } from './run.js';

package/src/core/init.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normaliseRoute } from './routes.js';
+
+export const CONFIG_FILE = 'snappy.config.js';
+export const PACKAGE_NAME = 'snappy-prerender';
+
+const VITE_CONFIGS = ['vite.config.js', 'vite.config.mjs', 'vite.config.cjs', 'vite.config.ts'];
+const METADATA_KEYS = ['siteUrl', 'siteName', 'titleTemplate', 'defaultImage', 'trailingSlash'];
+const RUNNERS = [
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npm'],
+];
+
+/**
+ * Reads what the project already says about itself: the framework that decides the build
+ * directory, whether Vite is in use, which package runner it uses, and whether this package
+ * is already a dependency.
+ */
+export async function detectProjectDefaults(dir = process.cwd()) {
+  const manifest = await readJson(path.join(dir, 'package.json'));
+  const dependencies = { ...manifest?.dependencies, ...manifest?.devDependencies };
+  const usesVite = Boolean(dependencies.vite) || (await anyExists(dir, VITE_CONFIGS));
+  const usesCreateReactApp = Boolean(dependencies['react-scripts']) && !usesVite;
+  return {
+    sourceDir: usesCreateReactApp ? 'build' : 'dist',
+    usesVite,
+    runner: await detectRunner(dir),
+    installed: PACKAGE_NAME in dependencies,
+  };
+}
+
+/**
+ * Normalises a comma separated route list into include patterns, keeping wildcards as the
+ * user wrote them and falling back to the root route so the config always renders something.
+ */
+export function parseRouteList(input) {
+  const routes = String(input ?? '')
+    .split(',')
+    .map((route) => route.trim())
+    .filter((route) => route.length > 0)
+    .map((route) => (route.includes('*') ? route : normaliseRoute(route)));
+  return routes.length > 0 ? routes : ['/'];
+}
+
+/**
+ * Renders the config file for the wizard's answers, writing only the options the answers
+ * actually set so every line in the file does something.
+ */
+export function renderConfigFile(answers = {}) {
+  const lines = [
+    '// Created by `snappy-prerender init`. Every option is documented in the snappy-prerender README.',
+    'export default {',
+    `  sourceDir: ${quote(answers.sourceDir ?? 'dist')},`,
+  ];
+  if (answers.base && answers.base !== '/') lines.push(`  base: ${quote(answers.base)},`);
+  // A supplied include list acts as an allowlist, so writing the default would stop discovery.
+  // It is only written when the answer actually narrows the set of routes.
+  const include = parseRouteList((answers.include ?? ['/']).join(','));
+  const includeIsDefault = include.length === 1 && include[0] === '/';
+  if (!includeIsDefault) lines.push(`  include: [${include.map(quote).join(', ')}],`);
+  if (answers.crawl === false) lines.push('  crawl: false,');
+  // The CSP dial and the parts it was tuned with, so a strict-CSP project keeps the choice.
+  if (answers.csp === 'strict') lines.push('  csp: "strict",');
+  if (answers.externalScripts === true) lines.push('  externalScripts: true,');
+  if (answers.criticalCssPreload !== undefined && answers.criticalCssPreload !== 'media') {
+    // A boolean stays a literal; a mode name is quoted.
+    const value =
+      typeof answers.criticalCssPreload === 'boolean'
+        ? String(answers.criticalCssPreload)
+        : quote(answers.criticalCssPreload);
+    lines.push(`  criticalCssPreload: ${value},`);
+  }
+
+  const metadata = METADATA_KEYS.filter((key) => answers[key]).map((key) => [key, answers[key]]);
+  if (metadata.length > 0) {
+    lines.push('  metadata: {');
+    for (const [key, value] of metadata) lines.push(`    ${key}: ${quote(value)},`);
+    lines.push('  },');
+  }
+
+  lines.push('};', '');
+  return lines.join('\n');
+}
+
+/**
+ * Writes the config file into the project, refusing to replace an existing one unless the
+ * caller asked for it, so a wizard run can never silently destroy hand-written settings.
+ */
+export async function writeConfigFile({ dir, contents, force = false }) {
+  const target = path.join(dir, CONFIG_FILE);
+  if (!force && (await exists(target))) {
+    throw new Error(`${CONFIG_FILE} already exists; pass --force to replace it`);
+  }
+  await fs.writeFile(target, contents, 'utf8');
+  return target;
+}
+
+// Quotes a string for the generated module.
+function quote(value) {
+  return JSON.stringify(String(value));
+}
+
+// Reads a JSON file, treating a missing or malformed file as absent.
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Reports whether any of the given file names exists in the directory.
+async function anyExists(dir, names) {
+  for (const name of names) {
+    if (await exists(path.join(dir, name))) return true;
+  }
+  return false;
+}
+
+// Reports whether a path exists.
+async function exists(target) {
+  return fs
+    .stat(target)
+    .then(() => true)
+    .catch(() => false);
+}
+
+// Detects the package runner from the lockfile, defaulting to npm.
+async function detectRunner(dir) {
+  for (const [lockfile, runner] of RUNNERS) {
+    if (await exists(path.join(dir, lockfile))) return runner;
+  }
+  return 'npm';
+}

package/src/core/inline-css.js

@@ -0,0 +1,67 @@
+import { minifyCss } from './minify.js';
+
+/**
+ * Inlines every same-origin stylesheet the page loaded, replacing the links with a
+ * single style tag. Blob-backed stylesheets work too because the text is read from
+ * the live page. Stylesheets that cannot be fetched are left in place.
+ */
+export async function inlineStylesheets({ page, minifyCssOptions }) {
+  const collected = await page.evaluate(async () => {
+    // Only media that applies on screen can be inlined without changing how the sheet
+    // applies, so a print stylesheet is left as a link instead of becoming active.
+    const INLINEABLE_MEDIA = new Set(['', 'all', 'screen']);
+    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
+    const parts = [];
+    const skipped = [];
+    for (const link of links) {
+      const media = (link.getAttribute('media') ?? '').trim().toLowerCase();
+      if (!INLINEABLE_MEDIA.has(media)) {
+        skipped.push(link.href);
+        continue;
+      }
+      try {
+        const response = await fetch(link.href);
+        if (!response.ok) throw new Error(String(response.status));
+        parts.push(await response.text());
+        link.remove();
+      } catch {
+        skipped.push(link.href);
+      }
+    }
+    return { css: parts.join('\n'), skipped };
+  });
+
+  if (collected.css.trim().length === 0) return { skipped: collected.skipped };
+  const css = minifyCssOptions ? minifyCss(collected.css, minifyCssOptions) : collected.css;
+  await page.evaluate((text) => {
+    const style = document.createElement('style');
+    style.textContent = text;
+    document.head.appendChild(style);
+  }, css);
+  return { skipped: collected.skipped };
+}
+
+/**
+ * Inlines only the above-the-fold CSS and defers the rest, using beasties. It runs
+ * on the serialised HTML in Node, reading stylesheets from the output directory.
+ * beasties is an optional peer dependency because most projects never need it.
+ * `preload` is passed through so a strict script-src can turn the swap handlers off.
+ */
+export async function inlineCriticalCss({ html, outputDir, base, preload = 'media' }) {
+  let Beasties;
+  try {
+    ({ default: Beasties } = await import('beasties'));
+  } catch {
+    throw new Error(
+      "inlineCss: 'critical' needs the optional beasties dependency. Install it with: npm install beasties",
+    );
+  }
+  const beasties = new Beasties({
+    path: outputDir,
+    publicPath: base,
+    logLevel: 'silent',
+    preload,
+    noscriptFallback: true,
+  });
+  return beasties.process(html);
+}

package/src/core/log.js

@@ -0,0 +1,45 @@
+import { styleText } from 'node:util';
+
+const LEVEL_RANK = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+
+/**
+ * Colour helper that disables ANSI output when the target stream is not a TTY or
+ * when NO_COLOR is set. FORCE_COLOR=1 forces colour, FORCE_COLOR=0 disables it.
+ */
+function paint(stream, format, text) {
+  const forced = process.env.FORCE_COLOR;
+  if (forced === '0') return text;
+  const enabled = forced ? true : Boolean(stream.isTTY) && !process.env.NO_COLOR;
+  if (!enabled) return text;
+  return styleText(format, text);
+}
+
+/**
+ * Progress logger for long prerender runs. Writes to stdout/stderr only; the tool
+ * intentionally keeps no log files because it is a build step, not a service.
+ */
+export function createLogger(level = 'info') {
+  const rank = LEVEL_RANK[level] ?? LEVEL_RANK.info;
+  // Emits one coloured line to the requested stream.
+  const write = (target, format, message) => {
+    target.write(`${paint(target, format, message)}\n`);
+  };
+  return {
+    level,
+    debug(message) {
+      if (rank >= LEVEL_RANK.debug) write(process.stdout, 'dim', message);
+    },
+    info(message) {
+      if (rank >= LEVEL_RANK.info) write(process.stdout, 'cyan', message);
+    },
+    warn(message) {
+      if (rank >= LEVEL_RANK.warn) write(process.stderr, 'yellow', message);
+    },
+    error(message) {
+      if (rank >= LEVEL_RANK.error) write(process.stderr, 'red', message);
+    },
+    success(message) {
+      if (rank >= LEVEL_RANK.info) write(process.stdout, 'green', message);
+    },
+  };
+}

package/src/core/metadata-origin.js

@@ -0,0 +1,39 @@
+const BUILD_ORIGIN = /https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?/gi;
+
+/**
+ * Recognises the metadata tags whose value is an absolute URL, and finds URLs pointing at a
+ * local build server inside them. Dependency-free on purpose, so the browser-side head entry
+ * can share the same pattern instead of shipping a second copy of it.
+ */
+export function isMetadataUrlNode(node) {
+  if (node.tagName === 'link') return attributeValue(node, 'rel').toLowerCase() === 'canonical';
+  if (node.tagName !== 'meta') return false;
+  return isUrlKey(attributeValue(node, 'property') || attributeValue(node, 'name'));
+}
+
+// Reads the URL a metadata tag carries.
+export function metadataUrlValue(node) {
+  return node.tagName === 'link' ? attributeValue(node, 'href') : attributeValue(node, 'content');
+}
+
+/**
+ * Collects the build server origins a value points at, de-duplicated and capped so one long
+ * value cannot flood a warning.
+ */
+export function collectBuildOrigins(text, limit = 3) {
+  const matches = String(text ?? '').match(BUILD_ORIGIN) ?? [];
+  return [...new Set(matches)].slice(0, limit);
+}
+
+// Reports whether a meta key names a URL, such as og:url, og:image or twitter:image.
+function isUrlKey(key) {
+  const [prefix, ...rest] = key.toLowerCase().split(':');
+  if (prefix !== 'og' && prefix !== 'twitter') return false;
+  const last = rest.at(-1);
+  return last === 'url' || last === 'image';
+}
+
+// Reads an attribute value, defaulting to an empty string.
+function attributeValue(node, name) {
+  return node.attrs?.find((attribute) => attribute.name === name)?.value ?? '';
+}