snappy-prerender 2.6.0-rc.3 → 2.7.0

package/src/cli.js

@@ -1,17 +1,10 @@
 #!/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 { createLogger } from './core/log.js';
 import { prerender } from './core/run.js';
 
@@ -30,17 +23,33 @@ Options:
       --max-depth <n>         Crawl depth limit, 0 renders roots only (default: unlimited)
       --max-routes <n>        Stop after this many routes and fail the run (default: unlimited)
       --concurrency <n>       Parallel browser pages (default: derived from CPU count)
-      --timeout <ms>          Per-route timeout (default: 30000)
+      --timeout <ms>          Per-route navigation/settle timeout (default: 30000)
+      --quiet-period <ms>     Network must be idle this long before capture (default: 500)
+      --scroll-step-delay <ms>  Delay between scroll steps (default: 100)
+      --viewport <WxH>        Browser viewport (default: 1280x720)
+      --ready-selector <sel>  Selector awaited when set
+      --ready-flag <name>     Window flag awaited when defined (default: __prerenderReady)
+      --no-headless           Run the browser visibly
       --wait-for <selector>   Wait for a selector on every route before capture
       --browser <choice>      auto | chrome | msedge | chromium | path (default: auto)
       --no-browser-download   Refuse the Chrome for Testing fallback download
       --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
       --no-verify             Skip the hydration verification pass
       --verify-changed-only   Skip verification for routes whose HTML did not change
       --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
+      --no-fail-on-error      Report route errors without failing the run
+      --fail-on-empty-page    Fail when a route renders no app content (default: on)
+      --no-fail-on-empty-page Allow an empty page and report it instead
+      --fail-on-console-error Fail when the browser logs a console error while rendering
+      --fail-on-failed-request  Fail when a same-origin request fails while rendering
+      --fail-on-duplicate-content  Fail when two routes produce identical HTML
+      --fail-on-build-origin-metadata  Fail when metadata still points at the prerender server
+      --fail-on-undetected    Fail when verification cannot find a framework root
+      --fail-on-verification-error  Fail when the verification pass cannot run
       --block-third-party     Block third-party requests while rendering
       --no-block-third-party  Allow third-party requests (the default)
       --allowed-hosts <hosts>  Third-party hosts to allow while blocking the rest, comma separated
@@ -50,7 +59,22 @@ 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)
       --user-agent <value>    User agent used while rendering (default: SnappyPrerender)
       --metadata-site-url <url>       Public site URL for canonical and og:url
@@ -58,6 +82,7 @@ Options:
       --metadata-title-template <t>   Title template, for example '%s | Example'
       --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
       --inline-css <strategy> inline | critical (critical needs the beasties package)
       --critical-css-preload <mode>  Swap for deferred CSS: none | body | media | swap | swap-high | swap-low | js | js-lazy
       --minify-html           Minify the generated HTML
@@ -69,17 +94,22 @@ Options:
       --sitemap               Write sitemap.xml from the rendered routes (needs metadata.siteUrl)
       --ignore-for-preload <names>  File names excluded from the manifest, comma separated
       --cache-ajax-requests   Expose captured JSON responses as window.snapStore
+      --max-cached-bytes <n>  Largest JSON response cached per request (default: 5242880)
       --remove-scripts        Strip every script tag from the output
       --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
+      --prune-stale-routes    Delete pages listed by the previous run's manifest
       --ignore-https-errors   Ignore TLS errors while rendering
       --browser-args <args>   Extra browser launch arguments, comma separated
       --url <url>             App URL to connect to when using --serve-cmd
       --serve-cmd <command>   Command that starts the app server instead of static serving
+      --serve-cmd-timeout <ms>  How long to wait for the command server (default: 30000)
+      --shutdown-timeout <ms>  Grace period before force-killing the server (default: 5000)
       --dry-run               Render and report without writing files
       --log-level <level>     silent | error | warn | info | debug (default: info)
       --yes, -y               Accept every default, for a shell without a terminal
