prestruct 0.0.0-stage → 1.0.0

package/engine/scripts/inject-brand.js

@@ -0,0 +1,430 @@
+/**
+ * scripts/inject-brand.js
+ * =======================
+ * Canonical engine source (engine/scripts/inject-brand.js). Deployed copies at
+ * scripts/inject-brand.js in init/ and example/ are generated byte-identically
+ * by scripts/sync-engine.mjs -- edit the engine, never the copies.
+ *
+ * Post-build script. Runs after `vite build` via `npm run build`.
+ * Reads ssr.config.js and injects all head meta into dist/index.html:
+ *   - <title>
+ *   - <meta name="description">
+ *   - <meta name="author">
+ *   - <meta name="keywords">
+ *   - <link rel="canonical">
+ *   - Open Graph tags (og:type, og:url, og:title, og:description, og:image, og:site_name)
+ *   - Twitter Card tags
+ *   - JSON-LD structured data (from config.buildJsonLd())
+ *   - <meta name="deploy-id"> with build identifier
+ *
+ * Deploy ID behavior (see init/ssr.config.example.js):
+ *   - deployId: true        -- inject <meta name="deploy-id"> (default: true)
+ *   - deployIdFooter: false -- show deploy ID in the app footer via
+ *                              data-deploy-id-footer on the root div.
+ *                              Opt-in (default: false). The attribute travels
+ *                              on the root div and survives prerendering
+ *                              (prerender.js carries root-div attrs -- W8).
+ *
+ * If config.proxy.url is set, also updates dist/_headers to add the proxy
+ * origin to connect-src. This is done precisely: it finds the existing
+ * connect-src directive and appends only if the origin isn't already there.
+ * Running the build twice is safe -- no duplicate entries.
+ *
+ * Module surface (importable for tests; CLI logic only runs when executed):
+ *   toReplaceSafe(value)
+ *   generateTitle(siteName, tagline)
+ *   injectBrand(config, distDir, { getDeployId })
+ *
+ * Fails gracefully -- exits 0 on any error so a bad config never blocks deployment.
+ * The site will still deploy as a working SPA without prerendered meta.
+ * Set PRESTRUCT_STRICT=1 to fail on config diagnostics instead.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+import { join, resolve, dirname } from 'path'
+import { execSync } from 'child_process'
+import { fileURLToPath, pathToFileURL } from 'url'
+
+import { validateConfig, formatDiagnostics } from './validate-config.js'
+
+// -- Replacement safety --------------------------------------------------------
+
+/**
+ * Neutralize replacement-pattern characters ($&, $1, ...) so user copy can
+ * safely be used as a String.replace() replacement string.
+ *
+ * @param {string} value - raw brand/config value
+ * @returns {string} replacement-safe text
+ */
+export function toReplaceSafe(value) {
+  return (value == null ? '' : String(value).replace(/\$/g, '$$$$'))
+}
+
+// HTML attribute/text escaping for values landed in the shell's head tags.
+// Meta values go into content="..." attributes (and <title> text): a `"` in
+// a description silently breaks the attribute, and `</title>` in a title
+// injects markup onto every page. applied BEFORE toReplaceSafe, which only
+// handles replace() $-semantics.
+/**
+ * Escape HTML-significant characters for attribute contexts (quotes, angle
+ * brackets, ampersands).
+ *
+ * @param {string} value - raw value
+ * @returns {string} attribute-safe value
+ */
+export function escapeHtmlAttr(value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+// -- Title generation ---------------------------------------------------------
+
+/**
+ * Compose the SEO title as "siteName | tagline" with the tagline trimmed
+ * when absent.
+ *
+ * @param {string} siteName - configured site name
+ * @param {string} tagline - configured tagline
+ * @returns {string} composed title
+ */
+export function generateTitle(siteName, tagline) {
+  return siteName ? (tagline ? `${siteName} | ${tagline}` : siteName) : 'Site'
+}
+
+// -- Deploy ID ----------------------------------------------------------------
+
+// Generate deploy ID from git commit hash + short timestamp
+function defaultGetDeployId() {
+  // Stable per commit. The OLD shape appended a random base36 timestamp,
+  // which changed the shell on EVERY build -- and because prerender's cache
+  // signature covers the whole shell, that defeated the incremental cache
+  // on every deployId:true project (SEO/perf audit 2026-10-20: warm
+  // rebuilds re-rendered 8/8 pages). Per-deploy identity belongs to the
+  // hosting platform (CF Pages deployment id), not the HTML; the shell
+  // still invalidates the cache honestly when content actually changes
+  // (vite asset hashes + meta live in the same signature).
+  try {
+    return execSync('git rev-parse --short HEAD 2>/dev/null', { encoding: 'utf8' }).trim()
+  } catch {
+    return 'dev-local'
+  }
+}
+
+// -- Main injection flow ------------------------------------------------------
+// export function injectBrand(config, distDir, { getDeployId } = {})
+//   config  : loaded ssr.config.js (validated first)
+//   distDir : absolute path to the build output (defaults ./dist)
+//   getDeployId : injectable for tests; defaults to git-hash generator
+
+/**
+ * Stamp the global brand meta into dist/index.html: title, description, OG,
+ * Twitter card, JSON-LD, deploy-id, canonical, keywords. Idempotent on
+ * rebuild (previously injected blocks are replaced). Library-safe: returns,
+ * never exits.
+ *
+ * @param {object} config - full ssr.config.js export
+ * @param {string} [distDir=resolve('dist')] - build output directory
+ * @param {{getDeployId?: Function, projectRoot?: string}} [opts] - injection hooks
+ * @returns {void}
+ */
+export function injectBrand(config, distDir = resolve('dist'), { getDeployId = defaultGetDeployId, projectRoot } = {}) {
+  const {
+    platform = 'cloudflare',
+    siteUrl, siteName, author, tagline, ogImage, keywords,
+    routes = [], buildJsonLd, proxy = {},
+  } = config
+
+  // Only generate Cloudflare-specific files (_headers, _redirects)
+  // Future: vercel gets vercel.json, netlify gets netlify.toml
+  if (platform === 'cloudflare') {
+    // _headers and _redirects are copied from init/public/ at build time
+    // This section reserved for any CF-specific injection logic
+  }
+
+  const htmlPath = join(distDir, 'index.html')
+
+  if (!existsSync(htmlPath)) {
+    console.warn('[inject-brand] dist/index.html not found -- skipping')
+    process.exit(0)
+  }
+
+  // Homepage meta as the global description fallback
+  const homeRoute   = routes.find(r => r.path === '/') || {}
+  const title       = generateTitle(siteName, tagline)
+  const description = homeRoute.meta?.description || null
+  const canonical   = `${siteUrl}/`
+
+  const titleSafe       = toReplaceSafe(escapeHtmlAttr(title))
+  const descriptionSafe = toReplaceSafe(escapeHtmlAttr(description))
+  const authorSafe      = toReplaceSafe(escapeHtmlAttr(author))
+  const keywordsSafe    = toReplaceSafe(escapeHtmlAttr(keywords))
+  const canonicalSafe   = toReplaceSafe(escapeHtmlAttr(canonical))
+  const ogImageSafe     = toReplaceSafe(escapeHtmlAttr(ogImage))
+  const siteNameSafe    = toReplaceSafe(escapeHtmlAttr(siteName))
+
+  let html = readFileSync(htmlPath, 'utf8')
+
+  // -- Deploy ID --------------------------------------------------------------
+
+  // Deploy ID meta tag is on by default. Footer display is opt-in (default false).
+  const deployIdEnabled = config.deployId !== false
+  const showFooter = config.deployIdFooter === true
+
+  if (deployIdEnabled) {
+    const deployId = getDeployId()
+    console.log(`  Deploy ID: ${deployId}`)
+
+    // Remove previously injected deploy-id (safe to run on rebuild)
+    html = html.replace(/<meta name="deploy-id"[^>]*>/g, '')
+
+    // Inject deploy-id meta tag
+    html = html.replace('</head>', `  <meta name="deploy-id" content="${deployId}" />\n</head>`)
+  } else {
+    // Remove any existing deploy-id meta tag if disabled
+    html = html.replace(/<meta name="deploy-id"[^>]*>/g, '')
+    console.log('  Deploy ID: disabled')
+  }
+
+  // Footer attribute is separate from the meta tag: applied when opted in,
+  // stripped when not (safe to run on rebuild either way). It travels on the
+  // root div and is carried through prerendering by replaceRootDiv.
+  if (showFooter) {
+    html = html.replace(/<div id="root"/, '<div id="root" data-deploy-id-footer')
+  } else {
+    html = html.replace(/ data-deploy-id-footer/g, '')
+  }
+
+  // -- Primary meta -----------------------------------------------------------
+
+  // Title regex deliberately has no dotall 's' flag: shells can carry the
+  // string '<title>' inside HTML comments (build instructions), and a dotall
+  // match would pair that comment fragment with the REAL closing </title> far
+  // below -- corrupting the comment tree and landing the replacement in the
+  // wrong place. Single-line matching means fake occurrences without a
+  // matching closer are skipped automatically. Caught by the tarball e2e pass.
+  html = html.replace(/<title>[^<]*<\/title>/,
+    `<title>${titleSafe}</title>`)
+
+  if (description) {
+    html = html.replace(/<meta name="description"[^>]*>/,
+      `<meta name="description" content="${descriptionSafe}" />`)
+  }
+
+  html = html.replace(/<meta name="author"[^>]*>/,
+    `<meta name="author" content="${authorSafe}" />`)
+
+  if (keywords) {
+    html = html.replace(/<meta name="keywords"[^>]*>/,
+      `<meta name="keywords" content="${keywordsSafe}" />`)
+  }
+
+  html = html.replace(/<link rel="canonical"[^>]*>/,
+    `<link rel="canonical" href="${canonicalSafe}" />`)
+
+  // -- Remove previously injected OG / JSON-LD blocks (safe to run on rebuild) --
+
+  html = html.replace(/\n\s*<!-- Open Graph -->[\s\S]*?<\/script>\s*/g, '\n  ')
+
+  // -- Open Graph + Twitter Card -----------------------------------------------
+
+  // Only include image tags if ogImage is provided
+  const imageMeta = ogImage ? `
+    <meta property="og:image"        content="${ogImageSafe}" />
+    <meta name="twitter:image"       content="${ogImageSafe}" />` : ''
+
+  const ogTags = `
+    <!-- Open Graph -->
+    <meta property="og:type"         content="website" />
+    <meta property="og:url"          content="${canonicalSafe}" />
+    <meta property="og:title"        content="${titleSafe}" />
+    <meta property="og:description"  content="${descriptionSafe}" />${imageMeta}
+    <meta property="og:locale"       content="en_US" />
+    <meta property="og:site_name"    content="${siteNameSafe}" />
+
+    <!-- Twitter / X Card -->
+    <meta name="twitter:card"        content="summary_large_image" />
+    <meta name="twitter:title"       content="${titleSafe}" />
+    <meta name="twitter:description" content="${descriptionSafe}" />`
+
+  // -- JSON-LD ----------------------------------------------------------------
+
+  let jsonLdBlock = ''
+  if (typeof buildJsonLd === 'function') {
+    const jsonLdData = buildJsonLd.call(config)
+    // Documented contract (ssr.config.example.js): accept a single bare
+    // object OR an array of objects. The array-only check used to silently
+    // drop the most common shape a consumer writes, while the config example
+    // promised object support -- caught in the crashtest vendored-copy diff.
+    const payload = Array.isArray(jsonLdData)
+      ? (jsonLdData.length === 0
+          ? null
+          : jsonLdData.length === 1
+            ? jsonLdData[0]
+            : { '@context': 'https://schema.org', '@graph': jsonLdData })
+      : (jsonLdData && typeof jsonLdData === 'object' ? jsonLdData : null)
+    if (payload) {
+      jsonLdBlock = `
+    <!-- JSON-LD Structured Data -- generated from ssr.config.js -->
+    <script type="application/ld+json">
+    ${JSON.stringify(payload, null, 2).replace(/</g, '\\u003c')}
+    </script>`
+    }
+  }
+
+  const jsonLdBlockSafe = toReplaceSafe(jsonLdBlock)
+
+  html = html.replace('</head>', `${ogTags}\n${jsonLdBlockSafe}\n  </head>`)
+
+  writeFileSync(htmlPath, html, 'utf8')
+
+  console.log('[inject-brand] injection complete')
+  console.log(`  Title:     ${title}`)
+  console.log(`  Canonical: ${canonical}`)
+
+  // -- CSP update for proxy origin --------------------------------------------
+  // Only runs when config.proxy.url is set.
+  // Appends the proxy origin to the connect-src directive in dist/_headers.
+  // Safe to run multiple times -- checks for existing entry before appending.
+
+  const headersPath = join(distDir, '_headers')
+
+  if (proxy?.url && existsSync(headersPath)) {
+    try {
+      const proxyOrigin = new URL(proxy.url).origin
+
+      let headers = readFileSync(headersPath, 'utf8')
+
+      // Match the full connect-src value up to (but not including) the semicolon
+      const connectSrcRegex = /(Content-Security-Policy:[^\n]*connect-src\s+)([^;]+)/
+
+      const match = headers.match(connectSrcRegex)
+      if (!match) {
+        console.warn('[inject-brand] connect-src not found in _headers -- skipping CSP update')
+      } else {
+        const existing = match[2]
+        if (existing.includes(proxyOrigin)) {
+          console.log(`[inject-brand] CSP already contains proxy origin (${proxyOrigin}) -- skipping`)
+        } else {
+          // Append the proxy origin cleanly, trimming any trailing whitespace first
+          headers = headers.replace(connectSrcRegex, `$1${existing.trimEnd()} ${proxyOrigin}`)
+          writeFileSync(headersPath, headers, 'utf8')
+          console.log(`[inject-brand] CSP connect-src updated with proxy origin: ${proxyOrigin}`)
+        }
+      }
+    } catch (err) {
+      // A bad proxyUrl is a config mistake, not a build-blocker
+      console.warn('[inject-brand] CSP update failed:', err.message)
+    }
+  }
+
+  // -- Worker bot list sync --------------------------------------------------
+  // The VPS proxy (scripts/proxy.js) reads config.proxy.botList from
+  // ssr.config.js at startup, but the Cloudflare Worker has no build-time
+  // config access -- its list is embedded in scripts/proxy.worker.js.
+  // Embed it here so a botList change only ever means editing ssr.config.js
+  // and rebuilding. The file may legitimately not exist (proxy is optional,
+  // example/ has none) -- skip silently in that case.
+  syncProxyBotList(config, projectRoot || dirname(resolve(distDir)))
+}
+
+// Replaces the BOT_LIST array literal inside scripts/proxy.worker.js with
+// config.proxy.botList. Idempotent: no write when the content is identical.
+// Returns true if the file was found and is in sync (written or already equal).
+/**
+ * Rewrite config.proxy.botList entries into the wire files that ship so the
+ * scaffolded VPS/Worker proxies stay in parity with the config.
+ *
+ * @param {object} config - full ssr.config.js export
+ * @param {string} projectRoot - project root containing the wire files
+ * @returns {void}
+ */
+export function syncProxyBotList(config, projectRoot) {
+  const proxy = (config && config.proxy) || {}
+  const botList = proxy.botList
+  if (!proxy.url || !Array.isArray(botList) || botList.length === 0) return false
+
+  const workerPath = join(projectRoot, 'scripts', 'proxy.worker.js')
+  if (!existsSync(workerPath)) return false
+
+  try {
+    const worker = readFileSync(workerPath, 'utf8')
+    const tokensSafe = botList
+      .map(t => String(t).replace(/\\/g, '\\\\').replace(/'/g, "\\'"))
+      .map(t => `  '${t}',`)
+      .join('\n')
+    const replacement = `const BOT_LIST = [\n${tokensSafe}\n]`
+
+    // Match the BOT_LIST declaration up to its closing bracket line. The
+    // array only ever contains single-quoted token lines, so \n] is the end.
+    const regex = /const BOT_LIST = \[[\s\S]*?\n\]/
+    if (!regex.test(worker)) {
+      console.warn('[inject-brand] BOT_LIST array not found in scripts/proxy.worker.js -- skipping sync')
+      return false
+    }
+
+    // Function form replacer: a string second-arg would expand "$&"-shaped
+    // patterns inside bot tokens (replace() special sequences). A function
+    // replacer treats the computed replacement literally.
+    const next = worker.replace(regex, () => replacement)
+    if (next !== worker) {
+      writeFileSync(workerPath, next, 'utf8')
+      console.log(`[inject-brand] BOT_LIST synced from ssr.config.js (${botList.length} bots) -> scripts/proxy.worker.js`)
+    } else {
+      console.log('[inject-brand] BOT_LIST already in sync with ssr.config.js')
+    }
+    return true
+  } catch (err) {
+    // A mangled worker file is a manual-edit problem, not a build-blocker
+    console.warn('[inject-brand] Worker bot list sync failed:', err.message)
+    return false
+  }
+}
+
+// -- CLI entry ----------------------------------------------------------------
+// Only runs when executed directly (node scripts/inject-brand.js) -- never on import.
+
+/**
+ * True when this module was executed directly (node scripts/inject-brand.js);
+ * library importers never trigger the CLI wrapper.
+ *
+ * @returns {boolean}
+ */
+export function isMainExecute() {
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1] || '').href
+  } catch {
+    return false
+  }
+}
+
+if (isMainExecute()) {
+  (async () => {
+    let config
+    try {
+      config = (await import('../ssr.config.js')).default
+    } catch (err) {
+      console.warn('[inject-brand] Could not load ssr.config.js -- skipping:', err.message)
+      process.exit(0)
+    }
+
+    // Validate required siteUrl
+    const { ok, errors } = validateConfig(config)
+    if (!ok) {
+      formatDiagnostics(errors).forEach(line => console.error(line))
+      if (process.env.PRESTRUCT_STRICT === '1') {
+        console.error('[inject-brand] PRESTRUCT_STRICT=1 -- failing build on config diagnostics')
+        process.exit(1)
+      }
+    }
+    if (!config.siteUrl) {
+      console.warn('[inject-brand] siteUrl is required in ssr.config.js -- skipping')
+      process.exit(0)
+    }
+
+    injectBrand(config, resolve(process.env.PRESTRUCT_DIST || 'dist'))
+  })()
+}