snappy-prerender 2.6.0 → 2.8.0

package/src/cli.js

@@ -1,17 +1,11 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import path from 'node:path';
 import process from 'node:process';
-import { createInterface } from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
-import {
-  CONFIG_FILE,
-  detectProjectDefaults,
-  PACKAGE_NAME,
-  parseRouteList,
-  renderConfigFile,
-  writeConfigFile,
-} from './core/init.js';
+import { runInit } from './cli-init.js';
+import { cliOptions } from './cli-options.js';
 import { createLogger } from './core/log.js';
 import { prerender } from './core/run.js';
 
@@ -43,8 +37,32 @@ Options:
       --browser-download-hash <sha256>  Pin the fallback download to a SHA-256 digest
       --browser-download-version <build>  Pin the Chrome for Testing build id
       --storage-state <file>  Playwright storage state for authenticated routes
+      --freeze-time <iso|build>  Fix Date/Date.now during render and verification
+      --timezone <iana>       Browser timezone for render and verification
+      --random-seed <n>       Deterministic Math.random for demo content
+      --allow-rerender <patterns>  Hydration re-renders allowed for matching routes
+      --skip-hydration <patterns>  Skip hydration verification for matching routes
+      --locale-mode <mode>    path | single (requires --locales)
+      --locales <codes>       Comma-separated locale codes, for example en,fr
+      --default-locale <code> Default locale code
+      --active-locale <code>  Active locale for single mode
+      --locale-prefix <code=prefix>  Locale path prefix, repeatable
+      --locale-url <code=url> Locale deployment origin, repeatable
+      --locale-storage-state <code=file>  Locale storage state, repeatable
+      --no-hreflang           Do not emit hreflang alternates
+      --seo-locale <code>     Seed a cookie/localStorage SEO locale
+      --seo-locale-source <source>  localStorage | cookie | both
+      --seo-locale-key <key>  localStorage key for the SEO locale
+      --seo-locale-cookie <name>  Cookie name for the SEO locale
+      --no-seo-locale-inject  Do not write the locale bootstrap into output
+      --no-seo-locale-verify  Do not seed the verification browser
+      --no-seo-locale-render  Do not seed the render browser
+      --no-seo-locale-overwrite  Only set the locale when it is missing
+      --seo-locale-navigator  Also emulate navigator.language
+      --seo-locale-force-html-lang  Override an existing html lang
       --no-verify             Skip the hydration verification pass
       --verify-changed-only   Skip verification for routes whose HTML did not change
+      --reuse-verification-context  Reuse one browser context per verification worker
       --fail-on-hydration-error  Fail the build when hydration errors are found
       --fail-on-rerender      Fail when a route re-renders instead of hydrating
       --fail-on-page-error    Fail when a page throws while it is being rendered
@@ -66,6 +84,20 @@ Options:
       --scroll                Scroll through each page to trigger lazy content
       --flat                  Write about.html instead of about/index.html
       --not-found <route>     Route emitted as 404.html (default: /404)
+      --routes-file <file>    Read route seeds from a text/JSON file
+      --routes-from-sitemap <path-or-url>  Seed routes from a local or remote sitemap
+      --route-priority <patterns>  Patterns ranked first when crawling, comma separated
+      --report <file>         Write a machine-readable run report (JSON)
+      --audit                 Check the written site for broken links and SEO issues (default: on)
+      --no-audit              Skip the site audit
+      --fail-on-audit-error   Fail when the audit finds an error
+      --audit-ignore-links <patterns>  Link patterns excluded from the audit, comma separated
+      --preload-links         Inject module, font and LCP image preload hints into each page
+      --image-sitemap         List page images in the sitemap
+      --framework <name>      auto | react | vue | svelte | preact (default: auto)
+      --retries <n>           Retry a failed render this many times (default: 0)
+      --retry-delay <ms>      Wait between render attempts (default: 500)
+      --trace-on-error        Write a Playwright trace for the final failed attempt
       --destination <dir>     Write output to another directory (default: in place)
       --clean-destination     Empty the destination before copying the build output
       --save-as <format>      html | png | jpeg (default: html)