@@ -105,16 +135,34 @@ async function main() {
       'max-routes': { type: 'string' },
       concurrency: { type: 'string' },
       timeout: { type: 'string' },
+      'quiet-period': { type: 'string' },
+      'scroll-step-delay': { type: 'string' },
+      'max-cached-bytes': { type: 'string' },
+      'serve-cmd-timeout': { type: 'string' },
+      'shutdown-timeout': { type: 'string' },
+      viewport: { type: 'string' },
+      'ready-flag': { type: 'string' },
+      'ready-selector': { type: 'string' },
+      headless: { type: 'boolean' },
       'wait-for': { type: 'string' },
       browser: { type: 'string' },
       'no-browser-download': { type: 'boolean' },
       'browser-download-hash': { type: 'string' },
+      'browser-download-version': { type: 'string' },
       'storage-state': { type: 'string' },
       'no-verify': { type: 'boolean' },
       'verify-changed-only': { type: 'boolean' },
       'fail-on-hydration-error': { type: 'boolean' },
+      'fail-on-error': { type: 'boolean' },
       'fail-on-rerender': { type: 'boolean' },
       'fail-on-page-error': { type: 'boolean' },
+      'fail-on-empty-page': { type: 'boolean' },
+      'fail-on-console-error': { type: 'boolean' },
+      'fail-on-failed-request': { type: 'boolean' },
+      'fail-on-duplicate-content': { type: 'boolean' },
+      'fail-on-build-origin-metadata': { type: 'boolean' },
+      'fail-on-undetected': { type: 'boolean' },
+      'fail-on-verification-error': { type: 'boolean' },
       'no-block-third-party': { type: 'boolean' },
       'block-third-party': { type: 'boolean' },
       'allowed-hosts': { type: 'string', multiple: true },
@@ -124,7 +172,22 @@ 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' },
       'user-agent': { type: 'string' },
       'metadata-site-url': { type: 'string' },
@@ -132,12 +195,14 @@ async function main() {
       'metadata-title-template': { type: 'string' },
       'metadata-default-image': { type: 'string' },
       'metadata-trailing-slash': { type: 'string' },
+      'metadata-base': { type: 'string' },
       'inline-css': { type: 'string' },
       'critical-css-preload': { type: 'string' },
       csp: { type: 'string' },
       'minify-html': { type: 'boolean' },
       'minify-css': { type: 'boolean' },
       'no-preconnect-third-party': { type: 'boolean' },
+      'preconnect-third-party': { type: 'boolean' },
       'preload-images': { type: 'boolean' },
       'preload-manifest': { type: 'boolean' },
       sitemap: { type: 'boolean' },
@@ -149,6 +214,8 @@ async function main() {
       'external-scripts': { type: 'boolean' },
       'no-remove-blobs': { type: 'boolean' },
       'remove-attributes': { type: 'string', multiple: true },
+      'no-strip-build-origin-metadata': { type: 'boolean' },
+      'prune-stale-routes': { type: 'boolean' },
       'ignore-https-errors': { type: 'boolean' },
       'browser-args': { type: 'string', multiple: true },
       url: { type: 'string' },
@@ -173,7 +240,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;
   }
 
@@ -205,18 +277,52 @@ function cliOptions({ values, positionals }) {
   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)
@@ -227,7 +333,28 @@ function cliOptions({ values, positionals }) {
   if (values.scroll) options.scrollToBottom = true;
   if (values.flat) options.flatOutput = true;
   if (values['not-found'] !== undefined) options.notFoundRoute = values['not-found'];
+  if (values['routes-file'] !== undefined) options.routesFile = values['routes-file'];
+  if (values['routes-from-sitemap'] !== undefined) {
+    options.routesFromSitemap = values['routes-from-sitemap'];
+  }
+  if (values['route-priority'] !== undefined) {
+    options.routePriority = splitList(values['route-priority']);
+  }
+  if (values.report !== undefined) options.reportPath = values.report;
+  if (values.audit !== undefined) options.audit = values.audit;
+  else if (values['no-audit']) options.audit = false;
+  if (values['fail-on-audit-error']) options.failOnAuditError = true;
+  if (values['audit-ignore-links'] !== undefined) {
+    options.auditIgnoreLinks = splitList(values['audit-ignore-links']);
+  }
+  if (values['preload-links']) options.preloadLinks = true;
+  if (values['image-sitemap']) options.imageSitemap = true;
+  if (values.framework !== undefined) options.framework = values.framework;
+  if (values.retries !== undefined) options.retries = Number(values.retries);
+  if (values['retry-delay'] !== undefined) options.retryDelay = Number(values['retry-delay']);
+  if (values['trace-on-error']) options.traceOnError = true;
   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);
@@ -241,6 +368,7 @@ function cliOptions({ values, positionals }) {
   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;
@@ -256,6 +384,8 @@ function cliOptions({ values, positionals }) {
   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;
@@ -270,161 +400,6 @@ 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 });
-}
-
-// 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 ?? '/',
-    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 }) {
-  const run = runnerCommand(detected.runner, PACKAGE_NAME);
-  const install = installCommand(detected.runner);
-  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) {
-  if (runner === 'pnpm') return `pnpm add -D ${PACKAGE_NAME}`;
-  if (runner === 'yarn') return `yarn add -D ${PACKAGE_NAME}`;
-  return `npm install --save-dev ${PACKAGE_NAME}`;
-}
-
 // Collects the metadata flags, or null when none was passed so a config file value survives.
 function metadataOptions(values) {
   const metadata = {};
@@ -441,6 +416,7 @@ function metadataOptions(values) {
   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;
 }
 
@@ -470,7 +446,22 @@ 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),
+  };
 }
 
 // Reads the package version without importing JSON, keeping Node 20 compatible.

