build.js

const fs = require("node:fs");
const path = require("node:path");
const crypto = require("node:crypto");
const { execSync } = require("node:child_process");

const ROOT = process.cwd();
const PUBLIC_DIR = path.join(ROOT, "public");
const BUILD_CACHE_PATH = path.join(ROOT, "manual", "build-cache.json");
const BUILD_CACHE_VERSION = 1;
const ROOT_PAGES_DIR = ROOT;
const ROADMAP_LABS_DIR = path.join(ROOT, "roadmap", "labs");
const ROADMAP_DIR = path.join(ROOT, "roadmap");
const PROJECTS_DIR = path.join(ROOT, "projects");
const COMMUNITY_DIR = path.join(ROOT, "community");
const LAYOUTS_DIR = path.join(ROOT, "layouts");
const ASSETS_DIR = path.join(ROOT, "assets");

const SYSTEM_RUNTIME_FILES = ["robots.txt", "sitemap.xml"];
const PROGRAMMING_TOPIC_FOLDERS = [
  "ada",
  "assembly",
  "bash",
  "c",
  "carbon",
  "cpp",
  "csharp",
  "css",
  "dart",
  "flutter",
  "fortran",
  "go",
  "html",
  "java",
  "julia",
  "nim",
  "php",
  "plsql",
  "python",
  "react",
  "ruby",
  "rust",
  "scala",
  "script",
  "svelte",
  "swift",
  "wasm",
  "tscript",
  "zig"
];

const LAB_ROUTE_MAP = {
  engineering: "cse",
  programming: "csp",
  videos: "videos"
};

function getSupabaseBuildConfig() {
  const url = process.env.NEXT_PUBLIC_SUPABASE_URL || process.env.SUPABASE_URL || "";
  const anonKey =
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY ||
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ||
    process.env.SUPABASE_ANON_KEY ||
    "";
  const schema = process.env.SUPABASE_SCHEMA || "public";

  if (!url || !anonKey) {
    return null;
  }

  return { url, anonKey, schema };
}

function writeSupabaseConfigAsset() {
  const sourcePath = path.join(ASSETS_DIR, "js", "supabase-config.js");
  const destinationPath = path.join(PUBLIC_DIR, "assets", "js", "supabase-config.js");
  const runtimeConfig = getSupabaseBuildConfig();

  if (!fs.existsSync(sourcePath)) {
    return;
  }

  if (!runtimeConfig) {
    copyRecursive(sourcePath, destinationPath);
    return;
  }

  const contents = [
    "// Generated during build from Vercel environment variables.",
    "(function () {",
    "  window.__SUPABASE_CONFIG__ = {",
    `    url: ${JSON.stringify(runtimeConfig.url)},`,
    `    anonKey: ${JSON.stringify(runtimeConfig.anonKey)},`,
    `    schema: ${JSON.stringify(runtimeConfig.schema)}`,
    "  };",
    "})();",
    ""
  ].join("\n");

  ensureDir(path.dirname(destinationPath));
  fs.writeFileSync(destinationPath, contents, "utf8");
}

