@nutin/cli 1.3.0 → 2.0.0

package/templates/{features/i18n/tools/builder/core → base/tools/builder/core/i18n}/build-i18n.js.hbs

@@ -1,8 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { exit } from 'process';
-import { getFilesRecursive, print, isVerbose } from '../../utils/index.js';
-import { PATHS } from './paths.js';
+import { getFilesRecursive, print, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
 
 const destDir = path.join(PATHS.tempSource, 'locales');
 
@@ -50,7 +49,7 @@ async function removeJsonFiles(directory) {
   try {
     await fs.promises.access(directory);
   } catch {
-    print.info(`Directory ${directory} does not exist, skipping cleanup`);
+    print.grayError(`Directory ${directory} does not exist, skipping cleanup`);
     return;
   }
   
@@ -60,19 +59,13 @@ async function removeJsonFiles(directory) {
     if (file.includes(`${path.sep}locales${path.sep}`)) {
       try {
         await fs.promises.unlink(file);
-        if (isVerbose) print.info(`Deleted locale JSON file: ${file}`);
       } catch (err) {
         print.error(`Failed to remove ${file}: ${err.message}`);
       }
-    } 
-    else if (isVerbose) {
-      print.info(`Skipping non-locale JSON file: ${file}`);
     }
   }
 
   await removeEmptyDirectories(directory);
-
-  if (isVerbose) print.boldInfo(`JSON files cleanup complete.`);
 }
 
 async function removeEmptyDirectories(directory) {
@@ -102,10 +95,9 @@ async function removeEmptyDirectories(directory) {
       const updatedItems = await fs.promises.readdir(directory);
       if (updatedItems.length === 0) {
         await fs.promises.rmdir(directory, { recursive: false });
-        if (isVerbose) print.info(`📁 Removed empty directory: ${directory}`);
       }
     } catch (err) {
-      print.error(`Failed to remove empty directory ${directory}: ${err.message}`);
+      print.grayError(`Failed to remove empty directory ${directory}: ${err.message}`);
     }
   }
 }
@@ -114,19 +106,16 @@ async function mergeJson() {
   if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
 
   const localeFilesMap = findLocaleFiles();
-
   for (const [locale, files] of Object.entries(localeFilesMap)) {
     const combined = combineJsonFiles(files);
     fs.writeFileSync(
       `${destDir}/${locale}.json`,
       JSON.stringify(combined, null, 2)
     );
-    if (isVerbose) print.boldInfo(`Json files for locale ${locale} merged successfully`);
   }
-  removeJsonFiles(PATHS.tempApp);
+  await removeJsonFiles(PATHS.tempApp);
 }
 
 mergeJson().catch((err) => {
-  print.boldError(`Unexpected error: ${err.message}`);
-  exit(1);
+  errorExit(err)
 });

package/templates/base/tools/builder/core/prod-bundle/compress-files.js.hbs