@@ -73,6 +105,7 @@ Options:
       --metadata-site-url <url>       Public site URL for canonical and og:url
       --metadata-site-name <name>     Site name used for og:site_name
       --metadata-title-template <t>   Title template, for example '%s | Example'
+      --metadata-default-title <t>    Title used when a page sets no title
       --metadata-default-image <url>  Share image for routes without one
       --metadata-trailing-slash <mode>  preserve | always | never
       --metadata-base <path>  Base path used for absolute metadata URLs
@@ -92,7 +125,7 @@ Options:
       --remove-styles         Strip every style tag from the output
       --async-scripts         Mark external scripts async
       --external-scripts      Write injected state scripts as same-origin files, for a strict CSP
-      --csp <mode>            off | strict: strict makes the output work under script-src 'self'
+      --csp <mode>            off | strict | hash: strict for script-src 'self', hash for inline hashes
       --no-remove-blobs       Keep blob stylesheet links instead of dropping them
       --remove-attributes <names>  Drop these attributes from the output, comma separated
       --no-strip-build-origin-metadata  Keep tags that point at the prerender server
@@ -143,8 +176,32 @@ async function main() {
       'browser-download-hash': { type: 'string' },
       'browser-download-version': { type: 'string' },
       'storage-state': { type: 'string' },
+      'freeze-time': { type: 'string' },
+      timezone: { type: 'string' },
+      'random-seed': { type: 'string' },
+      'allow-rerender': { type: 'string', multiple: true },
+      'skip-hydration': { type: 'string', multiple: true },
+      'locale-mode': { type: 'string' },
+      locales: { type: 'string' },
+      'default-locale': { type: 'string' },
+      'active-locale': { type: 'string' },
+      'locale-prefix': { type: 'string', multiple: true },
+      'locale-url': { type: 'string', multiple: true },
+      'locale-storage-state': { type: 'string', multiple: true },
+      'no-hreflang': { type: 'boolean' },
+      'seo-locale': { type: 'string' },
+      'seo-locale-source': { type: 'string' },
+      'seo-locale-key': { type: 'string' },
+      'seo-locale-cookie': { type: 'string' },
+      'no-seo-locale-inject': { type: 'boolean' },
+      'no-seo-locale-verify': { type: 'boolean' },
+      'no-seo-locale-render': { type: 'boolean' },
+      'no-seo-locale-overwrite': { type: 'boolean' },
+      'seo-locale-navigator': { type: 'boolean' },
+      'seo-locale-force-html-lang': { type: 'boolean' },
       'no-verify': { type: 'boolean' },
       'verify-changed-only': { type: 'boolean' },
+      'reuse-verification-context': { type: 'boolean' },
       'fail-on-hydration-error': { type: 'boolean' },
       'fail-on-error': { type: 'boolean' },
       'fail-on-rerender': { type: 'boolean' },
@@ -165,6 +222,20 @@ async function main() {
       scroll: { type: 'boolean' },
       flat: { type: 'boolean' },
       'not-found': { type: 'string' },
+      'routes-file': { type: 'string' },
+      'routes-from-sitemap': { type: 'string' },
+      'route-priority': { type: 'string', multiple: true },
+      report: { type: 'string' },
+      audit: { type: 'boolean' },
+      'no-audit': { type: 'boolean' },
+      'fail-on-audit-error': { type: 'boolean' },
+      'audit-ignore-links': { type: 'string', multiple: true },
+      'preload-links': { type: 'boolean' },
+      'image-sitemap': { type: 'boolean' },
+      framework: { type: 'string' },
+      retries: { type: 'string' },
+      'retry-delay': { type: 'string' },
+      'trace-on-error': { type: 'boolean' },
       destination: { type: 'string' },
       'clean-destination': { type: 'boolean' },
       'save-as': { type: 'string' },
@@ -172,6 +243,7 @@ async function main() {
       'metadata-site-url': { type: 'string' },
       'metadata-site-name': { type: 'string' },
       'metadata-title-template': { type: 'string' },
+      'metadata-default-title': { type: 'string' },
       'metadata-default-image': { type: 'string' },
       'metadata-trailing-slash': { type: 'string' },
       'metadata-base': { type: 'string' },
@@ -219,7 +291,12 @@ async function main() {
     return;
   }
   if (parsed.positionals[0] === 'init') {
-    await runInit(parsed);
+    await runInit({
+      values: parsed.values,
+      flags: cliOptions({ values: parsed.values, positionals: [] }),
+      log: createLogger(parsed.values['log-level'] ?? 'info'),
+      version: readVersion(),
+    });
     return;
   }
 
@@ -228,6 +305,19 @@ async function main() {
   const options = { ...fileConfig, ...cli };
   // Metadata flags are partial: they refine a config file value instead of replacing it.
   if (cli.metadata) options.metadata = { ...(fileConfig.metadata ?? {}), ...cli.metadata };
+  if (cli.hydration) {
+    options.hydration = { ...(fileConfig.hydration ?? {}), ...cli.hydration };
+  }
+  if (cli.seoLocale) {
+    options.seoLocale = {
+      ...(fileConfig.seoLocale ?? {}),
+      ...cli.seoLocale,
+      cookie: {
+        ...(fileConfig.seoLocale?.cookie ?? {}),
+        ...(cli.seoLocale.cookie ?? {}),
+      },
+    };
+  }
   if (!options.sourceDir) options.sourceDir = 'dist';
 
   const log = createLogger(options.logLevel ?? 'info');
@@ -239,303 +329,6 @@ async function main() {
  * Translates parsed flags into prerender options, only including flags the user
  * actually passed so config-file values are never clobbered by defaults.
  */
-function cliOptions({ values, positionals }) {
-  const options = {};
-  if (positionals[0] !== undefined) options.sourceDir = positionals[0];
-  if (values.source !== undefined) options.sourceDir = values.source;
-  if (values.base !== undefined) options.base = values.base;
-  if (values.include !== undefined) options.include = splitList(values.include);
-  if (values.exclude !== undefined) options.exclude = splitList(values.exclude);
-  if (values['no-crawl']) options.crawl = false;
-  if (values['max-depth'] !== undefined) options.maxDepth = Number(values['max-depth']);
-  if (values['max-routes'] !== undefined) options.maxRoutes = Number(values['max-routes']);
-  if (values.concurrency !== undefined) options.concurrency = Number(values.concurrency);
-  if (values.timeout !== undefined) options.timeout = Number(values.timeout);
-  if (values['quiet-period'] !== undefined) options.quietPeriod = Number(values['quiet-period']);
-  if (values['scroll-step-delay'] !== undefined) {
-    options.scrollStepDelay = Number(values['scroll-step-delay']);
-  }
-  if (values['max-cached-bytes'] !== undefined) {
-    options.maxCachedBytes = Number(values['max-cached-bytes']);
-  }
-  if (values['serve-cmd-timeout'] !== undefined) {
-    options.serveCmdTimeout = Number(values['serve-cmd-timeout']);
-  }
-  if (values['shutdown-timeout'] !== undefined) {
-    options.shutdownTimeout = Number(values['shutdown-timeout']);
-  }
-  if (values.viewport !== undefined) {
-    const match = /^(\d+)x(\d+)$/i.exec(values.viewport);
-    if (!match) throw new Error('viewport must look like 1280x720');
-    options.viewport = { width: Number(match[1]), height: Number(match[2]) };
-  }
-  if (values['ready-selector'] !== undefined) options.readySelector = values['ready-selector'];
-  if (values['ready-flag'] !== undefined) options.readyFlag = values['ready-flag'];
-  if (values.headless !== undefined) options.headless = values.headless;
-  if (values['wait-for'] !== undefined) options.waitFor = values['wait-for'];
-  if (values.browser !== undefined) options.browser = values.browser;
-  if (values['no-browser-download']) options.browserDownload = false;
-  if (values['browser-download-hash'] !== undefined) {
-    options.browserDownloadHash = values['browser-download-hash'];
-  }
-  if (values['browser-download-version'] !== undefined) {
-    options.browserDownloadVersion = values['browser-download-version'];
-  }
-  if (values['storage-state'] !== undefined) options.storageState = values['storage-state'];
-  if (values['no-verify']) options.verify = false;
-  if (values['verify-changed-only']) options.verifyChangedOnly = true;
-  if (values['fail-on-hydration-error']) options.failOnHydrationError = true;
-  if (values['fail-on-rerender']) options.failOnRerender = true;
-  if (values['fail-on-page-error']) options.failOnPageError = true;
-  if (values['fail-on-error'] !== undefined) options.failOnError = values['fail-on-error'];
-  if (values['fail-on-empty-page'] !== undefined) {
-    options.failOnEmptyPage = values['fail-on-empty-page'];
-  }
-  if (values['fail-on-console-error']) options.failOnConsoleError = true;
-  if (values['fail-on-failed-request']) options.failOnFailedRequest = true;
-  if (values['fail-on-duplicate-content']) options.failOnDuplicateContent = true;
-  if (values['fail-on-build-origin-metadata']) options.failOnBuildOriginMetadata = true;
-  if (values['fail-on-undetected']) options.failOnUndetected = true;
-  if (values['fail-on-verification-error']) options.failOnVerificationError = true;
-  if (values['no-block-third-party']) options.blockThirdParty = false;
-  if (values['block-third-party']) options.blockThirdParty = true;
-  if (values['allowed-hosts'] !== undefined)
-    options.allowedHosts = splitList(values['allowed-hosts']);
-  if (values['no-freeze-animations']) options.freezeAnimations = false;
-  if (values['no-capture-runtime-styles']) options.captureRuntimeStyles = false;
-  if (values['no-capture-form-state']) options.captureFormState = false;
-  if (values.scroll) options.scrollToBottom = true;
-  if (values.flat) options.flatOutput = true;
-  if (values['not-found'] !== undefined) options.notFoundRoute = values['not-found'];
-  if (values.destination !== undefined) options.destination = values.destination;
-  if (values['clean-destination']) options.cleanDestination = true;
-  if (values['save-as'] !== undefined) options.saveAs = values['save-as'];
-  if (values['user-agent'] !== undefined) options.userAgent = values['user-agent'];
-  const metadata = metadataOptions(values);
-  if (metadata) options.metadata = metadata;
-  if (values['inline-css'] !== undefined) options.inlineCss = values['inline-css'];
-  if (values.csp !== undefined) options.csp = values.csp;
-  if (values['critical-css-preload'] !== undefined) {
-    options.criticalCssPreload =
-      values['critical-css-preload'] === 'none' ? false : values['critical-css-preload'];
-  }
-  if (values['minify-html']) options.minifyHtml = true;
-  if (values['minify-css']) options.minifyCss = true;
-  if (values['no-preconnect-third-party']) options.preconnectThirdParty = false;
-  if (values['preconnect-third-party']) options.preconnectThirdParty = true;
-  if (values['preload-images']) options.preloadImages = true;
-  if (values['preload-manifest']) options.preloadManifest = true;
-  if (values.sitemap) options.sitemap = true;
-  if (values['ignore-for-preload'] !== undefined) {
-    options.ignoreForPreload = splitList(values['ignore-for-preload']);
-  }
-  if (values['cache-ajax-requests']) options.cacheAjaxRequests = true;
-  if (values['remove-scripts']) options.removeScriptTags = true;
-  if (values['remove-styles']) options.removeStyleTags = true;
-  if (values['async-scripts']) options.asyncScriptTags = true;
-  if (values['external-scripts']) options.externalScripts = true;
-  if (values['no-remove-blobs']) options.removeBlobs = false;
-  if (values['remove-attributes'] !== undefined) {
-    options.removeAttributes = splitList(values['remove-attributes']);
-  }
-  if (values['no-strip-build-origin-metadata']) options.stripBuildOriginMetadata = false;
-  if (values['prune-stale-routes']) options.pruneStaleRoutes = true;
-  if (values['ignore-https-errors']) options.ignoreHTTPSErrors = true;
-  if (values['browser-args'] !== undefined) options.browserArgs = splitList(values['browser-args']);
-  if (values.url !== undefined) options.url = values.url;
-  if (values['serve-cmd'] !== undefined) options.serveCmd = values['serve-cmd'];
-  if (values['dry-run']) options.dryRun = true;
-  if (values['log-level'] !== undefined) options.logLevel = values['log-level'];
-  return options;
-}
-
-// Splits comma separated flag values and drops empty entries.
-function splitList(entries) {
-  return entries.flatMap((entry) => entry.split(',')).filter((entry) => entry.length > 0);
-}
-
-/**
- * Setup wizard: asks for the handful of values that decide what gets prerendered and what the
- * metadata says, then writes snappy.config.js. Flags cover every question, so
- * `snappy-prerender init --yes --metadata-site-url https://example.com` works without a
- * terminal.
- */
-async function runInit({ values }) {
-  const log = createLogger(values['log-level'] ?? 'info');
-  const cwd = process.cwd();
-  if (!values.force && fs.existsSync(CONFIG_FILE)) {
-    throw new Error(`${CONFIG_FILE} already exists; pass --force to replace it`);
-  }
-  if (!values.yes && !process.stdin.isTTY) {
-    throw new Error('init needs an interactive terminal; pass --yes to accept the defaults');
-  }
-
-  const detected = await detectProjectDefaults(cwd);
-  const flags = cliOptions({ values, positionals: [] });
-  const defaults = defaultsFromFlags(detected, flags);
-  const answers = values.yes ? defaults : await askAnswers(defaults, log);
-  const cleaned = validatedAnswers(answers, log);
-
-  await writeConfigFile({
-    dir: cwd,
-    contents: renderConfigFile(cleaned),
-    force: values.force === true,
-  });
-  log.success(`Wrote ${CONFIG_FILE}`);
-  printNextSteps({ detected, log, tag: readVersion().includes('-') ? '@next' : '' });
-}
-
-// Turns the flags the CLI already understands into the wizard's starting answers.
-function defaultsFromFlags(detected, flags) {
-  return {
-    sourceDir: flags.sourceDir ?? detected.sourceDir,
-    base: flags.base ?? detected.base ?? '/',
-    include: flags.include ?? ['/'],
-    crawl: flags.crawl ?? true,
-    siteUrl: flags.metadata?.siteUrl ?? '',
-    siteName: flags.metadata?.siteName ?? '',
-    titleTemplate: flags.metadata?.titleTemplate ?? '',
-    defaultImage: flags.metadata?.defaultImage ?? '',
-    trailingSlash: flags.metadata?.trailingSlash ?? '',
-    csp: flags.csp ?? 'off',
-    externalScripts: flags.externalScripts,
-    criticalCssPreload: flags.criticalCssPreload,
-  };
-}
-
-// Asks every question in order, closing the terminal interface whatever the outcome.
-async function askAnswers(defaults, log) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    log.info('A few questions, then a config file with only the options you set.');
-    return {
-      sourceDir: await ask(rl, 'Build output directory', defaults.sourceDir),
-      base: await ask(rl, 'Public base path', defaults.base),
-      include: parseRouteList(
-        await ask(rl, 'Routes to prerender, comma separated', defaults.include.join(',')),
-      ),
-      crawl: await askYesNo(rl, 'Follow same-origin links while rendering?', defaults.crawl),
-      siteUrl: await ask(
-        rl,
-        'Public site URL for canonical and og:url, blank to skip',
-        defaults.siteUrl,
-      ),
-      siteName: await ask(rl, 'Site name, blank to skip', defaults.siteName),
-      titleTemplate: await ask(
-        rl,
-        "Title template such as '%s | Example', blank to skip",
-        defaults.titleTemplate,
-      ),
-      csp: (await askYesNo(
-        rl,
-        "Serve a strict CSP (script-src 'self', no inline scripts)?",
-        defaults.csp === 'strict',
-      ))
-        ? 'strict'
-        : 'off',
-      defaultImage: defaults.defaultImage,
-      trailingSlash: defaults.trailingSlash,
-    };
-  } finally {
-    rl.close();
-  }
-}
-
-// Asks one question, showing the value Enter will accept.
-async function ask(rl, question, fallback) {
-  const answer = (await rl.question(`${question} (${fallback}): `)).trim();
-  return answer.length > 0 ? answer : fallback;
-}
-
-// Asks a yes/no question, treating Enter as the default.
-async function askYesNo(rl, question, fallback) {
-  const answer = (await rl.question(`${question} (${fallback ? 'Y/n' : 'y/N'}): `))
-    .trim()
-    .toLowerCase();
-  if (answer.length === 0) return fallback;
-  return answer === 'y' || answer === 'yes';
-}
-
-// Drops values that would make a broken config, so a typo becomes a warning instead.
-function validatedAnswers(answers, log) {
-  const cleaned = { ...answers };
-  if (cleaned.siteUrl && !/^https?:\/\//.test(cleaned.siteUrl)) {
-    log.warn(`ignoring site URL ${cleaned.siteUrl}: it must start with http:// or https://`);
-    cleaned.siteUrl = '';
-  }
-  if (cleaned.titleTemplate && !cleaned.titleTemplate.includes('%s')) {
-    log.warn('ignoring the title template: it has no %s placeholder');
-    cleaned.titleTemplate = '';
-  }
-  cleaned.include = parseRouteList((cleaned.include ?? ['/']).join(','));
-  return cleaned;
-}
-
-// Prints what to do next: install if needed, run it, and where the head layer goes.
-function printNextSteps({ detected, log, tag = '' }) {
-  const run = runnerCommand(detected.runner, PACKAGE_NAME);
-  const install = installCommand(detected.runner, tag);
-  log.info('');
-  log.info('Next steps:');
-  if (!detected.installed) log.info(`  Install      ${install}`);
-  log.info(`  Dry run      ${run} --dry-run`);
-  log.info(`  Prerender    ${run}`);
-  log.info('');
-  log.info('Per-route titles and meta tags come from the head layer:');
-  log.info("  import { Head } from 'snappy-prerender/head';");
-  log.info('  <Head title="Awards" description="..." image="/share/awards.png" />');
-  if (detected.usesVite) {
-    log.info('');
-    log.info('Or run it inside the build (vite.config.js):');
-    log.info("  import snappy from 'snappy-prerender';");
-    log.info('  plugins: [react(), snappy()],');
-    log.info(
-      `  ${CONFIG_FILE} is read by the snappy-prerender command, so pass the same options to snappy() too.`,
-    );
-  }
-}
-
-// Builds the command that runs a locally installed binary for the project's package runner.
-function runnerCommand(runner, binary) {
-  if (runner === 'pnpm') return `pnpm exec ${binary}`;
-  if (runner === 'yarn') return `yarn ${binary}`;
-  return `npx ${binary}`;
-}
-
-// Builds the command that installs this package as a dev dependency.
-function installCommand(runner, tag = '') {
-  const pkg = `${PACKAGE_NAME}${tag}`;
-  if (runner === 'pnpm') return `pnpm add -D ${pkg}`;
-  if (runner === 'yarn') return `yarn add -D ${pkg}`;
-  return `npm install --save-dev ${pkg}`;
-}
-
-// Collects the metadata flags, or null when none was passed so a config file value survives.
-function metadataOptions(values) {
-  const metadata = {};
-  if (values['metadata-site-url'] !== undefined) metadata.siteUrl = values['metadata-site-url'];
-  if (values['metadata-site-name'] !== undefined) {
-    metadata.siteName = values['metadata-site-name'];
-  }
-  if (values['metadata-title-template'] !== undefined) {
-    metadata.titleTemplate = values['metadata-title-template'];
-  }
-  if (values['metadata-default-image'] !== undefined) {
-    metadata.defaultImage = values['metadata-default-image'];
-  }
-  if (values['metadata-trailing-slash'] !== undefined) {
-    metadata.trailingSlash = values['metadata-trailing-slash'];
-  }
-  if (values['metadata-base'] !== undefined) metadata.base = values['metadata-base'];
-  return Object.keys(metadata).length > 0 ? metadata : null;
-}
-
-/**
- * Loads a JS config file. An explicitly requested file must exist; the implicit
- * snappy.config.js is optional. The default export is either a plain options object or an
- * async function that returns one, which is how routes are computed from a CMS, a sitemap or
- * a file listing without a separate prebuild script.
- */
 async function loadConfigFile(explicitPath) {
   if (explicitPath === undefined) {
     if (!fs.existsSync('snappy.config.js')) return {};
@@ -556,7 +349,33 @@ async function loadConfigFile(explicitPath) {
       `Config file must export a plain options object or a function returning one: ${explicitPath}`,
     );
   }
-  return loaded;
+  return resolveSourcePaths(loaded, path.dirname(path.resolve(explicitPath)));
+}
+
+// Resolves local route-source paths against the config file, not the process cwd, while
+// leaving URLs and absolute paths alone.
+function resolveSourcePaths(options, dir) {
+  const resolve = (value) => {
+    if (typeof value !== 'string' || value.length === 0) return value;
+    if (/^https?:\/\//i.test(value) || path.isAbsolute(value)) return value;
+    return path.resolve(dir, value);
+  };
+  return {
+    ...options,
+    routesFile: resolve(options.routesFile),
+    routesFromSitemap: resolve(options.routesFromSitemap),
+    ...(options.locales?.list
+      ? {
+          locales: {
+            ...options.locales,
+            list: options.locales.list.map((locale) => ({
+              ...locale,
+              storageState: resolve(locale.storageState),
+            })),
+          },
+        }
+      : {}),
+  };
 }
 
 // Reads the package version without importing JSON, keeping Node 20 compatible.

package/src/core/artifacts.js

@@ -69,6 +69,7 @@ export async function writeSitemap({ outputDir, config, log, report }) {
       routes: sitemap.routes,
       robotsUpdated: patched !== null,
       files: names,
+      locs: sitemap.locs,
     };
     log.info(`Dry run: would write ${names.join(', ')} listing ${sitemap.routes} route(s)`);
     return;
@@ -89,6 +90,7 @@ export async function writeSitemap({ outputDir, config, log, report }) {
     routes: sitemap.routes,
     robotsUpdated: patched !== null,
     files: names,
+    locs: sitemap.locs,
   };
   log.info(
     `${statuses.every((status) => status === 'unchanged') ? 'Unchanged' : 'Wrote'} ${names.join(', ')} listing ${sitemap.routes} route(s)`,

package/src/core/audit/index.js

@@ -0,0 +1,114 @@
+import { auditLinks, auditOrphans } from './links.js';
+import { auditMetadata } from './metadata.js';
+import { auditSitemap } from './sitemap.js';
+
+/**
+ * Audits the written site and returns report-only findings. Errors are the things a
+ * static site should not ship (broken links, sitemap disagreement, duplicate titles);
+ * warnings cover metadata that is useful but legitimately optional.
+ */
+export async function auditRun({ report, config, outputDir }) {
+  const errors = [];
+  const warnings = [];
+  const add = (severity, rule, message, details = {}) => {
+    const finding = { rule, severity, message, ...details };
+    if (severity === 'error') errors.push(finding);
+    else warnings.push(finding);
+  };
+
+  const pages = report.routeDetails.filter((detail) => detail.file?.endsWith('.html'));
+  auditRouteHealth({ report, add });
+  auditMetadata({ pages, config, add });
+  auditSitemap({ pages, config, report, add });
+  const linkAudit = await auditLinks({ report, config, outputDir, add });
+  auditOrphans({ pages, report, add });
+  auditCspHygiene({ pages, config, report, add });
+  removeDuplicateFindings({ errors, warnings });
+
+  return {
+    errors,
+    warnings,
+    linksChecked: linkAudit.checked,
+  };
+}
+
+// Mirrors route-level failures into the audit so failOnAuditError covers route health
+// without requiring callers to inspect a second collection.
+function auditRouteHealth({ report, add }) {
+  for (const error of report.errors ?? []) {
+    add('error', 'route-error', error.message, { route: error.route ?? undefined });
+  }
+  if (report.truncated) {
+    add(
+      'error',
+      'route-cap',
+      `maxRoutes (${report.truncated.limit}) stopped the crawl after ${report.truncated.routes} route(s)`,
+      { droppedRoutes: report.truncated.droppedRoutes ?? [] },
+    );
+  }
+  for (const route of report.emptyPages ?? []) {
+    add('error', 'empty-page', 'rendered an empty page', { route });
+  }
+  for (const group of report.duplicatePages ?? []) {
+    for (const route of group.routes) {
+      const others = group.routes.filter((other) => other !== route).join(', ');
+      add('error', 'duplicate-output', `identical output to ${others}`, { route });
+    }
+  }
+}
+
+// Inline style attributes cannot be covered by a CSP hash, and browser console errors
+// reveal assets the generated policy blocked.
+function auditCspHygiene({ pages, config, report, add }) {
+  if (config.csp !== 'hash') return;
+  for (const route of report.cspSkipped ?? []) {
+    add(
+      'warning',
+      'existing-csp-meta',
+      `${route} already has a CSP meta, so no hashes were injected`,
+      { route },
+    );
+  }
+  const violations = new Map();
+  const collect = (route, message) => {
+    if (!/content security policy|violates the following/i.test(message)) return;
+    const messages = violations.get(route) ?? new Set();
+    messages.add(message);
+    violations.set(route, messages);
+  };
+  for (const { route, message } of report.consoleErrors ?? []) collect(route, message);
+  for (const page of pages) {
+    for (const message of page.consoleErrors ?? []) collect(page.route, message);
+  }
+  for (const [route, messages] of violations) {
+    add(
+      'warning',
+      'csp-console-violation',
+      `${route} logged ${messages.size} Content-Security-Policy violation(s)`,
+      { route },
+    );
+  }
+  for (const page of pages) {
+    if (page.meta?.inlineStyleAttributes > 0) {
+      add(
+        'warning',
+        'inline-style-attributes',
+        `${page.route} has ${page.meta.inlineStyleAttributes} inline style attribute(s); CSP hashes cannot cover them`,
+        { route: page.route },
+      );
+    }
+  }
+}
+
+// A finding can be produced by more than one check; keep the first copy.
+function removeDuplicateFindings({ errors, warnings }) {
+  for (const list of [errors, warnings]) {
+    const seen = new Set();
+    for (let index = list.length - 1; index >= 0; index -= 1) {
+      const finding = list[index];
+      const key = `${finding.rule}|${finding.route ?? ''}|${finding.message}`;
+      if (seen.has(key)) list.splice(index, 1);
+      else seen.add(key);
+    }
+  }
+}