const ASSET_PATH_REWRITES = [
  { pattern: /(["'])\/(sage\.css)\1/g, replacement: "$1/assets/css/sage.css$1" },
  { pattern: /(["'])\/(carousel\.css)\1/g, replacement: "$1/assets/css/carousel.css$1" },
  { pattern: /(["'])\/(manifesto\.css)\1/g, replacement: "$1/assets/css/manifesto.css$1" },
  { pattern: /(["'])\/(prism\.css)\1/g, replacement: "$1/assets/css/prism.css$1" },
  { pattern: /(["'])\/(sage\.js)\1/g, replacement: "$1/assets/js/sage.js$1" },
  { pattern: /(["'])\/(sidebar\.js)\1/g, replacement: "$1/assets/js/sidebar.js$1" },
  { pattern: /(["'])\/(progress\.js)\1/g, replacement: "$1/assets/js/progress.js$1" },
  { pattern: /(["'])\/(home\.js)\1/g, replacement: "$1/assets/js/home.js$1" },
  { pattern: /(["'])\/(prism\.js)\1/g, replacement: "$1/assets/js/prism.js$1" },
  { pattern: /(["'])\/common\/([^"']+\.js)\1/g, replacement: "$1/assets/js/$2$1" },
  { pattern: /(["'])\.\.\/\.\.\/common\/([^"']+\.js)\1/g, replacement: "$1/assets/js/$2$1" },
  { pattern: /(["'])\.\.\/common\/([^"']+\.js)\1/g, replacement: "$1/assets/js/$2$1" },
  { pattern: /(["'])\.\/common\/([^"']+\.js)\1/g, replacement: "$1/assets/js/$2$1" },
  { pattern: /(["'])common\/([^"']+\.js)\1/g, replacement: "$1/assets/js/$2$1" },
  { pattern: /(["'])\/(images\/)\1/g, replacement: "$1/assets/images/$1" },
  { pattern: /(["'])\.\.\/\.\.\/images\//g, replacement: "$1/assets/images/" },
  { pattern: /(["'])\.\.\/images\//g, replacement: "$1/assets/images/" },
  { pattern: /(["'])\.\/images\//g, replacement: "$1/assets/images/" },
  { pattern: /(["'])images\//g, replacement: "$1/assets/images/" },
  { pattern: /(["'])\.\.\/\.\.\/sage\.css\1/g, replacement: "$1/assets/css/sage.css$1" },
  { pattern: /(["'])\.\.\/sage\.css\1/g, replacement: "$1/assets/css/sage.css$1" },
  { pattern: /(["'])\.\/sage\.css\1/g, replacement: "$1/assets/css/sage.css$1" },
  { pattern: /(["'])sage\.css\1/g, replacement: "$1/assets/css/sage.css$1" },
  { pattern: /(["'])\.\.\/\.\.\/prism\.css\1/g, replacement: "$1/assets/css/prism.css$1" },
  { pattern: /(["'])\.\.\/prism\.css\1/g, replacement: "$1/assets/css/prism.css$1" },
  { pattern: /(["'])\.\/prism\.css\1/g, replacement: "$1/assets/css/prism.css$1" },
  { pattern: /(["'])prism\.css\1/g, replacement: "$1/assets/css/prism.css$1" },
  { pattern: /(["'])\.\.\/\.\.\/prism\.js\1/g, replacement: "$1/assets/js/prism.js$1" },
  { pattern: /(["'])\.\.\/prism\.js\1/g, replacement: "$1/assets/js/prism.js$1" },
  { pattern: /(["'])\.\/prism\.js\1/g, replacement: "$1/assets/js/prism.js$1" },
  { pattern: /(["'])prism\.js\1/g, replacement: "$1/assets/js/prism.js$1" },
  { pattern: /(["'])\.\.\/\.\.\/sage\.js\1/g, replacement: "$1/assets/js/sage.js$1" },
  { pattern: /(["'])\.\.\/sage\.js\1/g, replacement: "$1/assets/js/sage.js$1" },
  { pattern: /(["'])\.\/sage\.js\1/g, replacement: "$1/assets/js/sage.js$1" },
  { pattern: /(["'])sage\.js\1/g, replacement: "$1/assets/js/sage.js$1" }
];

function ensureDir(dirPath) {
  fs.mkdirSync(dirPath, { recursive: true });
}

function isPathInside(filePath, directoryPath) {
  const relative = path.relative(directoryPath, filePath);
  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
}

function hashFileContent(filePath) {
  return crypto.createHash("sha1").update(fs.readFileSync(filePath)).digest("hex");
}

function collectFilesRecursive(dir, result = []) {
  if (!fs.existsSync(dir)) {
    return result;
  }

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      collectFilesRecursive(fullPath, result);
    } else if (entry.isFile()) {
      result.push(fullPath);
    }
  }

  return result;
}

function collectBuildInputFiles() {
  const sourceFiles = new Set();

  sourceFiles.add(__filename);

  for (const fileName of SYSTEM_RUNTIME_FILES) {
    const filePath = path.join(ROOT, fileName);
    if (fs.existsSync(filePath)) {
      sourceFiles.add(filePath);
    }
  }

  for (const htmlPath of collectTopLevelHtmlFiles(ROOT_PAGES_DIR)) {
    sourceFiles.add(htmlPath);
  }

  for (const filePath of collectFilesRecursive(LAYOUTS_DIR)) {
    sourceFiles.add(filePath);
  }

  for (const filePath of collectFilesRecursive(ASSETS_DIR)) {
    sourceFiles.add(filePath);
  }

  for (const filePath of collectFilesRecursive(ROADMAP_DIR)) {
    sourceFiles.add(filePath);
  }

  for (const filePath of collectFilesRecursive(PROJECTS_DIR)) {
    sourceFiles.add(filePath);
  }

  for (const filePath of collectFilesRecursive(COMMUNITY_DIR)) {
    sourceFiles.add(filePath);
  }

  return Array.from(sourceFiles).sort();
}

function createSourceHashMap(files) {
  const hashes = {};
  for (const filePath of files) {
    hashes[filePath] = hashFileContent(filePath);
  }
  return hashes;
}

function loadBuildCache() {
  if (!fs.existsSync(BUILD_CACHE_PATH)) {
    return null;
  }

  try {
    const parsed = JSON.parse(readTextOrEmpty(BUILD_CACHE_PATH));
    if (!parsed || parsed.version !== BUILD_CACHE_VERSION || typeof parsed.sourceHashes !== "object") {
      return null;
    }
    return parsed;
  } catch {
    return null;
  }
}

function saveBuildCache(sourceHashes, mode) {
  const payload = {
    version: BUILD_CACHE_VERSION,
    generatedAtUtc: new Date().toISOString(),
    mode,
    sourceHashes
  };

  ensureDir(path.dirname(BUILD_CACHE_PATH));
  fs.writeFileSync(BUILD_CACHE_PATH, JSON.stringify(payload, null, 2), "utf8");
}

function diffSourceHashes(previousHashes, currentHashes) {
  const changed = [];
  const deleted = [];

  const previous = previousHashes || {};
  const current = currentHashes || {};

  for (const [filePath, currentHash] of Object.entries(current)) {
    if (!Object.prototype.hasOwnProperty.call(previous, filePath) || previous[filePath] !== currentHash) {
      changed.push(filePath);
    }
  }

  for (const filePath of Object.keys(previous)) {
    if (!Object.prototype.hasOwnProperty.call(current, filePath)) {
      deleted.push(filePath);
    }
  }

  return { changed, deleted };
}

function cleanPublicDir() {
  if (fs.existsSync(PUBLIC_DIR)) {
    fs.rmSync(PUBLIC_DIR, { recursive: true, force: true });
  }
  ensureDir(PUBLIC_DIR);
}

function readTextOrEmpty(filePath) {
  if (!fs.existsSync(filePath)) {
    return "";
  }
  return fs.readFileSync(filePath, "utf8");
}

function copyRecursive(src, dest) {
  if (!fs.existsSync(src)) {
    return;
  }

  const stat = fs.statSync(src);
  if (stat.isDirectory()) {
    ensureDir(dest);
    for (const entry of fs.readdirSync(src)) {
      copyRecursive(path.join(src, entry), path.join(dest, entry));
    }
    return;
  }

  ensureDir(path.dirname(dest));
  fs.copyFileSync(src, dest);
}

function copyHtmlOnlyRecursive(src, dest) {
  if (!fs.existsSync(src)) {
    return;
  }

  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
    const sourcePath = path.join(src, entry.name);
    const targetPath = path.join(dest, entry.name);

    if (entry.isDirectory()) {
      copyHtmlOnlyRecursive(sourcePath, targetPath);
      continue;
    }

    if (
      entry.isFile() &&
      entry.name.toLowerCase().endsWith(".html") &&
      entry.name.toLowerCase() !== "template.html"
    ) {
      ensureDir(path.dirname(targetPath));
      fs.copyFileSync(sourcePath, targetPath);
    }
  }
}

function shouldCopyLabStaticAsset(fileName) {
  const ext = path.extname(fileName).toLowerCase();
  const staticAssetExtensions = new Set([
    ".png",
    ".jpg",
    ".jpeg",
    ".gif",
    ".svg",
    ".webp",
    ".bmp",
    ".ico",
    ".avif",
    ".mp3",
    ".wav",
    ".ogg",
    ".mp4",
    ".webm",
    ".mov",
    ".m4v",
    ".css",
    ".js",
    ".woff",
    ".woff2",
    ".ttf",
    ".otf",
    ".eot",
    ".json"
  ]);

  return staticAssetExtensions.has(ext);
}

function copyLabStaticAssetsRecursive(src, dest) {
  if (!fs.existsSync(src)) {
    return;
  }

  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
    const sourcePath = path.join(src, entry.name);
    const targetPath = path.join(dest, entry.name);

    if (entry.isDirectory()) {
      // Allow recursion into subdirectories like 'data'
      copyLabStaticAssetsRecursive(sourcePath, targetPath);
      continue;
    }

    if (!entry.isFile()) {
      continue;
    }

    // Allow any file within a "demo" directory to be copied
    const isInDemoDir = sourcePath.split(path.sep).includes("demo");

    // Always copy .json files in roadmap/labs or roadmap/*/data
    if (!isInDemoDir && !shouldCopyLabStaticAsset(entry.name) && path.extname(entry.name) !== ".json") {
      continue;
    }

    ensureDir(path.dirname(targetPath));
    fs.copyFileSync(sourcePath, targetPath);
  }
}

function collectHtmlFiles(dir, result = []) {
  if (!fs.existsSync(dir)) {
    return result;
  }

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      collectHtmlFiles(fullPath, result);
    } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".html")) {
      result.push(fullPath);
    }
  }
  return result;
}

function collectTopLevelHtmlFiles(dir) {
  if (!fs.existsSync(dir)) {
    return [];
  }

  return fs
    .readdirSync(dir, { withFileTypes: true })
    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
    .map((entry) => path.join(dir, entry.name));
}

function sanitizeTitle(raw) {
  return raw
    .replace(/[-_]/g, " ")
    .replace(/\s+/g, " ")
    .trim()
    .replace(/\b\w/g, (char) => char.toUpperCase());
}

function detectTitle(content, sourcePath) {
  const explicitMatch = content.match(/<!--\s*@page-title:\s*(.*?)\s*-->/i);
  if (explicitMatch) {
    return explicitMatch[1].trim();
  }

  const h1Match = content.match(/<h1[^>]*>(.*?)<\/h1>/i);
  if (h1Match) {
    return h1Match[1].replace(/<[^>]+>/g, "").trim();
  }

  const fileName = path.basename(sourcePath, ".html");
  return sanitizeTitle(fileName || "Sage-Code");
}

function buildMaintenanceBanner() {
  if ((process.env.MIGRATION_MAINTENANCE_MODE || "").toLowerCase() !== "true") {
    return "";
  }

  return [
    '<div class="migration-banner" role="status" aria-live="polite">',
    "  Maintenance: this page is being migrated to the new static architecture.",
    "</div>"
  ].join("\n");
}

function renderFromTemplate(content, sourcePath, templates) {
  const { baseTemplate, headerTemplate, footerTemplate } = templates;
  const title = detectTitle(content, sourcePath);
  const maintenanceBanner = buildMaintenanceBanner();
  const description = "Sage-Code static page";

  return baseTemplate
    .replace("{{title}}", title)
    .replace("{{meta_description}}", description)
    .replace("{{head_extra}}", "")
    .replace("{{maintenance_banner}}", maintenanceBanner)
    .replace("{{header}}", headerTemplate)
    .replace("{{content}}", content)
    .replace("{{footer}}", footerTemplate);
}

function rewritePublishedRoutePrefix(html, sourcePrefix, publishedPrefix) {
  const pattern = new RegExp(`(["'])\\/${sourcePrefix}\\/`, "gi");
  return html.replace(pattern, `$1/${publishedPrefix}/`);
}

function rewriteAssetPaths(html) {
  let transformed = html;
  for (const rule of ASSET_PATH_REWRITES) {
    transformed = transformed.replace(rule.pattern, rule.replacement);
  }

  // Normalize roadmap publish routes under /roadmap and standalone project routes under /projects.
  transformed = rewritePublishedRoutePrefix(transformed, "engineering", "roadmap/cse");
  transformed = rewritePublishedRoutePrefix(transformed, "programming", "roadmap");
  transformed = rewritePublishedRoutePrefix(transformed, "cse", "roadmap/cse");
  transformed = rewritePublishedRoutePrefix(transformed, "csp", "roadmap");
  transformed = rewritePublishedRoutePrefix(transformed, "csa", "roadmap/csa");
  transformed = rewritePublishedRoutePrefix(transformed, "dsa", "roadmap/dsa");
  transformed = rewritePublishedRoutePrefix(transformed, "itc", "roadmap/hpc");
  transformed = rewritePublishedRoutePrefix(transformed, "hpc", "roadmap/hpc");
  transformed = rewritePublishedRoutePrefix(transformed, "tek", "roadmap/tek");
  transformed = rewritePublishedRoutePrefix(transformed, "ops", "roadmap/tek");
  transformed = rewritePublishedRoutePrefix(transformed, "dba", "roadmap/dba");
  transformed = rewritePublishedRoutePrefix(transformed, "sml", "roadmap/sml");
  transformed = rewritePublishedRoutePrefix(transformed, "osd", "roadmap/osd");
  transformed = rewritePublishedRoutePrefix(transformed, "dsk", "roadmap/dsk");
  transformed = rewritePublishedRoutePrefix(transformed, "das", "roadmap/sml");
  transformed = rewritePublishedRoutePrefix(transformed, "csd", "roadmap/sml");
  transformed = rewritePublishedRoutePrefix(transformed, "pro", "projects");

  // MAJ assets and media now live under the standalone /projects namespace.
  transformed = transformed.replace(/(["'])\/maj\/\.\.\/projects\//gi, "$1/projects/");
  transformed = transformed.replace(/(["'])\/content\/maj\//gi, "$1/projects/maj/");
  transformed = transformed.replace(/(["'])\/maj\//gi, "$1/projects/maj/");
  transformed = transformed.replace(/(["'])\/maj\/img\//gi, "$1/projects/maj/img/");
  transformed = transformed.replace(/(["'])((?:\.\.\/)+)maj\/img\//gi, "$1$2projects/maj/img/");

  // Normalize legacy image roots to the centralized assets folder.
  transformed = transformed.replace(/(["'])\/images\//g, "$1/assets/images/");

  // Several legacy references use .jpg while only .svg diagrams exist in assets/images.
  transformed = transformed.replace(/assets\/images\/(array|decision|ladder|for-loop|while|switch|function)\.jpg/gi, "assets/images/$1.svg");

  return transformed;
}

function getRelativeRootPrefix(sourcePath) {
  const relativePath = path.relative(PUBLIC_DIR, sourcePath);
  if (!relativePath || relativePath.startsWith("..")) {
    return "./";
  }

  const depth = relativePath.split(path.sep).length - 1;
  if (depth <= 0) {
    return "./";
  }

  return "../".repeat(depth);
}

function relativizeInternalRootLinks(html, sourcePath) {
  const prefix = getRelativeRootPrefix(sourcePath);

  let transformed = html;

  // Convert exact site-root links first (e.g., href="/").
  transformed = transformed.replace(/\b(href|src)=(["'])\/\2/gi, (match, attr, quote) => {
    return `${attr}=${quote}${prefix}${quote}`;
  });

  // Convert root-relative href/src links to page-relative paths for local /public serving.
  return transformed.replace(/\b(href|src)=(["'])\/([^"']*)\2/gi, (match, attr, quote, value) => {
    // Keep protocol-relative URLs unchanged.
    if (value.startsWith("/")) {
      return match;
    }

    // Anchor-only references remain unchanged.
    if (value.startsWith("#")) {
      return match;
    }

    const relative = `${prefix}${value}`;
    return `${attr}=${quote}${relative}${quote}`;
  });
}

function normalizeSharedBrandAssets(html, sourcePath) {
  // Keep shared brand assets rooted at /assets so they resolve on clean-url routes.
  const logoPath = `/assets/images/sage-logo.svg`;
  const faviconPath = `/assets/images/favicon.ico`;

  let transformed = html;
  transformed = transformed.replace(/\bsrc=(['"])(?:[^"']*\/)?sage-logo\.svg\1/gi, (match, quote) => {
    return `src=${quote}${logoPath}${quote}`;
  });

  transformed = transformed.replace(/\bhref=(['"])(?:[^"']*\/)?favicon\.ico\1/gi, (match, quote) => {
    return `href=${quote}${faviconPath}${quote}`;
  });

  return transformed;
}

function shouldRelativizeRootLinks(sourcePath) {
  const normalized = sourcePath.replace(/\\/g, "/").toLowerCase();
  if (normalized.includes("/public/roadmap/")) {
    return false;
  }

  // Project subpages are served by Vercel as clean directory URLs (for
  // example, /projects/bee/features/). Their virtual route depth differs
  // from the published .html path, so page-relative shared asset URLs break.
  if (normalized.includes("/public/projects/")) {
    return false;
  }

  // Vercel's cleanUrls + trailingSlash config serves top-level pages like
  // /legal.html and /manifesto.html at a virtual /legal/ and /manifesto/
  // route (one directory level deeper than the file actually sits in
  // /public). Page-relative "./assets/..." links resolve incorrectly under
  // that virtual route, so keep root-absolute links for every top-level
  // page except index.html, whose clean route is "/" itself.
  if (path.dirname(sourcePath) === PUBLIC_DIR && path.basename(sourcePath).toLowerCase() !== "index.html") {
    return false;
  }

  return true;
}

function escapeHtml(value) {
  return String(value)
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#39;");
}

function getSourceRouteForPublicRoute(publicRoute) {
  for (const [sourceRoute, publishedRoute] of Object.entries(LAB_ROUTE_MAP)) {
    if (publishedRoute === publicRoute) {
      return sourceRoute;
    }
  }
  return publicRoute;
}

function resolveContentRouteSourceDir(publicRoute) {
  const directRouteDir = path.join(ROADMAP_DIR, publicRoute);
  if (fs.existsSync(directRouteDir)) {
    return directRouteDir;
  }

  const sourceTopLevelRoute = getSourceRouteForPublicRoute(publicRoute);
  const legacyRouteDir = path.join(ROADMAP_LABS_DIR, sourceTopLevelRoute);
  if (fs.existsSync(legacyRouteDir)) {
    return legacyRouteDir;
  }

  return null;
}

function resolveSidebarJsonPath(publicHtmlPath) {
  const relativePath = path.relative(PUBLIC_DIR, publicHtmlPath);
  if (!relativePath || relativePath.startsWith("..")) {
    return null;
  }

  const publicPathParts = relativePath.split(path.sep);
  if (publicPathParts[0].toLowerCase() === "projects") {
    if (publicPathParts.length < 3) {
      return null;
    }

    const projectDir = path.join(PROJECTS_DIR, publicPathParts[1]);
    const relativeJsonPath = publicPathParts.slice(2).join(path.sep).replace(/\.html$/i, ".json");
    const jsonPath = path.join(projectDir, relativeJsonPath);
    return fs.existsSync(jsonPath) ? jsonPath : null;
  }

  if (publicPathParts.length < 2) {
    return null;
  }

  const contentRootOffset = publicPathParts[0].toLowerCase() === "roadmap" ? 1 : 0;
  if (publicPathParts.length < contentRootOffset + 2) {
    return null;
  }

  const topLevelRoute = publicPathParts[contentRootOffset].toLowerCase();

  const contentRouteDir = resolveContentRouteSourceDir(topLevelRoute);
  if (!contentRouteDir) {
    return null;
  }

  const relativeJsonPath = publicPathParts.slice(contentRootOffset + 1).join(path.sep).replace(/\.html$/i, ".json");
  const jsonPath = path.join(contentRouteDir, relativeJsonPath);
  return fs.existsSync(jsonPath) ? jsonPath : null;
}

function resolveRoadmapTopicContext(publicHtmlPath) {
  const relativePath = path.relative(PUBLIC_DIR, publicHtmlPath);
  if (!relativePath || relativePath.startsWith("..")) {
    return null;
  }

  const publicPathParts = relativePath.split(path.sep);
  const rootNamespace = (publicPathParts[0] || "").toLowerCase();
  const isProjectTopic = rootNamespace === "projects";
  if (publicPathParts.length < (isProjectTopic ? 3 : 3)) {
    return null;
  }

  const contentRootOffset = rootNamespace === "roadmap" || isProjectTopic ? 1 : 0;
  if (publicPathParts.length < contentRootOffset + 2) {
    return null;
  }

  const topLevelRoute = publicPathParts[contentRootOffset].toLowerCase();
  const hasProjectRoute = isProjectTopic && fs.existsSync(path.join(PROJECTS_DIR, topLevelRoute));
  if (!hasProjectRoute && !resolveContentRouteSourceDir(topLevelRoute)) {
    return null;
  }

  const fileName = publicPathParts[publicPathParts.length - 1] || "";
  const topicId = path.basename(fileName, path.extname(fileName));
  if (!topicId || topicId.toLowerCase() === "index") {
    return null;
  }

  const sidebarJsonPath = resolveSidebarJsonPath(publicHtmlPath);
  if (!sidebarJsonPath) {
    return null;
  }

  return {
    namespace: isProjectTopic ? "projects" : "roadmap",
    topLevelRoute,
    topicId
  };
}

function getLabIdFromRoute(route) {
  if (route === "cse") {
    return "engineering";
  }

  if (route === "csp") {
    return "programming";
  }

  if (PROGRAMMING_TOPIC_FOLDERS.includes(route)) {
    return "programming";
  }

  return route;
}

function renderSidebarItems(items, state = { index: 0 }, level = 0) {
  let html = "";

  for (const item of items) {
    const title = escapeHtml(item.title || "Untitled");
    const link = item.link || (item.target ? `#${item.target}` : "#");
    const safeLink = escapeHtml(link);
    const isAnchorLink = link.startsWith("#");

    if (!isAnchorLink) {
      if (Array.isArray(item.children) && item.children.length > 0) {
        html += renderSidebarItems(item.children, state, level);
      }
      continue;
    }

    const itemId = `sidebar-item-${state.index}`;
    state.index += 1;
    const sectionKey = escapeHtml(link.slice(1));
    const nodeId = `node-${sectionKey}-static-${state.index}`;
    const hasChildren = Array.isArray(item.children) && item.children.length > 0;
    const icon = hasChildren
      ? `<button type="button" class="nav-tree-toggle" data-node-id="${nodeId}" aria-expanded="${level === 0 ? "true" : "false"}" aria-label="${level === 0 ? "Collapse topic folder" : "Expand topic folder"}"><i class="bi ${level === 0 ? "bi-folder2-open" : "bi-folder2"}" aria-hidden="true"></i></button>`
      : '<span class="nav-file-icon"><i class="bi bi-file-earmark-text" aria-hidden="true"></i></span>';

    html += `<li class="nav-item mb-2 nav-tree-item" id="${itemId}" data-sidebar-level="${level}" data-tree-level="${level}" data-node-id="${nodeId}" data-section-key="${sectionKey}"${hasChildren ? ' data-has-children="true"' : ""}>`;
    html += `<div class="nav-node-row" data-node-id="${nodeId}" data-section-key="${sectionKey}">`;
    const checkboxId = `nav-progress-${state.index}`;
    html += `${icon}<input type="checkbox" class="nav-progress-checkbox" id="${checkboxId}" data-is-trackable="true" data-link="${safeLink}" data-section-key="${sectionKey}" tabindex="-1" aria-hidden="true">`;
    html += `<a href="${safeLink}" class="nav-tree-link text-decoration-none" data-section-key="${sectionKey}" role="treeitem" aria-level="${level + 1}" tabindex="-1">${title}</a>`;
    html += `</div>`;

    if (hasChildren) {
      html += `<ul class="list-unstyled ms-4 mt-1 nav-tree-children${level === 0 ? "" : " is-collapsed"}" data-sidebar-group="children" data-sidebar-level="${level + 1}" data-parent-node-id="${nodeId}" role="group">`;
      html += renderSidebarItems(item.children, state, level + 1);
      html += "</ul>";
    }

    html += "</li>";
  }

  return html;
}

// Clean URLs + trailing slashes serve topic pages from a virtual directory, so a
// relative "./index.html" resolves back onto the current page instead of the track index.
function resolveReturnToRoadmapHref(sourcePath) {
  const context = resolveRoadmapTopicContext(sourcePath);
  if (context) {
    if (context.namespace === "projects") {
      return `/projects/${context.topLevelRoute}/#topic-${context.topicId}`;
    }

    return `/roadmap/${context.topLevelRoute}/#topic-${context.topicId}`;
  }

  const parentRoute = path
    .relative(PUBLIC_DIR, path.dirname(sourcePath))
    .split(path.sep)
    .filter(Boolean)
    .join("/");

  return parentRoute ? `/${parentRoute}/` : "/";
}

function renderReturnToRoadmapItem(sourcePath) {
  const href = escapeHtml(resolveReturnToRoadmapHref(sourcePath));
  return `<li class="nav-item mb-2 return-roadmap-link"><a href="${href}" class="text-info text-decoration-none">Return to Roadmap</a></li>`;
}

function findBookmarkListBounds(html) {
  const openTagRegex = /<ul[^>]*id=["']bookmark-list["'][^>]*>/i;
  const openMatch = openTagRegex.exec(html);
  if (!openMatch) {
    return null;
  }

  const openStart = openMatch.index;
  const openTag = openMatch[0];
  const openEnd = openStart + openTag.length;

  const ulTagRegex = /<\/?ul\b[^>]*>/gi;
  ulTagRegex.lastIndex = openEnd;
  let depth = 1;

  for (let match = ulTagRegex.exec(html); match; match = ulTagRegex.exec(html)) {
    const token = match[0].toLowerCase();
    if (token.startsWith("</ul")) {
      depth -= 1;
      if (depth === 0) {
        return {
          openStart,
          openEnd,
          closeStart: match.index,
          closeEnd: ulTagRegex.lastIndex,
          openTag
        };
      }
    } else {
      depth += 1;
    }
  }

  return null;
}

function markBookmarkListAsStatic(openTag) {
  if (/\bdata-static-sidebar\s*=\s*["']true["']/i.test(openTag)) {
    return openTag;
  }

  return openTag.replace(/>$/, ' data-static-sidebar="true">');
}

function ensureReturnToRoadmapLink(html, sourcePath) {
  const bounds = findBookmarkListBounds(html);
  if (!bounds) {
    return html;
  }

  const inner = html.slice(bounds.openEnd, bounds.closeStart);
  if (/return-roadmap-link|Return to Roadmap/i.test(inner)) {
    return html;
  }

  const trimmedInner = inner.trimEnd();
  const separator = trimmedInner.length > 0 ? "\n" : "";
  const updatedInner = `${trimmedInner}${separator}${renderReturnToRoadmapItem(sourcePath)}\n`;

  return `${html.slice(0, bounds.openEnd)}${updatedInner}${html.slice(bounds.closeStart)}`;
}

function injectStaticSidebar(html, sourcePath) {
  const bounds = findBookmarkListBounds(html);
  if (!bounds) {
    return html;
  }

  if (/\bdata-static-sidebar\s*=\s*["']true["']/i.test(bounds.openTag)) {
    return html;
  }

  const jsonPath = resolveSidebarJsonPath(sourcePath);
  if (!jsonPath) {
    return html;
  }

  let navItems = [];
  try {
    navItems = JSON.parse(readTextOrEmpty(jsonPath));
  } catch {
    return html;
  }

  if (!Array.isArray(navItems) || navItems.length === 0) {
    return html;
  }

  let transformed = html;
  transformed = transformed.replace(
    /<aside class=["']side-bar\b([^"']*)["']/i,
    '<aside id="topic-sidebar" class="side-bar$1"'
  );

  const refreshedBounds = findBookmarkListBounds(transformed);
  if (!refreshedBounds) {
    return transformed;
  }

  const staticOpenTag = markBookmarkListAsStatic(refreshedBounds.openTag);
  const renderedList = `${renderSidebarItems(navItems)}\n${renderReturnToRoadmapItem(sourcePath)}`;
  transformed =
    `${transformed.slice(0, refreshedBounds.openStart)}` +
    `${staticOpenTag}\n${renderedList}\n` +
    `${transformed.slice(refreshedBounds.closeStart)}`;

  return transformed;
}

function injectInlineHeader(html, headerTemplate) {
  if (!headerTemplate.trim()) {
    return html;
  }

  const headerWithPlaceholderRegex = /<header[^>]*id=["']dynamic-header["'][^>]*>\s*<\/header>/i;
  if (headerWithPlaceholderRegex.test(html)) {
    return html.replace(headerWithPlaceholderRegex, headerTemplate);
  }

  return html;
}

function injectInlineFooter(html, footerTemplate, enforceCommonFooter = false) {
  if (!footerTemplate.trim()) {
    return html;
  }

  const normalizedFooter = footerTemplate.trim();

  const footerWithPlaceholderRegex = /<footer[^>]*id=["']dynamic-footer["'][^>]*>\s*<\/footer>/i;
  if (footerWithPlaceholderRegex.test(html)) {
    return html.replace(footerWithPlaceholderRegex, normalizedFooter);
  }

  if (!enforceCommonFooter) {
    if (/<footer[\s>]/i.test(html)) {
      return html;
    }

    if (/<\/body>/i.test(html)) {
      return html.replace(/<\/body>/i, `${normalizedFooter}\n</body>`);
    }

    return `${html}\n${normalizedFooter}`;
  }

  if (/<footer[\s>]/i.test(html)) {
    return html.replace(/<footer\b[\s\S]*?<\/footer>/i, normalizedFooter);
  }

  const bodyCloseWithContainerEndRegex = /(\s*<\/div>\s*)(<\/body>)/i;
  if (bodyCloseWithContainerEndRegex.test(html)) {
    return html.replace(bodyCloseWithContainerEndRegex, `\n${normalizedFooter}\n$1$2`);
  }

  if (/<\/body>/i.test(html)) {
    return html.replace(/<\/body>/i, `${normalizedFooter}\n</body>`);
  }

  return `${html}\n${normalizedFooter}`;
}

function ensureBootstrapIconsForTopic(html) {
  if (!/<ul[^>]*id=["']bookmark-list["']/i.test(html) || /bootstrap-icons/i.test(html)) {
    return html;
  }

  const iconStylesheet = '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">';
  if (/<\/head>/i.test(html)) {
    return html.replace(/<\/head>/i, `${iconStylesheet}\n</head>`);
  }

  return html;
}

function shouldEnforceCommonFooter(sourcePath) {
  const normalized = sourcePath.replace(/\\/g, "/").toLowerCase();
  return normalized.includes("/public/") && normalized.endsWith(".html");
}

function shouldInjectRoadmapProgressScripts(html) {
  return /window\.TOPIC_CONFIG\s*=|data-sage-roadmap=/i.test(html);
}

function injectRoadmapProgressScripts(html) {
  if (!shouldInjectRoadmapProgressScripts(html)) {
    return html;
  }

  const needsAuthStack = !/supabase-client\.js/i.test(html) || !/roadmap-state\.js/i.test(html);
  const needsProgressSync = !/roadmap-progress-sync\.js/i.test(html);

  if (!needsAuthStack && !needsProgressSync) {
    return html;
  }

  const scripts = [];

  if (needsAuthStack) {
    scripts.push(
      '<script src="/assets/js/supabase-config.js"></script>',
      '<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>',
      '<script src="/assets/js/supabase-client.js"></script>',
      '<script src="/assets/js/roadmap-state.js"></script>'
    );
  }

  if (needsProgressSync) {
    scripts.push('<script src="/assets/js/roadmap-progress-sync.js"></script>');
  }

  return html.replace(/<\/body>/i, `${scripts.join("\n")}\n</body>`);
}

function removeLegacySidebarRuntimeScript(html) {
  return html.replace(/\s*<script\b[^>]*src=["'][^"']*sidebar\.js["'][^>]*><\/script>\s*/gi, "\n");
}

function hasTopicRuntimeMarker(html) {
  return /<body\b[^>]*\bdata-topic-runtime-injected\s*=\s*["']true["']/i.test(html);
}

function addTopicRuntimeMarker(html) {
  if (hasTopicRuntimeMarker(html)) {
    return html;
  }

  return html.replace(/<body\b/i, '<body data-topic-runtime-injected="true"');
}

function ensureTopicConfigScript(html, sourcePath) {
  if (hasTopicRuntimeMarker(html)) {
    return html;
  }

  if (/window\.TOPIC_CONFIG\s*=/.test(html)) {
    return html;
  }

  if (!/<ul[^>]*id=["']bookmark-list["']/i.test(html)) {
    return html;
  }

  const context = resolveRoadmapTopicContext(sourcePath);
  if (!context) {
    return html;
  }

  const labId = getLabIdFromRoute(context.topLevelRoute);
  const homeLink = context.namespace === "projects"
    ? `/projects/${context.topLevelRoute}/#topics`
    : `/roadmap/${context.topLevelRoute}/#topics`;
  const labHomeLink = context.namespace === "projects"
    ? `/projects/${context.topLevelRoute}/`
    : resolveReturnToRoadmapHref(sourcePath);
  const configScript = [
    "<script>",
    "  window.TOPIC_CONFIG = {",
    `    labId: ${JSON.stringify(labId)},`,
    `    topicId: ${JSON.stringify(context.topicId)},`,
    `    homeLink: ${JSON.stringify(homeLink)},`,
    `    labHomeLink: ${JSON.stringify(labHomeLink)},`,
    "    inlineContent: true",
    "  };",
    "</script>"
  ].join("\n");

  if (/<\/body>/i.test(html)) {
    return html.replace(/<\/body>/i, `${configScript}\n</body>`);
  }

  return `${html}\n${configScript}`;
}

function ensureTopicRuntimeScripts(html, sourcePath) {
  const context = resolveRoadmapTopicContext(sourcePath);
  if (!context) {
    return html;
  }

  let transformed = removeLegacySidebarRuntimeScript(html);

  if (hasTopicRuntimeMarker(transformed)) {
    return transformed;
  }

  transformed = ensureTopicConfigScript(transformed, sourcePath);

  const requiredScripts = [];
  if (!/\bprogress\.js\b/i.test(transformed)) {
    requiredScripts.push('<script src="/assets/js/progress.js" defer></script>');
  }
  if (!/\blab-progress-bridge\.js\b/i.test(transformed)) {
    requiredScripts.push('<script src="/assets/js/lab-progress-bridge.js" defer></script>');
  }
  if (!/\btopic-loader\.js\b/i.test(transformed)) {
    requiredScripts.push('<script src="/assets/js/topic-loader.js" defer></script>');
  }

  if (requiredScripts.length === 0) {
    return addTopicRuntimeMarker(transformed);
  }

  const scriptsBlock = requiredScripts.join("\n");
  if (/<\/body>/i.test(transformed)) {
    transformed = transformed.replace(/<\/body>/i, `${scriptsBlock}\n</body>`);
    return addTopicRuntimeMarker(transformed);
  }

  transformed = `${transformed}\n${scriptsBlock}`;
  return addTopicRuntimeMarker(transformed);
}

function makeInlineScriptFileName(sourcePath, index, scriptBody) {
  const relativePath = path.relative(PUBLIC_DIR, sourcePath).replace(/\\/g, "/");
  const sourceStub = relativePath
    .replace(/\.html$/i, "")
    .replace(/[^a-zA-Z0-9/_-]/g, "-")
    .replace(/\//g, "-")
    .replace(/-+/g, "-")
    .replace(/^-|-$/g, "")
    .toLowerCase();
  const hash = crypto
    .createHash("sha1")
    .update(`${relativePath}:${index}:${scriptBody}`)
    .digest("hex")
    .slice(0, 12);

  return `${sourceStub || "page"}-${index}-${hash}.js`;
}

function externalizeInlineScripts(html, sourcePath) {
  let scriptIndex = 0;
  const scriptTagRegex = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;

  return html.replace(scriptTagRegex, (fullMatch, attrs = "", body = "") => {
    const attrsLower = attrs.toLowerCase();
    if (/\bsrc\s*=/.test(attrsLower)) {
      return fullMatch;
    }

    if (/\btype\s*=\s*["']application\/ld\+json["']/.test(attrsLower)) {
      return fullMatch;
    }

    if (!body.trim()) {
      return "";
    }

    scriptIndex += 1;
    const outputFileName = makeInlineScriptFileName(sourcePath, scriptIndex, body);
    const inlineJsRelative = path.posix.join("assets", "js", "inline", outputFileName);
    const inlineJsAbsolute = path.join(PUBLIC_DIR, ...inlineJsRelative.split("/"));

    ensureDir(path.dirname(inlineJsAbsolute));
    fs.writeFileSync(inlineJsAbsolute, `${body.trim()}\n`, "utf8");

    const preserveTypeModule = /\btype\s*=\s*["']module["']/.test(attrsLower) ? ' type="module"' : "";
    const preserveNoModule = /\bnomodule\b/.test(attrsLower) ? " nomodule" : "";
    return `<script${preserveTypeModule}${preserveNoModule} src="/${inlineJsRelative}"></script>`;
  });
}

function canonicalizeRoadmapTrackIndexTopicLinks(html, sourcePath) {
  const normalizedPath = sourcePath.replace(/\\/g, "/").toLowerCase();
  const match = normalizedPath.match(/\/public\/roadmap\/([a-z0-9_-]+)\/index\.html$/i);
  if (!match) {
    return html;
  }

  const trackId = match[1].toLowerCase();
  return html.replace(
    /(<tr\b[^>]*\bdata-topic=["']([^"']+)["'][^>]*>[\s\S]*?<a\b[^>]*\bhref=["'])([^"']*)(["'])/gi,
    (fullMatch, prefix, topicId, currentHref, suffix) => {
      const normalizedTopicId = String(topicId || "").trim();
      if (!normalizedTopicId) {
        return fullMatch;
      }

      return `${prefix}/roadmap/${trackId}/${normalizedTopicId}.html${suffix}`;
    }
  );
}

// Gives each track index row a stable anchor so topic pages can scroll back to their row.
function addRoadmapTrackIndexTopicAnchors(html, sourcePath) {
  const normalizedPath = sourcePath.replace(/\\/g, "/").toLowerCase();
  const match = normalizedPath.match(/\/public\/roadmap\/([a-z0-9_-]+)\/index\.html$/i);
  if (!match) {
    return html;
  }

  const trackId = match[1].toLowerCase();
  const topicHrefRegex = new RegExp(`href=["'][^"']*/roadmap/${trackId}/([a-z0-9_-]+)(?:\\.html|/)`, "i");

  const addAnchor = (rowMarkup, tagName, attributes, rowInner) => {
    if (/\bid\s*=/i.test(attributes)) {
      return rowMarkup;
    }

    const dataTopicMatch = attributes.match(/\bdata-topic=["']([^"']+)["']/i);
    const topicId = dataTopicMatch ? dataTopicMatch[1] : (rowInner.match(topicHrefRegex) || [])[1];

    const anchorId = String(topicId || "").trim().replace(/[^a-zA-Z0-9_-]/g, "-");
    if (!anchorId || anchorId.toLowerCase() === "index") {
      return rowMarkup;
    }

    return `<${tagName} id="topic-${anchorId}"${attributes}>${rowInner}</${tagName}>`;
  };

  let transformed = html.replace(/<tr\b([^>]*)>([\s\S]*?)<\/tr>/gi, (rowMarkup, attributes, rowInner) =>
    addAnchor(rowMarkup, "tr", attributes, rowInner)
  );

  transformed = transformed.replace(/<li\b([^>]*)>((?:(?!<li\b)[\s\S])*?)<\/li>/gi, (rowMarkup, attributes, rowInner) =>
    addAnchor(rowMarkup, "li", attributes, rowInner)
  );

  return transformed;
}

function addProjectIndexTopicAnchors(html, sourcePath) {
  const normalizedPath = sourcePath.replace(/\\/g, "/").toLowerCase();
  const match = normalizedPath.match(/\/public\/projects\/([a-z0-9_-]+)\/index\.html$/i);
  if (!match) {
    return html;
  }

  const addAnchor = (rowMarkup, attributes) => {
    if (/\bid\s*=\s*/i.test(attributes)) {
      return rowMarkup;
    }

    const topicMatch = attributes.match(/\bdata-topic=["']([^"']+)["']/i);
    const topicId = topicMatch ? topicMatch[1].trim() : "";
    if (!topicId || topicId.toLowerCase() === "index") {
      return rowMarkup;
    }

    const anchorId = topicId.replace(/[^a-zA-Z0-9_-]/g, "-");
    return rowMarkup.replace(/^(<tr\b)([^>]*)>/i, `$1$2 id="topic-${anchorId}">`);
  };

  return html.replace(/<tr\b([^>]*)>/gi, (rowMarkup, attributes) => addAnchor(rowMarkup, attributes));
}

function optimizeHtmlOutput(html, headerTemplate, footerTemplate, sourcePath) {
  let transformed = html;
  const enforceCommonFooter = shouldEnforceCommonFooter(sourcePath);
  transformed = ensureBootstrapIconsForTopic(transformed);
  transformed = injectInlineHeader(transformed, headerTemplate);
  transformed = injectInlineFooter(transformed, footerTemplate, enforceCommonFooter);
  transformed = injectStaticSidebar(transformed, sourcePath);
  transformed = ensureTopicRuntimeScripts(transformed, sourcePath);
  transformed = injectRoadmapProgressScripts(transformed);
  transformed = ensureReturnToRoadmapLink(transformed, sourcePath);
  transformed = rewriteAssetPaths(transformed);
  if (shouldRelativizeRootLinks(sourcePath)) {
    transformed = relativizeInternalRootLinks(transformed, sourcePath);
  }
  transformed = normalizeSharedBrandAssets(transformed, sourcePath);
  transformed = canonicalizeRoadmapTrackIndexTopicLinks(transformed, sourcePath);
  transformed = addRoadmapTrackIndexTopicAnchors(transformed, sourcePath);
  transformed = addProjectIndexTopicAnchors(transformed, sourcePath);

  // Enforce folder-style routes for top-level hubs.
  transformed = transformed.replace(/\b(href|src)=(['"])([^"']*?)roadmap\.html\2/gi, "$1=$2$3roadmap/$2");
  transformed = transformed.replace(/\b(href|src)=(['"])([^"']*?)community\.html\2/gi, "$1=$2$3community/$2");

  transformed = externalizeInlineScripts(transformed, sourcePath);
  return transformed;
}

function copyAssets() {
  copyRecursive(ASSETS_DIR, path.join(PUBLIC_DIR, "assets"));
}

function copySystemRuntimeFiles() {
  for (const fileName of SYSTEM_RUNTIME_FILES) {
    publishSystemRuntimeFile(fileName);
  }
}

function publishSystemRuntimeFile(fileName) {
  const source = path.join(ROOT, fileName);
  const destination = path.join(PUBLIC_DIR, fileName);

  if (!fs.existsSync(source)) {
    return;
  }

  if (fileName === "sitemap.xml") {
    let sitemap = readTextOrEmpty(source);
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/engineering\//gi, "https://sagecode.org/roadmap/cse/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/programming\//gi, "https://sagecode.org/roadmap/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/cse\//gi, "https://sagecode.org/roadmap/cse/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/csp\//gi, "https://sagecode.org/roadmap/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/csa\//gi, "https://sagecode.org/roadmap/csa/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/dsa\//gi, "https://sagecode.org/roadmap/dsa/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/itc\//gi, "https://sagecode.org/roadmap/hpc/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/hpc\//gi, "https://sagecode.org/roadmap/hpc/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/tek\//gi, "https://sagecode.org/roadmap/tek/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/ops\//gi, "https://sagecode.org/roadmap/tek/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/dba\//gi, "https://sagecode.org/roadmap/dba/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/sml\//gi, "https://sagecode.org/roadmap/sml/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/osd\//gi, "https://sagecode.org/roadmap/osd/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/dsk\//gi, "https://sagecode.org/roadmap/dsk/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/das\//gi, "https://sagecode.org/roadmap/sml/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/csd\//gi, "https://sagecode.org/roadmap/sml/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/roadmap\/csp\//gi, "https://sagecode.org/roadmap/");
    sitemap = sitemap.replace(/https:\/\/sagecode\.org\/pro\//gi, "https://sagecode.org/projects/");
    ensureDir(path.dirname(destination));
    fs.writeFileSync(destination, sitemap, "utf8");
    return;
  }

  copyRecursive(source, destination);
}

function copyLabHtml() {
  if (!fs.existsSync(ROADMAP_LABS_DIR)) {
    return;
  }

  for (const [sourceDirName, publicDirName] of Object.entries(LAB_ROUTE_MAP)) {
    const sourceDir = path.join(ROADMAP_LABS_DIR, sourceDirName);
    const destinationDir = path.join(PUBLIC_DIR, publicDirName);
    copyHtmlOnlyRecursive(sourceDir, destinationDir);
  }
}

function copyLabStaticAssets() {
  if (!fs.existsSync(ROADMAP_LABS_DIR)) {
    return;
  }

  for (const [sourceDirName, publicDirName] of Object.entries(LAB_ROUTE_MAP)) {
    const sourceDir = path.join(ROADMAP_LABS_DIR, sourceDirName);
    const destinationDir = path.join(PUBLIC_DIR, publicDirName);
    copyLabStaticAssetsRecursive(sourceDir, destinationDir);
  }
}

function shouldCopyProjectStaticAsset(fileName) {
  const ext = path.extname(fileName).toLowerCase();
  const staticAssetExtensions = new Set([
    ".png",
    ".jpg",
    ".jpeg",
    ".gif",
    ".svg",
    ".webp",
    ".bmp",
    ".ico",
    ".avif",
    ".mp3",
    ".wav",
    ".ogg",
    ".mp4",
    ".webm",
    ".mov",
    ".m4v",
    ".css",
    ".js",
    ".json",
    ".pdf",
    ".woff",
    ".woff2",
    ".ttf",
    ".otf",
    ".eot"
  ]);

  return staticAssetExtensions.has(ext);
}

function copyCommunityContent() {
  if (!fs.existsSync(COMMUNITY_DIR)) {
    return;
  }

  const destinationDir = path.join(PUBLIC_DIR, "community");
  copyHtmlOnlyRecursive(COMMUNITY_DIR, destinationDir);
  copyProjectStaticAssetsRecursive(COMMUNITY_DIR, destinationDir);
}

function copyProjectStaticAssetsRecursive(src, dest) {
  if (!fs.existsSync(src)) {
    return;
  }

  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
    const sourcePath = path.join(src, entry.name);
    const targetPath = path.join(dest, entry.name);

    if (entry.isDirectory()) {
      copyProjectStaticAssetsRecursive(sourcePath, targetPath);
      continue;
    }

    if (!entry.isFile() || !shouldCopyProjectStaticAsset(entry.name)) {
      continue;
    }

    ensureDir(path.dirname(targetPath));
    fs.copyFileSync(sourcePath, targetPath);
  }
}

function copyProjectContent() {
  if (!fs.existsSync(PROJECTS_DIR)) {
    return;
  }

  const destinationDir = path.join(PUBLIC_DIR, "projects");
  copyHtmlOnlyRecursive(PROJECTS_DIR, destinationDir);
  copyProjectStaticAssetsRecursive(PROJECTS_DIR, destinationDir);
}

function copyRoadmapDirectories() {
  if (!fs.existsSync(ROADMAP_DIR)) {
    return;
  }

  const skipFolders = new Set(["labs"]);

  for (const entry of fs.readdirSync(ROADMAP_DIR, { withFileTypes: true })) {
    if (!entry.isDirectory()) {
      continue;
    }

    const dirName = entry.name.toLowerCase();
    if (skipFolders.has(dirName) || dirName.startsWith(".")) {
      continue;
    }

    const sourceDir = path.join(ROADMAP_DIR, entry.name);
    const destinationDir = path.join(PUBLIC_DIR, "roadmap", entry.name);
    copyHtmlOnlyRecursive(sourceDir, destinationDir);
    copyLabStaticAssetsRecursive(sourceDir, destinationDir);
  }
}

function copyRoadmapLandingPage() {
  const sourceIndex = path.join(ROADMAP_DIR, "index.html");
  if (!fs.existsSync(sourceIndex)) {
    return;
  }

  const destinationIndex = path.join(PUBLIC_DIR, "roadmap", "index.html");
  ensureDir(path.dirname(destinationIndex));
  fs.copyFileSync(sourceIndex, destinationIndex);
}

function copyRoadmapTopLevelPages() {
  if (!fs.existsSync(ROADMAP_DIR)) {
    return;
  }

  for (const entry of fs.readdirSync(ROADMAP_DIR, { withFileTypes: true })) {
    if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".html")) {
      continue;
    }

    if (entry.name.toLowerCase() === "index.html") {
      continue;
    }

    const sourcePath = path.join(ROADMAP_DIR, entry.name);
    const destinationPath = path.join(PUBLIC_DIR, "roadmap", entry.name);
    ensureDir(path.dirname(destinationPath));
    fs.copyFileSync(sourcePath, destinationPath);
  }
}

function buildContentPages() {
  const baseTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "base.html"));
  const headerTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "header.html"));
  const footerTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "footer.html"));

  if (!baseTemplate.trim()) {
    return { pageCount: 0, renderedPages: [] };
  }

  const sourceFiles = collectTopLevelHtmlFiles(ROOT_PAGES_DIR);
  const renderedPages = [];

  for (const sourceFile of sourceFiles) {
    const content = readTextOrEmpty(sourceFile);
    const relativePath = path.basename(sourceFile);
    const destinationPath = path.join(PUBLIC_DIR, relativePath);

    const isFullDocument = /<html[\s>]/i.test(content) && /<body[\s>]/i.test(content);
    const output = isFullDocument
      ? content
      : renderFromTemplate(content, sourceFile, {
          baseTemplate,
          headerTemplate,
          footerTemplate
        });

    const optimizedOutput = optimizeHtmlOutput(output, headerTemplate, footerTemplate, destinationPath);

    ensureDir(path.dirname(destinationPath));
    fs.writeFileSync(destinationPath, optimizedOutput, "utf8");
    renderedPages.push(relativePath);
  }

  return {
    pageCount: renderedPages.length,
    renderedPages
  };
}

function sourcePathToPublishedPath(sourcePath) {
  if (isPathInside(sourcePath, ASSETS_DIR)) {
    return path.join(PUBLIC_DIR, "assets", path.relative(ASSETS_DIR, sourcePath));
  }

  if (isPathInside(sourcePath, PROJECTS_DIR)) {
    return path.join(PUBLIC_DIR, "projects", path.relative(PROJECTS_DIR, sourcePath));
  }

  if (isPathInside(sourcePath, COMMUNITY_DIR)) {
    return path.join(PUBLIC_DIR, "community", path.relative(COMMUNITY_DIR, sourcePath));
  }

  if (isPathInside(sourcePath, ROADMAP_LABS_DIR)) {
    const relative = path.relative(ROADMAP_LABS_DIR, sourcePath);
    const parts = relative.split(path.sep);
    const sourceRoute = parts.shift();
    const publishedRoute = LAB_ROUTE_MAP[sourceRoute];
    if (!publishedRoute) {
      return null;
    }
    return path.join(PUBLIC_DIR, publishedRoute, ...parts);
  }

  if (isPathInside(sourcePath, ROADMAP_DIR)) {
    const relative = path.relative(ROADMAP_DIR, sourcePath);
    const parts = relative.split(path.sep);
    if (!parts.length) {
      return null;
    }

    if (parts[0].toLowerCase() === "labs") {
      return null;
    }

    if (parts.length === 1) {
      const fileName = parts[0];
      if (fileName.toLowerCase() === "index.html") {
        return path.join(PUBLIC_DIR, "roadmap", "index.html");
      }
      return path.join(PUBLIC_DIR, "roadmap", fileName);
    }

    return path.join(PUBLIC_DIR, "roadmap", ...parts);
  }

  return null;
}

function isRootRuntimeSourceFile(sourcePath) {
  const fileName = path.basename(sourcePath);
  return path.dirname(sourcePath) === ROOT && SYSTEM_RUNTIME_FILES.includes(fileName);
}

function isRootContentHtmlFile(sourcePath) {
  if (path.dirname(sourcePath) !== ROOT) {
    return false;
  }

  const lower = sourcePath.toLowerCase();
  return lower.endsWith(".html");
}

function shouldPublishSourceAsset(sourcePath) {
  const ext = path.extname(sourcePath).toLowerCase();

  if (isPathInside(sourcePath, PROJECTS_DIR) || isPathInside(sourcePath, COMMUNITY_DIR)) {
    return shouldCopyProjectStaticAsset(sourcePath);
  }

  if (isPathInside(sourcePath, ROADMAP_DIR) || isPathInside(sourcePath, ROADMAP_LABS_DIR) || isPathInside(sourcePath, ASSETS_DIR)) {
    return shouldCopyLabStaticAsset(sourcePath);
  }

  return false;
}

function shouldPublishHtmlFromSource(sourcePath) {
  const lower = sourcePath.toLowerCase();
  if (!lower.endsWith(".html")) {
    return false;
  }

  if (path.basename(lower) === "template.html") {
    return false;
  }

  if (isRootContentHtmlFile(sourcePath)) {
    return false;
  }

  return true;
}

function publishChangedSourceFile(sourcePath, optimizedHtmlTargets) {
  if (isRootRuntimeSourceFile(sourcePath)) {
    publishSystemRuntimeFile(path.basename(sourcePath));
    return;
  }

  if (isRootContentHtmlFile(sourcePath)) {
    return;
  }

  if (isPathInside(sourcePath, LAYOUTS_DIR)) {
    return;
  }

  const destinationPath = sourcePathToPublishedPath(sourcePath);
  if (!destinationPath) {
    return;
  }

  if (shouldPublishHtmlFromSource(sourcePath)) {
    ensureDir(path.dirname(destinationPath));
    fs.copyFileSync(sourcePath, destinationPath);
    optimizedHtmlTargets.add(destinationPath);
    return;
  }

  if (shouldPublishSourceAsset(sourcePath)) {
    ensureDir(path.dirname(destinationPath));
    fs.copyFileSync(sourcePath, destinationPath);
    return;
  }

  if (sourcePath.toLowerCase().endsWith(".json") && isPathInside(sourcePath, ROADMAP_DIR)) {
    const siblingHtmlSource = sourcePath.replace(/\.json$/i, ".html");
    const siblingPublishedPath = sourcePathToPublishedPath(siblingHtmlSource);
    if (siblingPublishedPath && fs.existsSync(siblingPublishedPath)) {
      optimizedHtmlTargets.add(siblingPublishedPath);
    }
  }
}

function deletePublishedSourceTarget(sourcePath) {
  if (isRootRuntimeSourceFile(sourcePath)) {
    const destination = path.join(PUBLIC_DIR, path.basename(sourcePath));
    if (fs.existsSync(destination)) {
      fs.rmSync(destination, { force: true });
    }
    return;
  }

  if (isRootContentHtmlFile(sourcePath) || isPathInside(sourcePath, LAYOUTS_DIR)) {
    return;
  }

  const destinationPath = sourcePathToPublishedPath(sourcePath);
  if (!destinationPath || !fs.existsSync(destinationPath)) {
    return;
  }

  fs.rmSync(destinationPath, { force: true });
}

function optimizePublishedHtmlTargets(targetPaths) {
  if (!targetPaths || targetPaths.size === 0) {
    return;
  }

  const headerTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "header.html"));
  const footerTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "footer.html"));

  for (const filePath of targetPaths) {
    if (!fs.existsSync(filePath)) {
      continue;
    }

    const current = readTextOrEmpty(filePath);
    const transformed = optimizeHtmlOutput(current, headerTemplate, footerTemplate, filePath);
    if (transformed !== current) {
      fs.writeFileSync(filePath, transformed, "utf8");
    }
  }
}

function optimizePublishedHtmlFiles() {
  const headerTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "header.html"));
  const footerTemplate = readTextOrEmpty(path.join(LAYOUTS_DIR, "footer.html"));
  const htmlFiles = collectHtmlFiles(PUBLIC_DIR);
  for (const filePath of htmlFiles) {
    const current = readTextOrEmpty(filePath);
    const transformed = optimizeHtmlOutput(current, headerTemplate, footerTemplate, filePath);
    if (transformed !== current) {
      fs.writeFileSync(filePath, transformed, "utf8");
    }
  }
}

function writeBuildManifest(contentResult) {
  const manifest = {
    generatedAtUtc: new Date().toISOString(),
    pageCount: contentResult.pageCount,
    renderedPages: contentResult.renderedPages,
    maintenanceMode: (process.env.MIGRATION_MAINTENANCE_MODE || "false").toLowerCase() === "true",
    strategy: "incremental-static-migration"
  };

  fs.writeFileSync(
    path.join(ROOT, "manual", "build-manifest.json"),
    JSON.stringify(manifest, null, 2),
    "utf8"
  );
}

function generateRoadmapIndex() {
  try {
    // Detect Python executable (python, python3, or py)
    let pythonCmd = "python";
    try {
      execSync(`${pythonCmd} --version`, { stdio: "pipe" });
    } catch {
      try {
        pythonCmd = "python3";
        execSync(`${pythonCmd} --version`, { stdio: "pipe" });
      } catch {
        pythonCmd = "py";
        execSync(`${pythonCmd} --version`, { stdio: "pipe" });
      }
    }

    // Run roadmap.py
    execSync(`${pythonCmd} scripts/tools/roadmap.py`, { stdio: "inherit" });

  } catch (error) {
    console.error("[WARN] Failed to generate roadmap index:", error.message);
  }
}

function runFullBuild() {
  cleanPublicDir();
  copyAssets();
  writeSupabaseConfigAsset();
  copySystemRuntimeFiles();
  copyLabHtml();
  copyLabStaticAssets();
  copyProjectContent();
  copyCommunityContent();
  copyRoadmapDirectories();
  copyRoadmapTopLevelPages();
  copyRoadmapLandingPage();
  const contentResult = buildContentPages();
  optimizePublishedHtmlFiles();
  return contentResult;
}

function runIncrementalBuild(changedFiles, deletedFiles, options = {}) {
  ensureDir(PUBLIC_DIR);
  writeSupabaseConfigAsset();

  const optimizedHtmlTargets = new Set();

  for (const sourcePath of deletedFiles) {
    deletePublishedSourceTarget(sourcePath);
  }

  for (const sourcePath of changedFiles) {
    publishChangedSourceFile(sourcePath, optimizedHtmlTargets);
  }

  const contentResult = buildContentPages();

  if (options.forceGlobalHtmlOptimization) {
    optimizePublishedHtmlFiles();
  } else {
    optimizePublishedHtmlTargets(optimizedHtmlTargets);
  }

  return contentResult;
}

function main() {
  generateRoadmapIndex();

  const previousCache = loadBuildCache();
  const sourceFiles = collectBuildInputFiles();
  const currentHashes = createSourceHashMap(sourceFiles);
  const diff = diffSourceHashes(previousCache ? previousCache.sourceHashes : {}, currentHashes);

  const baseTemplatePath = path.join(LAYOUTS_DIR, "base.html");
  const headerPath = path.join(LAYOUTS_DIR, "header.html");
  const footerPath = path.join(LAYOUTS_DIR, "footer.html");
  const buildScriptChanged = diff.changed.includes(__filename) || diff.deleted.includes(__filename);
  const forceFullBuild = (process.env.BUILD_MODE || "").toLowerCase() === "full";
  const hasCache = Boolean(previousCache);
  const publicReady = fs.existsSync(PUBLIC_DIR);
  const baseTemplateChanged =
    diff.changed.includes(baseTemplatePath) || diff.deleted.includes(baseTemplatePath);
  const headerOrFooterChanged =
    diff.changed.includes(headerPath) ||
    diff.changed.includes(footerPath) ||
    diff.deleted.includes(headerPath) ||
    diff.deleted.includes(footerPath);

  const requiresFullBuild = forceFullBuild || !hasCache || !publicReady || baseTemplateChanged || buildScriptChanged;

  const contentResult = requiresFullBuild
    ? runFullBuild()
    : runIncrementalBuild(diff.changed, diff.deleted, {
        forceGlobalHtmlOptimization: headerOrFooterChanged
      });

  const modeLabel = requiresFullBuild ? "full" : "differential";
  writeBuildManifest(contentResult);
  saveBuildCache(currentHashes, modeLabel);

  console.log(
    `Build complete (${modeLabel}). Rendered ${contentResult.pageCount} page(s) from roadmap root.`
  );
  runCssValidation();
}

main();


// Run CSS Validation after build
function runCssValidation() {
    console.log("Running CSS Validation...");
    try {
        const { execSync } = require("node:child_process");
        execSync("node scripts/validate-css.js", { stdio: "inherit" });
        console.log("CSS Validation passed.");
    } catch (error) {
        console.error("CSS Validation failed!");
        process.exit(1);
    }
}