@@ -0,0 +1,37 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { gzipSync, brotliCompressSync, constants } from 'zlib';
+import { print, getFilesRecursive, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+
+function compressStaticAssets() {
+  const files = getFilesRecursive(
+    PATHS.tempSource,
+    ['.js', '.css', '.json', '.svg', '.ttf', '.otf', '.eot']
+  );
+  
+  for (const file of files) {
+    const content = readFileSync(file);
+
+    const gzipped = gzipSync(content, {
+      level: 9,
+      memLevel: 9,
+      windowBits: 15
+    });
+    writeFileSync(`${file}.gz`, gzipped);
+    
+    const brotlied = brotliCompressSync(content, {
+      params: {
+        [constants.BROTLI_PARAM_QUALITY]: 11,
+        [constants.BROTLI_PARAM_MODE]: constants.BROTLI_MODE_GENERIC,
+        [constants.BROTLI_PARAM_SIZE_HINT]: content.length
+      }
+    });
+    writeFileSync(`${file}.br`, brotlied);
+  };
+}
+
+try {
+  compressStaticAssets()
+} catch(err) {
+  errorExit(err, 'compress-files');
+}

package/templates/base/tools/builder/core/prod-bundle/esbuild.js.hbs

@@ -0,0 +1,30 @@
+import esbuild from 'esbuild';
+import path from 'path';
+import { print, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+import { builderConfig } from '../../builder.config.js';
+
+const ENTRY_FILE = path.join(PATHS.tempApp, 'main.ts');
+const OUT_FILE = path.join(PATHS.tempSource, 'bundle.js');
+
+async function build() {
+  await esbuild.build({
+    ...builderConfig.esbuild,
+    platform: 'browser',
+    format: 'esm',
+    legalComments: 'none',
+    loader: {
+      '.json': 'json',
+    },
+    define: {
+      'process.env.NODE_ENV': '"production"',
+    },
+    entryPoints: [ENTRY_FILE],
+    outfile: OUT_FILE,
+    keepNames: false,
+  });
+}
+
+build().catch((err) => {
+  errorExit(err, 'esbuild');
+});

package/templates/base/tools/builder/core/{hash-files.js.hbs → prod-bundle/hash-files.js.hbs}

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
-import { PATHS } from './paths.js';
-import { print, isVerbose, getFilesRecursive } from '../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+import { print, getFilesRecursive, errorExit } from '../../../utils/index.js';
 
 function addHashToFiles(distDir) {
   const files = getFilesRecursive(distDir, ['.js', '.css']);
@@ -24,10 +24,6 @@ function addHashToFiles(distDir) {
     const newRel = path.relative(distDir, newPath).replace(/\\/g, '/');
 
     fileMap[oldRel] = newRel;
-
-    if (isVerbose) {
-      print.info(`Renamed: ${oldRel} → ${newRel}`);
-    }
   });
 
   updateHtmlReferences(path.join(distDir, 'index.html'), fileMap);
@@ -38,15 +34,22 @@ function hashFile(filePath) {
   return crypto.createHash('sha256').update(content).digest('hex').substring(0, 8);
 }
 
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 function updateHtmlReferences(htmlPath, fileMap) {
   let html = fs.readFileSync(htmlPath, 'utf8');
-  
+
   Object.entries(fileMap).forEach(([oldName, newName]) => {
-    html = html.replace(new RegExp(oldName, 'g'), newName);
+    html = html.replace(new RegExp(escapeRegExp(oldName), 'g'), newName);
   });
-  
+
   fs.writeFileSync(htmlPath, html);
-  if (isVerbose) print.info('Updated index.html references');
 }
 
-addHashToFiles(PATHS.tempSource);
+try {
+  addHashToFiles(PATHS.tempSource)
+} catch(err) {
+  errorExit(err, 'hash-files');
+}

package/templates/base/tools/builder/core/seo/generate-robots-txt.js.hbs

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import { PATHS } from '../app/paths.js';
+import { print } from '../../../utils/index.js';
+
+export function generateRobotsTxt() {
+  const seoConfigPath = path.join(PATHS.temp, 'config', 'seo.json');
+  const seoConfig = JSON.parse(fs.readFileSync(seoConfigPath, 'utf-8'));
+  const baseUrl = seoConfig.baseUrl.replace(/\/$/, '');
+  const routes = seoConfig.routes ?? [];
+  const disallowBots = seoConfig.disallowBots ?? [];
+
+  // Paths disallowed for all bots (disallow: true)
+  const globalDisallows = routes
+    .filter(r => r.disallow === true)
+    .map(r => `Disallow: ${r.path}`);
+
+  // Paths disallowed per named bot: { botName -> [path, ...] }
+  const perBotDisallows = {};
+  for (const r of routes) {
+    if (!Array.isArray(r.disallow)) continue;
+    for (const bot of r.disallow) {
+      (perBotDisallows[bot] ??= []).push(r.path);
+    }
+  }
+  // Bots that are fully blocked contribute an empty-path disallow
+  for (const bot of disallowBots) {
+    perBotDisallows[bot] ??= [];
+  }
+
+  const lines = [
+    'User-agent: *',
+    'Allow: /',
+    ...globalDisallows,
+  ];
+
+  for (const [bot, paths] of Object.entries(perBotDisallows)) {
+    lines.push('');
+    lines.push(`User-agent: ${bot}`);
+    if (paths.length > 0) {
+      for (const p of paths) lines.push(`Disallow: ${p}`);
+    } else {
+      lines.push('Disallow: /');
+    }
+  }
+
+  lines.push('', `Sitemap: ${baseUrl}/sitemap.xml`);
+
+  const outputPath = path.join(PATHS.tempSource, 'robots.txt');
+  fs.writeFileSync(outputPath, lines.join('\n') + '\n', 'utf-8');
+}

package/templates/base/tools/builder/core/seo/generate-seo-files.js.hbs

@@ -0,0 +1,16 @@
+import { print, errorExit } from '../../../utils/index.js';
+import { generateSeoHtml } from './generate-seo-html.js';
+import { generateRobotsTxt } from './generate-robots-txt.js';
+import { generateSitemapXml } from './generate-sitemap-xml.js';
+
+async function generateSeoFiles() {
+  await generateSeoHtml();
+  generateRobotsTxt();
+  generateSitemapXml();
+}
+
+try {
+  await generateSeoFiles();
+} catch (err) {
+  errorExit(err, 'generate-seo-files');
+}

package/templates/base/tools/builder/core/seo/generate-seo-html.js.hbs

@@ -0,0 +1,128 @@
+import fs from 'fs';
+import path from 'path';
+import { PATHS } from '../app/paths.js';
+import { print, errorExit } from '../../../utils/index.js';
+import { buildSsrBundle, cleanupSsrBundle } from './ssr/ssr-bundle.js';
+import { renderRoute } from './ssr/ssr-render.js';
+import { builderConfig } from '../../builder.config.js';
+import { resolveLocaleValue, valueForLangWithFallback, collectI18nSeoIssues } from './i18n-resolution.js';
+import { segmentsOf, validateMockParams, writeRouteHtml, warnForRoutesMissingSeoConfig } from './route-output.js';
+
+async function processRoute(template, baseUrl, defaultLanguage, languages, route, bundleUrl) {
+  validateMockParams(route);
+
+  const routeSuffix = route.path === '/' ? '' : route.path;
+
+  if (builderConfig.i18n) {
+    for (const lang of languages) {
+      const title = valueForLangWithFallback(route.title, lang, defaultLanguage);
+      const description = valueForLangWithFallback(route.description, lang, defaultLanguage);
+      const ogImage = valueForLangWithFallback(route.ogImage, lang, defaultLanguage);
+
+      const pageUrl = `${baseUrl}/${lang}${routeSuffix}`;
+      const body = await renderRoute({
+        bundleUrl,
+        appRoutesKey: route.path,
+        mockParams: route.mockParams,
+        mockFetch: route.mockFetch,
+        lang,
+        pageUrl,
+        i18nEnabled: builderConfig.i18n,
+      });
+
+      await writeRouteHtml({
+        template, lang, title, description, pageUrl, ogImage, body,
+        outputSegments: [lang, ...segmentsOf(routeSuffix)],
+        routePath: route.path,
+      });
+    }
+  } else {
+    const title = resolveLocaleValue(route.title, defaultLanguage);
+    const description = resolveLocaleValue(route.description, defaultLanguage);
+    const ogImage = resolveLocaleValue(route.ogImage, defaultLanguage);
+
+    if (!title || !description) {
+      errorExit(`Missing title or description for route "${route.path}" in seo.json`, 'generate-seo-html');
+    }
+
+    const pageUrl = `${baseUrl}${routeSuffix}`;
+    const body = await renderRoute({
+      bundleUrl,
+      appRoutesKey: route.path,
+      mockParams: route.mockParams,
+      mockFetch: route.mockFetch,
+      lang: defaultLanguage,
+      pageUrl,
+      i18nEnabled: builderConfig.i18n,
+    });
+
+    await writeRouteHtml({
+      template, lang: defaultLanguage, title, description, pageUrl, ogImage, body,
+      outputSegments: segmentsOf(routeSuffix),
+      routePath: route.path,
+    });
+  }
+}
+
+export async function generateSeoHtml() {
+  const templatePath = path.join(PATHS.tempSource, 'index.html');
+  const template = fs.readFileSync(templatePath, 'utf-8');
+
+  if (!template.includes('</head>')) {
+    errorExit('index.html is missing a </head> tag — cannot inject SEO tags', 'generate-seo-html');
+  }
+
+  const seoConfigPath = path.join(PATHS.temp, 'config', 'seo.json');
+  const seoConfig = JSON.parse(fs.readFileSync(seoConfigPath, 'utf-8'));
+  const baseUrl = seoConfig.baseUrl.replace(/\/$/, '');
+
+  const languagesConfigPath = path.join(PATHS.temp, 'config', 'languages.json');
+  const { languages, defaultLanguage } = JSON.parse(fs.readFileSync(languagesConfigPath, 'utf-8'));
+
+  if (builderConfig.i18n) {
+    const { fallbacks, missing, noLocalization } = collectI18nSeoIssues(seoConfig.routes, languages, defaultLanguage);
+
+    if (noLocalization.length > 0) {
+      const lines = noLocalization
+        .map(({ path, field }) => `  - route "${path}": "${field}"`)
+        .join('\n');
+      print.warn(
+        `[generate-seo-html] i18n is enabled, but these routes have no language values in seo.json:\n${lines}\n\n` +
+        `Add per-language objects (e.g. { "en": ..., "fr": ... }) under the matching route's ` +
+        `"title"/"description" in config/seo.json to localize this content, or ignore this ` +
+        `warning if sharing the same content across every language is intentional.`
+      );
+    }
+
+    if (fallbacks.length > 0) {
+      const lines = fallbacks
+        .map(({ path, field, lang, sourceLang }) => `  - route "${path}": "${field}.${lang}" not set — using "${field}.${sourceLang}"`)
+        .join('\n');
+      print.error(`[generate-seo-html] Using defaultLanguage fallback for missing i18n content:\n${lines}`);
+    }
+
+    if (missing.length > 0) {
+      const lines = missing
+        .map(({ path, field, lang }) => `  - route "${path}": missing "${field}.${lang}" (no language has a value for this field)`)
+        .join('\n');
+
+      errorExit(
+        `config/seo.json is missing required content:\n${lines}\n\n` +
+        `Add these keys under the matching route's "title"/"description" in config/seo.json. ` +
+        `Configured languages (config/languages.json): ${languages.join(', ')}.`
+        , 'generate-seo-html'
+      );
+    }
+  }
+
+  try {
+    const bundleUrl = await buildSsrBundle();
+    await warnForRoutesMissingSeoConfig(bundleUrl, seoConfig.routes, defaultLanguage, baseUrl);
+
+    for (const route of seoConfig.routes) {
+      await processRoute(template, baseUrl, defaultLanguage, languages, route, bundleUrl);
+    }
+  } finally {
+    cleanupSsrBundle();
+  }
+}

package/templates/base/tools/builder/core/seo/generate-sitemap-xml.js.hbs

@@ -0,0 +1,43 @@
+import fs from 'fs';
+import path from 'path';
+import { PATHS } from '../app/paths.js';
+import { print } from '../../../utils/index.js';
+import { builderConfig } from '../../builder.config.js';
+
+function collectUrls(baseUrl, routes, languages) {
+  const urls = [];
+
+  for (const route of routes) {
+    const routeSuffix = route.path === '/' ? '' : route.path;
+
+    if (builderConfig.i18n) {
+      for (const lang of languages) {
+        urls.push(`${baseUrl}/${lang}${routeSuffix}/`);
+      }
+    } else {
+      urls.push(`${baseUrl}${routeSuffix}/`);
+    }
+  }
+
+  return urls;
+}
+
+function buildSitemapXml(urls) {
+  const urlEntries = urls.map(loc => `  <url>\n    <loc>${loc}</loc>\n  </url>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urlEntries}\n</urlset>\n`;
+}
+
+export function generateSitemapXml() {
+  const seoConfigPath = path.join(PATHS.temp, 'config', 'seo.json');
+  const seoConfig = JSON.parse(fs.readFileSync(seoConfigPath, 'utf-8'));
+  const baseUrl = seoConfig.baseUrl.replace(/\/$/, '');
+
+  const languagesConfigPath = path.join(PATHS.temp, 'config', 'languages.json');
+  const { languages } = JSON.parse(fs.readFileSync(languagesConfigPath, 'utf-8'));
+
+  const urls = collectUrls(baseUrl, seoConfig.routes, languages);
+  const xml = buildSitemapXml(urls);
+
+  const outputPath = path.join(PATHS.tempSource, 'sitemap.xml');
+  fs.writeFileSync(outputPath, xml, 'utf-8');
+}

package/templates/base/tools/builder/core/seo/html-substitutions.js.hbs

@@ -0,0 +1,99 @@
+export function escape(str) {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+export function upsertInHead(html, pattern, replacement, fullTag) {
+  if (pattern.test(html)) {
+    return html.replace(pattern, replacement);
+  }
+  return html.replace('</head>', `\n    ${fullTag}\n  </head>`);
+}
+
+export function applySubstitutions(template, lang, title, description, pageUrl, ogImage) {
+  let html = template;
+
+  // lang attribute on <html>
+  if (/(<html[^>]*\slang=)["'][^"']*["']/.test(html)) {
+    html = html.replace(/(<html[^>]*\slang=)["'][^"']*["']/, `$1"${lang}"`);
+  } else {
+    html = html.replace(/<html/, `<html lang="${lang}"`);
+  }
+
+  // <title>
+  html = upsertInHead(html,
+    /(<title>)[^<]*(<\/title>)/,
+    `$1${escape(title)}$2`,
+    `<title>${escape(title)}</title>`
+  );
+
+  // <meta name="description"> — replace all occurrences, or insert one
+  const descPattern = /(<meta\s+name=["']description["']\s+content=)["'][^"']*["']/;
+  if (descPattern.test(html)) {
+    html = html.replace(/(<meta\s+name=["']description["']\s+content=)["'][^"']*["']/g, `$1"${escape(description)}"`);
+  } else {
+    html = html.replace('</head>', `\n    <meta name="description" content="${escape(description)}" />\n  </head>`);
+  }
+
+  // <link rel="canonical">
+  html = upsertInHead(html,
+    /(<link\s+rel=["']canonical["']\s+href=)["'][^"']*["']/,
+    `$1"${pageUrl}/"`,
+    `<link rel="canonical" href="${pageUrl}/" />`
+  );
+
+  // og:url
+  html = upsertInHead(html,
+    /(<meta\s+property=["']og:url["']\s+content=)["'][^"']*["']/,
+    `$1"${pageUrl}/"`,
+    `<meta property="og:url" content="${pageUrl}/" />`
+  );
+
+  // og:title
+  html = upsertInHead(html,
+    /(<meta\s+property=["']og:title["']\s+content=)["'][^"']*["']/,
+    `$1"${escape(title)}"`,
+    `<meta property="og:title" content="${escape(title)}" />`
+  );
+
+  // og:description
+  html = upsertInHead(html,
+    /(<meta\s+property=["']og:description["']\s+content=)["'][^"']*["']/,
+    `$1"${escape(description)}"`,
+    `<meta property="og:description" content="${escape(description)}" />`
+  );
+
+  // twitter:title
+  html = upsertInHead(html,
+    /(<meta\s+name=["']twitter:title["']\s+content=)["'][^"']*["']/,
+    `$1"${escape(title)}"`,
+    `<meta name="twitter:title" content="${escape(title)}" />`
+  );
+
+  // twitter:description
+  html = upsertInHead(html,
+    /(<meta\s+name=["']twitter:description["']\s+content=)["'][^"']*["']/,
+    `$1"${escape(description)}"`,
+    `<meta name="twitter:description" content="${escape(description)}" />`
+  );
+
+  // og:image + twitter:image — only when explicitly provided in route config
+  if (ogImage) {
+    html = upsertInHead(html,
+      /(<meta\s+property=["']og:image["']\s+content=)["'][^"']*["']/,
+      `$1"${escape(ogImage)}"`,
+      `<meta property="og:image" content="${escape(ogImage)}" />`
+    );
+    html = upsertInHead(html,
+      /(<meta\s+name=["']twitter:image["']\s+content=)["'][^"']*["']/,
+      `$1"${escape(ogImage)}"`,
+      `<meta name="twitter:image" content="${escape(ogImage)}" />`
+    );
+  }
+
+  return html;
+}

package/templates/base/tools/builder/core/seo/i18n-resolution.js.hbs

@@ -0,0 +1,66 @@
+// Collapses a per-lang-object-or-flat value down to one language, falling back to the
+// first available value if the exact key is missing. Used when i18n is off, where a route
+// may still be authored as a per-lang object (e.g. the default seo.json.hbs) or a flat value.
+export function resolveLocaleValue(value, defaultLanguage) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value[defaultLanguage] ?? Object.values(value)[0];
+  }
+  return value;
+}
+
+// Used when i18n is on: a per-lang object must have an exact entry for `lang` (no silent
+// fallback to another language), while a flat value is applied uniformly to every language.
+function valueForLang(value, lang) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value[lang] : value;
+}
+
+// Used to actually resolve HTML content when i18n is on: falls back to defaultLanguage (then
+// the first available value) when `lang` has no exact entry, mirroring resolveLocaleValue's
+// fallback. Missing translations become a warning (see collectI18nSeoIssues), not a crash.
+export function valueForLangWithFallback(value, lang, defaultLanguage) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value[lang] ?? value[defaultLanguage] ?? Object.values(value)[0];
+  }
+  return value;
+}
+
+// Which language's value valueForLangWithFallback would actually use for `lang`, given the
+// same value[lang] ?? value[defaultLanguage] ?? Object.values(value)[0] precedence — so
+// warnings can name the real source language instead of assuming defaultLanguage.
+function sourceLangFor(value, lang, defaultLanguage) {
+  if (value[lang]) return lang;
+  if (value[defaultLanguage]) return defaultLanguage;
+  return Object.keys(value).find((key) => value[key]);
+}
+
+// Upfront pass over every route x lang x field, run before the (expensive) SSR bundle build.
+// Buckets each combination into a fallback warning (some language has content, this one
+// doesn't) or a hard error (no language has any content for this field on this route).
+export function collectI18nSeoIssues(routes, languages, defaultLanguage) {
+  const fallbacks = [];
+  const missing = [];
+  const noLocalization = [];
+
+  for (const route of routes) {
+    for (const field of ['title', 'description']) {
+      const value = route[field];
+
+      if (value && typeof value !== 'object') {
+        noLocalization.push({ path: route.path, field });
+      }
+
+      for (const lang of languages) {
+        if (valueForLang(value, lang)) continue;
+
+        const sourceLang = value && typeof value === 'object' ? sourceLangFor(value, lang, defaultLanguage) : undefined;
+        if (sourceLang) {
+          fallbacks.push({ path: route.path, field, lang, sourceLang });
+        } else {
+          missing.push({ path: route.path, field, lang });
+        }
+      }
+    }
+  }
+
+  return { fallbacks, missing, noLocalization };
+}

package/templates/base/tools/builder/core/seo/route-output.js.hbs

@@ -0,0 +1,64 @@
+import fs from 'fs';
+import path from 'path';
+import { PATHS } from '../app/paths.js';
+import { print, errorExit } from '../../../utils/index.js';
+import { applySubstitutions } from './html-substitutions.js';
+import { getAppRoutePaths } from './ssr/ssr-render.js';
+import { builderConfig } from '../../builder.config.js';
+
+export function segmentsOf(routeSuffix) {
+  return routeSuffix ? routeSuffix.split('/').filter(Boolean) : [];
+}
+
+export function validateMockParams(route) {
+  const requiredParams = [...route.path.matchAll(/:([^/]+)/g)]
+    .map(([, name]) => name)
+    .filter((name) => !name.endsWith('?')); // optional segments don't require a mock value
+
+  if (requiredParams.length === 0) return;
+
+  const provided = route.mockParams ?? {};
+  const missing = requiredParams.filter((name) => !(name in provided));
+
+  if (missing.length > 0) {
+    errorExit(
+      `Route "${route.path}" has dynamic segment(s) but is missing "mockParams" ` +
+      `for: ${missing.join(', ')}. Add a "mockParams" object to this route in config/seo.json.`
+      , 'generate-seo-html'
+    );
+  }
+}
+
+export async function writeRouteHtml({ template, lang, title, description, pageUrl, ogImage, body, outputSegments, routePath }) {
+  let html = applySubstitutions(template, lang, title, description, pageUrl, ogImage);
+
+  if (html === template) {
+    errorExit(`Failed to apply any changes for ${routePath} (lang "${lang}") — index.html may be missing a </head> tag`, 'generate-seo-html');
+  }
+
+  html = html.replace(
+    /<main\s+id=["']app["'][^>]*>[\s\S]*?<\/main>/,
+    `<main id="app">\n${body}\n  </main>`
+  );
+
+  const outputDir = path.join(PATHS.tempSource, ...outputSegments);
+  const outputPath = path.join(outputDir, 'index.html');
+
+  fs.mkdirSync(outputDir, { recursive: true });
+  fs.writeFileSync(outputPath, html, 'utf-8');
+}
+
+export async function warnForRoutesMissingSeoConfig(bundleUrl, seoRoutes, defaultLanguage, baseUrl) {
+  const appRoutePaths = await getAppRoutePaths(bundleUrl, defaultLanguage, baseUrl);
+  const seoRoutePaths = new Set(seoRoutes.map((route) => route.path));
+
+  for (const path of appRoutePaths) {
+    if (seoRoutePaths.has(path)) continue;
+
+    if (builderConfig.WELL_KNOWN_NON_SEO_ROUTES.includes(path)) {
+      continue;
+    } else {
+      print.error(`[generate-seo-html] Route "${path}" has no matching entry in config/seo.json; consider adding it so this route gets SEO HTML, sitemap, and meta tags.`);
+    }
+  }
+}