package/src/core/artifacts.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { writeFileIfChanged } from './output.js';
+import { buildPreloadManifest } from './preload-manifest.js';
+import { toPublicPath } from './routes.js';
+import { buildSitemap, withSitemapDirective } from './sitemap.js';
+
+/**
+ * Writes the preload manifest: per route, the scripts and stylesheets the final HTML
+ * references, as Link header values a host can serve for Early Hints or HTTP headers.
+ */
+export async function writePreloadManifest({ manifestEntries, outputDir, config, log, report }) {
+  const manifest = buildPreloadManifest(manifestEntries, {
+    ignoreForPreload: config.ignoreForPreload,
+    base: config.base,
+    flatOutput: config.flatOutput,
+    trailingSlash: config.metadata?.trailingSlash,
+    notFoundRoute: config.notFoundRoute,
+  });
+  const file = 'preload-manifest.json';
+  const contents = `${JSON.stringify(manifest, null, 2)}\n`;
+  if (config.dryRun) {
+    report.files.push({ route: null, file, status: 'dry-run', bytes: Buffer.byteLength(contents) });
+    log.info(`Dry run: would write preload manifest covering ${manifest.length} route(s)`);
+    return { file, routes: manifest.length, status: 'dry-run' };
+  }
+  const written = await writeFileIfChanged({ dir: outputDir, file, contents });
+  report.files.push({ route: null, ...written });
+  log.info(
+    `${written.status === 'unchanged' ? 'Unchanged' : 'Wrote'} preload manifest covering ${manifest.length} route(s)`,
+  );
+  return { file, routes: manifest.length, status: written.status };
+}
+
+/**
+ * Writes sitemap.xml from the routes the run produced, and points an existing robots.txt at
+ * it. Every loc must be absolute, which is why the option needs metadata.siteUrl.
+ */
+export async function writeSitemap({ outputDir, config, log, report }) {
+  if (config.saveAs !== 'html') {
+    log.warn(
+      `sitemap is skipped when saveAs writes ${config.saveAs} files, as there are no pages to list`,
+    );
+    return;
+  }
+  const sitemap = buildSitemap({ files: report.files, config });
+  if (!sitemap) {
+    log.warn('sitemap is skipped: no pages were written');
+    return;
+  }
+
+  const siteUrl = config.metadata.siteUrl.replace(/\/$/, '');
+  const sitemapUrl = `${siteUrl}${toPublicPath('/sitemap.xml', config.base)}`;
+  const robots = await fs.readFile(path.join(outputDir, 'robots.txt'), 'utf8').catch(() => null);
+  const patched = robots === null ? null : withSitemapDirective(robots, sitemapUrl);
+  const names = sitemap.files.map((entry) => entry.name);
+
+  if (config.dryRun) {
+    for (const entry of sitemap.files) {
+      report.files.push({
+        route: null,
+        file: entry.name,
+        status: 'dry-run',
+        bytes: Buffer.byteLength(entry.contents),
+      });
+    }
+    report.sitemap = {
+      file: 'sitemap.xml',
+      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;
+  }
+
+  const statuses = [];
+  for (const entry of sitemap.files) {
+    const written = await writeFileIfChanged({
+      dir: outputDir,
+      file: entry.name,
+      contents: entry.contents,
+    });
+    statuses.push(written.status);
+    report.files.push({ route: null, ...written });
+  }
+  report.sitemap = {
+    file: 'sitemap.xml',
+    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)`,
+  );
+
+  if (robots === null) {
+    log.info(`Add "Sitemap: ${sitemapUrl}" to a robots.txt so crawlers find it`);
+    return;
+  }
+  if (patched !== null) {
+    const written = await writeFileIfChanged({
+      dir: outputDir,
+      file: 'robots.txt',
+      contents: patched,
+    });
+    report.files.push({ route: null, ...written });
+    log.info('Added the sitemap location to robots.txt');
+  }
+}