@koehler8/cms 1.0.0-beta.35 → 1.0.0-beta.37

package/bin/cms-ssg-build.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin wrapper that runs the memory-bounded SSG build orchestrator from the
+// consuming site's cwd. The script does its own argument handling, spawns the
+// per-shard `vite-ssg build` processes, and prints its own status.
+// See scripts/ssg-build/index.mjs and SSG-MEMORY-PLAN.md.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+await import(path.resolve(__dirname, '..', 'scripts', 'ssg-build', 'index.mjs'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.35",
+  "version": "1.0.0-beta.37",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -54,6 +54,7 @@
   },
   "bin": {
     "cms-generate-public-assets": "./bin/cms-generate-public-assets.js",
+    "cms-ssg-build": "./bin/cms-ssg-build.js",
     "cms-migrate-image-variants": "./bin/cms-migrate-image-variants.js",
     "cms-validate-themes": "./bin/cms-validate-themes.js",
     "cms-validate-extensions": "./bin/cms-validate-extensions.js",
@@ -87,13 +88,13 @@
     "dotenv": "^17.2.3",
     "pinia": "^3.0.1",
     "png-to-ico": "^3.0.1",
-    "sharp": "^0.33.5"
+    "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@vue/test-utils": "^2.4.10",
     "happy-dom": "^20.9.0",
     "vitest": "^4.1.6",
-    "vue": "^3.5.34",
+    "vue": "^3.5.39",
     "vue-router": "^5.0.7"
   },
   "engines": {

package/scripts/ssg-build/index.mjs

@@ -0,0 +1,197 @@
+/**
+ * cms-ssg-build — memory-bounded SSG pre-render (the durable fix for the
+ * per-route heap accumulation in vite-ssg's single-process render; see
+ * SSG-MEMORY-PLAN.md).
+ *
+ * vite-ssg renders every route in one Node process and leaves a fixed retained
+ * cost per route, so peak heap scales with total routes (pages × locales) and
+ * large sites OOM. This orchestrator runs the render as N separate
+ * `vite-ssg build` processes, each handling a slice of the routes (via the
+ * framework's CMS_SSG_SHARD hook) into its own outDir, then merges the shards
+ * into dist/. Because each shard is its own process, memory is reclaimed
+ * between shards — peak heap is bounded by SLICE size, not total routes,
+ * independent of how large the site grows.
+ *
+ * Shards run sequentially by default: that gives the LOWEST peak memory (one
+ * shard live at a time), which is the whole point. Parallelism would trade that
+ * back for build speed and also races on the plugin's shared writes to the site
+ * root, so it stays opt-in/experimental.
+ *
+ * Small sites (≤ one shard) fall through to a single ordinary `vite-ssg build`,
+ * byte-identical to today.
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const CWD = process.cwd();
+const TAG = '[cms-ssg-build]';
+
+function parseArgs(argv) {
+  const opts = {
+    shardSize: 150, // routes per shard
+    concurrency: 1, // sequential by default (lowest peak memory + no shared-write race)
+    heap: 2048, // per-shard --max-old-space-size (MB); a slice fits comfortably
+    siteDir: './site',
+    passthrough: [], // forwarded verbatim to `vite-ssg build`
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--shard-size') opts.shardSize = Number(argv[++i]) || opts.shardSize;
+    else if (a === '--concurrency') opts.concurrency = Math.max(1, Number(argv[++i]) || 1);
+    else if (a === '--heap') opts.heap = Number(argv[++i]) || opts.heap;
+    else if (a === '--site-dir') opts.siteDir = argv[++i] || opts.siteDir;
+    else opts.passthrough.push(a);
+  }
+  return opts;
+}
+
+// Estimate the route count the same way the Vite plugin discovers routes
+// (base-locale pages × content locales, + /404 + /admin). Only used to choose
+// the shard count N; the framework's CMS_SSG_SHARD filter partitions whatever
+// routes actually exist, so an approximate N still yields a correct, complete
+// dist/ — it just tunes slice sizes.
+function estimateRouteCount(siteDir) {
+  const contentDir = path.join(siteDir, 'content');
+  let baseLocale = 'en';
+  try {
+    baseLocale = JSON.parse(fs.readFileSync(path.join(contentDir, 'content.config.json'), 'utf8')).baseLocale || 'en';
+  } catch { /* default en */ }
+
+  let pages = 1;
+  try {
+    pages = fs.readdirSync(path.join(contentDir, baseLocale, 'pages')).filter((f) => f.endsWith('.json')).length || 1;
+  } catch { /* single page */ }
+
+  let locales = 1;
+  try {
+    locales = fs.readdirSync(contentDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .filter((d) => {
+        const dir = path.join(contentDir, d.name);
+        return fs.existsSync(path.join(dir, 'site.json'))
+          || fs.existsSync(path.join(dir, 'shared.json'))
+          || fs.existsSync(path.join(dir, 'pages'));
+      }).length || 1;
+  } catch { /* single locale */ }
+
+  return pages * locales + 2; // + /404 + /admin
+}
+
+function resolveViteSsgBin() {
+  const local = path.join(CWD, 'node_modules', '.bin', 'vite-ssg');
+  return fs.existsSync(local) ? local : 'vite-ssg';
+}
+
+function runViteSsg({ shard, outDir, heap, passthrough }) {
+  return new Promise((resolve) => {
+    const env = { ...process.env };
+    if (shard) env.CMS_SSG_SHARD = shard;
+    if (outDir) env.CMS_SSG_OUTDIR = outDir;
+    // A shard renders a bounded slice, so a modest heap suffices — this is what
+    // lets sites drop the 8 GB stop-loss flag. Strip any inherited
+    // --max-old-space-size and set our own.
+    const base = (process.env.NODE_OPTIONS || '').replace(/--max-old-space-size=\d+/g, '').trim();
+    env.NODE_OPTIONS = `${base} --max-old-space-size=${heap}`.trim();
+
+    const child = spawn(resolveViteSsgBin(), ['build', ...passthrough], { cwd: CWD, env });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { out += d; });
+    child.on('close', (code) => resolve({ code, out }));
+    child.on('error', (err) => resolve({ code: 1, out: String(err && err.stack ? err.stack : err) }));
+  });
+}
+
+async function pool(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await worker(items[i], i);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
+// Union-merge every shard's output into dist/. Shared files (assets/, sitemap,
+// robots, manifest, favicon, 404.html) are byte-identical across shards, and
+// per-route HTML files are disjoint — so a plain overwrite-merge is a clean
+// union. The ONE exception is dist/index.html: only the shard that rendered `/`
+// produced the real home page; every other shard's client build left a
+// hydration shell there. So after merging, restore the rendered home
+// explicitly (identified by the data-server-rendered marker).
+async function mergeShards(shardDirs, finalDist) {
+  await fsp.rm(finalDist, { recursive: true, force: true });
+  await fsp.mkdir(finalDist, { recursive: true });
+  for (const dir of shardDirs) {
+    await fsp.cp(dir, finalDist, { recursive: true, force: true });
+  }
+
+  let renderedHome = null;
+  for (const dir of shardDirs) {
+    try {
+      const html = await fsp.readFile(path.join(dir, 'index.html'), 'utf8');
+      if (html.includes('data-server-rendered="true"')) { renderedHome = html; break; }
+    } catch { /* shard has no index.html */ }
+  }
+  if (renderedHome != null) {
+    await fsp.writeFile(path.join(finalDist, 'index.html'), renderedHome, 'utf8');
+  } else {
+    console.warn(`${TAG} warning: no shard produced a server-rendered home page; dist/index.html left as the client shell.`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const siteDir = path.resolve(CWD, opts.siteDir);
+  const estRoutes = estimateRouteCount(siteDir);
+  const N = Math.max(1, Math.ceil(estRoutes / opts.shardSize));
+
+  if (N <= 1) {
+    console.log(`${TAG} ~${estRoutes} routes ≤ shard size ${opts.shardSize}: running a single vite-ssg build (no sharding needed).`);
+    const r = await runViteSsg({ heap: opts.heap, passthrough: opts.passthrough });
+    process.stdout.write(r.out);
+    process.exit(r.code);
+  }
+
+  console.log(`${TAG} ~${estRoutes} routes → ${N} shards of ≤${opts.shardSize}, ${opts.heap} MB heap each, ${opts.concurrency === 1 ? 'sequential' : `${opts.concurrency}-way parallel`}. Peak heap is bounded per shard.`);
+  if (opts.concurrency > 1) {
+    console.warn(`${TAG} warning: --concurrency > 1 is experimental — parallel shards race on the plugin's shared site-root writes and raise peak memory. Sequential is recommended.`);
+  }
+
+  const tmp = path.join(CWD, '.cms-ssg');
+  await fsp.rm(tmp, { recursive: true, force: true });
+  await fsp.mkdir(tmp, { recursive: true });
+
+  const shards = Array.from({ length: N }, (_, k) => ({ k, outDir: path.join('.cms-ssg', `dist-${k}`) }));
+  const t0 = Date.now();
+  const results = await pool(shards, opts.concurrency, async (s) => {
+    const started = Date.now();
+    process.stdout.write(`${TAG} shard ${s.k + 1}/${N} rendering…\n`);
+    const r = await runViteSsg({ shard: `${s.k}/${N}`, outDir: s.outDir, heap: opts.heap, passthrough: opts.passthrough });
+    process.stdout.write(`${TAG} shard ${s.k + 1}/${N} ${r.code === 0 ? 'ok' : 'FAILED'} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
+    return { ...r, k: s.k };
+  });
+
+  const failed = results.filter((r) => r.code !== 0);
+  if (failed.length) {
+    console.error(`${TAG} ${failed.length}/${N} shard(s) failed:`);
+    for (const f of failed) {
+      console.error(`${TAG} ---- shard ${f.k} output (tail) ----`);
+      console.error(f.out.slice(-4000));
+    }
+    process.exit(1);
+  }
+
+  await mergeShards(shards.map((s) => path.join(CWD, s.outDir)), path.join(CWD, 'dist'));
+  await fsp.rm(tmp, { recursive: true, force: true });
+  console.log(`${TAG} merged ${N} shards → dist/ in ${((Date.now() - t0) / 1000).toFixed(1)}s. Done.`);
+}
+
+main().catch((err) => { console.error(TAG, err); process.exit(1); });

package/src/main.js

@@ -135,6 +135,21 @@ export function createCmsApp() {
       };
 
       const extractCurrentRoute = () => {
+        // During SSG, vite-ssg passes the route being pre-rendered as a string
+        // on `ctx.routePath` and only pushes the router AFTER this setup fn runs
+        // — so `router.currentRoute` is still vue-router's START_LOCATION ('/')
+        // here, identically on every page. Resolve `routePath` through the router
+        // (a pure match, no navigation) to recover the real path + `params.locale`.
+        // Without this, `resolveCurrentPageId` sees '/' for every route, so the
+        // payload trim targets the wrong page — or, when '/' is ambiguous, none.
+        const routePath = ctx?.routePath;
+        if (typeof routePath === 'string' && routePath) {
+          try {
+            return router.resolve(routePath);
+          } catch {
+            return { path: routePath, params: {} };
+          }
+        }
         if (ctx?.route) {
           return ctx.route;
         }

package/src/utils/loadConfig.js

@@ -70,8 +70,24 @@ export function resolvePageIdForRoute(config, routePath, localeParam) {
         (typeof p === 'string' ? p : '/').replace(/\/+/g, '/').replace(/\/+$/, '') || '/';
     target = normalize(target);
     const pages = (config && config.pages) || {};
-    const matches = Object.entries(pages).filter(([, data]) => {
-        const pagePath = data && typeof data.path === 'string' && data.path.trim() ? data.path : '/';
+
+    // The SSG pre-renders `/404` from a site's custom `pages/404.json` (mirrors
+    // usePageConfig.selectPage's `/404` → `404` mapping). That page is
+    // conventionally path-less, so it can't be matched by `path` below — map the
+    // route to it directly. It is also deliberately NOT treated as living at `/`
+    // (see the id === '404' guard in the matcher) so it never collides with
+    // `home` there — the collision that otherwise makes `/` ambiguous on any
+    // site shipping a custom 404 page, suppressing the home-page trim.
+    const notFound = pages['404'];
+    const notFoundPathless = notFound && !(typeof notFound.path === 'string' && notFound.path.trim());
+    if (target === '/404' && notFoundPathless) return '404';
+
+    const matches = Object.entries(pages).filter(([id, data]) => {
+        const hasPath = data && typeof data.path === 'string' && data.path.trim();
+        // A page with no explicit `path` conventionally lives at `/` (home). The
+        // SSG-only `404` page is the exception: it is served at `/404`, never `/`.
+        const pagePath = hasPath ? data.path : (id === '404' ? null : '/');
+        if (pagePath === null) return false;
         return normalize(pagePath) === target;
     });
     return matches.length === 1 ? matches[0][0] : null;

package/src/utils/ssgRoutes.js

@@ -0,0 +1,40 @@
+// Route sharding for `cms-ssg-build` — the opt-in durable memory bound for the
+// SSG pre-render. vite-ssg renders every route in one Node process and leaves a
+// fixed retained cost per route, so peak heap scales with total routes;
+// `cms-ssg-build` runs the render in N separate processes, each handling a slice
+// of the routes, so peak heap is bounded by slice size instead. This module is
+// the pure partition function so the slicing rules are unit-testable without a
+// build. See SSG-MEMORY-PLAN.md.
+
+// Routes every shard renders regardless of its slice. `/404` must be present in
+// each shard's output dir so that shard's `onFinished` can copy 404/index.html
+// → 404.html; `/admin` is a cheap vestigial placeholder kept alongside it.
+export const ALWAYS_SHARDED_ROUTES = ['/404', '/admin'];
+
+/**
+ * Return shard `k` of `N` from the full SSG route list.
+ *
+ * `shardSpec` is a `"k/N"` string (e.g. `"2/5"`). Shard k = the always-present
+ * routes + every Nth remaining route offset by k, so the N shards partition the
+ * non-always routes exactly once each (no route rendered twice, none dropped).
+ *
+ * Returns the full list unchanged when `shardSpec` is absent or malformed —
+ * this is the normal `vite-ssg build` path and must stay byte-identical.
+ */
+export function applyRouteShard(allRoutes, shardSpec) {
+  if (!Array.isArray(allRoutes)) return allRoutes;
+  const match = typeof shardSpec === 'string' ? shardSpec.trim().match(/^(\d+)\/(\d+)$/) : null;
+  if (!match) return allRoutes;
+
+  const k = Number(match[1]);
+  const n = Number(match[2]);
+  if (!(n > 0) || k < 0 || k >= n) return allRoutes;
+
+  const always = new Set(ALWAYS_SHARDED_ROUTES);
+  const alwaysRoutes = allRoutes.filter((route) => always.has(route));
+  const shardRoutes = allRoutes
+    .filter((route) => !always.has(route))
+    .filter((_, i) => i % n === k);
+
+  return Array.from(new Set([...alwaysRoutes, ...shardRoutes]));
+}

package/vite-plugin.js

@@ -17,6 +17,7 @@ import { buildRobotsTxt } from './src/utils/robotsGenerator.js';
 import { buildSitemap, getSitemapUrl } from './src/utils/sitemapGenerator.js';
 import { buildWebAppManifest } from './src/utils/webAppManifest.js';
 import { sha256Hex } from './src/utils/sha256.js';
+import { applyRouteShard } from './src/utils/ssgRoutes.js';
 import {
   computeVariantCacheDir,
   resolveImageVariantConfig,
@@ -539,6 +540,14 @@ export default function cmsPlugin(options = {}) {
         publicDir: path.join(siteRoot, 'public'),
         build: {
           modulePreload: false,
+          // `cms-ssg-build` renders each route shard as a separate build into
+          // its own outDir (e.g. `.cms-ssg/dist-0`), then merges them into
+          // `dist/`. Honor the override for the CLIENT build only — vite-ssg's
+          // SSR build sets its own temp outDir and then imports the server
+          // bundle back from there, so overriding it would break that import.
+          ...(process.env.CMS_SSG_OUTDIR && !(env?.isSsrBuild || userConfig?.build?.ssr)
+            ? { outDir: process.env.CMS_SSG_OUTDIR }
+            : {}),
           rollupOptions: {
             input: tempIndexPath,
             output: {
@@ -590,7 +599,7 @@ export default function cmsPlugin(options = {}) {
           // unmatched URL with HTTP status 404, so this gives sites a
           // proper not-found response without per-site config.
           onFinished() {
-            const distDir = path.join(siteRoot, 'dist');
+            const distDir = path.join(siteRoot, process.env.CMS_SSG_OUTDIR || 'dist');
             const nestedNotFound = path.join(distDir, '404', 'index.html');
             const flatNotFound = path.join(distDir, '404.html');
             if (fs.existsSync(nestedNotFound)) {
@@ -630,7 +639,15 @@ export default function cmsPlugin(options = {}) {
               ...Array.from(staticRoutes),
               ...Array.from(localizedRoutes),
             ];
-            return Array.from(new Set(candidates));
+            const allRoutes = Array.from(new Set(candidates));
+
+            // Opt-in durable memory bound: when `cms-ssg-build` sets
+            // CMS_SSG_SHARD=k/N in the environment, render only this shard's
+            // slice of routes so peak SSG heap is bounded by slice size, not
+            // total route count. Unset (the normal `vite-ssg build` path) →
+            // the full list, byte-identical to before. (applyRouteShard keeps
+            // /404 + /admin in every shard so each can emit its own 404.html.)
+            return applyRouteShard(allRoutes, process.env.CMS_SSG_SHARD);
           },
         },
       };