@koehler8/cms 1.0.0-beta.9 → 1.0.0

package/scripts/scaffold.mjs

@@ -0,0 +1,242 @@
+// Shared core for the cms-create-{theme,extension} CLIs. Reads a template
+// directory, substitutes __SLUG__ / __DISPLAY_NAME__ placeholders, writes
+// the result to <cwd>/{themes,extensions}/<slug>/.
+//
+// Intentionally side-effect-free except for the file writes — wiring into
+// the consuming site's package.json / vite.config.js is left to the user
+// via the printed next-steps message. Modifying those files automatically
+// would risk corrupting custom formatting and is harder to reverse than a
+// copy/paste from the terminal.
+
+import { mkdir, readdir, readFile, writeFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Don't use `new URL('..', import.meta.url)` — vitest's happy-dom env can
+// patch the URL constructor in ways that make fileURLToPath reject the
+// result. Compute the path directly.
+function defaultFrameworkRoot() {
+  try {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  } catch {
+    return null;
+  }
+}
+const SLUG_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+function toDisplayName(slug) {
+  return slug
+    .split('-')
+    .map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+    .join(' ');
+}
+
+function parseArgs(argv) {
+  const args = { slug: null, out: null, force: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') args.help = true;
+    else if (a === '--force' || a === '-f') args.force = true;
+    else if (a === '--out') args.out = argv[++i];
+    else if (a.startsWith('--out=')) args.out = a.slice('--out='.length);
+    else if (!args.slug && !a.startsWith('-')) args.slug = a;
+  }
+  return args;
+}
+
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Files in the template tree that should never be copied into the
+// scaffolded output (OS junk, editor artifacts). Dotfiles in general
+// ARE copied — site templates need .nvmrc, .gitignore, .env.example.
+const TEMPLATE_SKIP = new Set(['.DS_Store', 'Thumbs.db', '.git']);
+
+async function collectTemplateFiles(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (TEMPLATE_SKIP.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...(await collectTemplateFiles(full)));
+    } else {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function applySubstitutions(content, subs) {
+  let result = content;
+  for (const [from, to] of Object.entries(subs)) {
+    result = result.split(from).join(to);
+  }
+  return result;
+}
+
+/**
+ * Run the scaffold for one of {theme, extension}.
+ *
+ * @param {object} opts
+ * @param {'theme'|'extension'} opts.kind
+ * @param {string[]} opts.argv  argv slice excluding `node` + script path
+ * @param {string} opts.cwd     working directory (defaults to process.cwd())
+ * @returns {Promise<{ok: boolean, slug?: string, targetDir?: string, message?: string}>}
+ */
+export async function runScaffold({ kind, argv, cwd = process.cwd(), frameworkRoot } = {}) {
+  if (kind !== 'theme' && kind !== 'extension' && kind !== 'site') {
+    return { ok: false, message: `unknown kind: ${kind}` };
+  }
+  const root = frameworkRoot || defaultFrameworkRoot();
+  if (!root) {
+    return {
+      ok: false,
+      message: 'error: could not resolve @koehler8/cms framework root; pass `frameworkRoot` explicitly',
+    };
+  }
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    return { ok: true, message: usage(kind) };
+  }
+  if (!args.slug) {
+    return { ok: false, message: `error: missing <slug>\n${usage(kind)}` };
+  }
+  if (!SLUG_PATTERN.test(args.slug)) {
+    return {
+      ok: false,
+      message: `error: slug "${args.slug}" must be lowercase kebab-case (e.g. "coastal", "lush-canopy")`,
+    };
+  }
+
+  const slug = args.slug;
+  const displayName = toDisplayName(slug);
+  const subs = { __SLUG__: slug, __DISPLAY_NAME__: displayName };
+  const templateDir = path.join(root, 'templates', 'scaffolds', kind);
+  // Default target dir: themes/<slug>/ for themes, extensions/<slug>/ for
+  // extensions, site-<slug>/ (sibling of cwd) for sites — matches the
+  // conventional koehler8/site-<slug> repo naming.
+  let defaultTarget;
+  if (kind === 'site') {
+    defaultTarget = path.join(cwd, `site-${slug}`);
+  } else if (kind === 'theme') {
+    defaultTarget = path.join(cwd, 'themes', slug);
+  } else {
+    defaultTarget = path.join(cwd, 'extensions', slug);
+  }
+  const targetDir = args.out ? path.resolve(cwd, args.out) : defaultTarget;
+
+  if (!(await pathExists(templateDir))) {
+    return {
+      ok: false,
+      message: `error: scaffold templates missing at ${templateDir}. Reinstall @koehler8/cms?`,
+    };
+  }
+  if ((await pathExists(targetDir)) && !args.force) {
+    return {
+      ok: false,
+      message: `error: target directory already exists: ${targetDir}\n(use --force to overwrite)`,
+    };
+  }
+
+  const files = await collectTemplateFiles(templateDir);
+  await mkdir(targetDir, { recursive: true });
+  for (const file of files) {
+    const rel = path.relative(templateDir, file);
+    const outPath = path.join(targetDir, rel);
+    await mkdir(path.dirname(outPath), { recursive: true });
+    const raw = await readFile(file, 'utf8');
+    await writeFile(outPath, applySubstitutions(raw, subs));
+  }
+
+  const targetRel = path.relative(cwd, targetDir) || targetDir;
+  return {
+    ok: true,
+    slug,
+    targetDir,
+    message: `${successHeader(kind, slug, targetRel)}\n${nextSteps(kind, slug, targetRel)}`,
+  };
+}
+
+function successHeader(kind, slug, targetRel) {
+  return `✓ Scaffolded ${kind} "${slug}" → ${targetRel}/`;
+}
+
+function nextSteps(kind, slug, targetRel) {
+  if (kind === 'theme') {
+    return [
+      '',
+      'Next steps:',
+      '  1. Add to your site\'s package.json dependencies:',
+      `       "cms-theme-${slug}": "file:./${targetRel}"`,
+      '  2. Run `npm install` to symlink it into node_modules.',
+      '  3. Add to vite.config.js\'s themes array:',
+      `       themes: ['cms-theme-${slug}'],`,
+      '  4. Activate it in site/content/{baseLocale}/site.json:',
+      `       "theme": "${slug}"`,
+      `  5. Edit ${targetRel}/theme.config.js to define your palette.`,
+      '',
+    ].join('\n');
+  }
+  if (kind === 'extension') {
+    return [
+      '',
+      'Next steps:',
+      '  1. Add to your site\'s package.json dependencies:',
+      `       "cms-ext-${slug}": "file:./${targetRel}"`,
+      '  2. Run `npm install` to symlink it into node_modules.',
+      '  3. Add to vite.config.js\'s extensions array:',
+      `       extensions: ['cms-ext-${slug}'],`,
+      `  4. Add components to ${targetRel}/components/ as needed (see ${targetRel}/README.md).`,
+      `     Or, for one-off site-only components, prefer site/components/ instead.`,
+      '',
+    ].join('\n');
+  }
+  // site
+  return [
+    '',
+    'Next steps:',
+    `  1. cd ${targetRel}`,
+    '  2. nvm use && npm install',
+    '  3. npm run dev          # Vite dev server on http://localhost:5173',
+    '  4. Read CLAUDE.md       # navigation guide for "where things go"',
+    '',
+    'Then start customizing:',
+    `  - Edit site/content/en/site.json (title, description, theme key)`,
+    `  - Edit site/content/en/pages/home.json (hero copy, components)`,
+    `  - Add a theme:           npx cms-create-theme <slug>`,
+    `  - Add a local extension: npx cms-create-extension <slug>`,
+    `  - Add a one-off Vue component: drop a file in site/components/`,
+    '',
+  ].join('\n');
+}
+
+function usage(kind) {
+  const cmds = { theme: 'cms-create-theme', extension: 'cms-create-extension', site: 'cms-create-site' };
+  const cmd = cmds[kind];
+  const defaultDir = {
+    theme: './themes/<slug>/',
+    extension: './extensions/<slug>/',
+    site: './site-<slug>/',
+  }[kind];
+  return `
+Usage: npx ${cmd} <slug> [--out <directory>] [--force]
+
+Scaffolds a new @koehler8/cms ${kind} into the current directory.
+
+Arguments:
+  <slug>          Lowercase kebab-case slug (e.g. "coastal", "lush-canopy").
+
+Options:
+  --out <dir>     Where to create the ${kind}. Defaults to ${defaultDir}.
+  --force         Overwrite an existing target directory.
+  -h, --help      Show this message.
+`;
+}

package/scripts/ssg-build/findEmptyRenders.mjs

@@ -0,0 +1,42 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+// Detect a page whose root container never mounted any real markup — just
+// Vue's SSR placeholder comment for "nothing rendered here". This is the
+// signature of a rare, silent failure in the onServerPrefetch data-fetch
+// path: @vue/server-renderer's renderComponentVNode gates a component's
+// render on `Promise.all(prefetches).catch(NOOP)` (see server-renderer.cjs.js
+// in any consuming site's node_modules) — if that promise ever rejects, the
+// renderer swallows the error entirely and renders anyway, using whatever
+// default/empty state the component held. No warning, no non-zero exit —
+// just well-formed, blank HTML on disk. A real page from this framework is
+// never legitimately empty (Home.vue always renders at least the skip-link +
+// <main>, DraftGate renders a dialog, 404 renders NotFound), so any match
+// here is unconditionally a bug. Kept in its own module (no side effects on
+// import) so it's unit-testable without tripping index.mjs's top-level
+// main() invocation — see bin/cms-ssg-build.js.
+const EMPTY_ROOT_RE = /<div id="[^"]+"[^>]*>\s*<!---->\s*<\/div>/;
+
+export async function findEmptyRenders(dir) {
+  const empties = [];
+  let entries;
+  try {
+    entries = await fsp.readdir(dir, { recursive: true });
+  } catch {
+    return empties;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith('index.html')) continue;
+    const full = path.join(dir, entry);
+    let html;
+    try {
+      html = await fsp.readFile(full, 'utf8');
+    } catch {
+      continue;
+    }
+    if (EMPTY_ROOT_RE.test(html)) {
+      empties.push(full);
+    }
+  }
+  return empties;
+}

package/scripts/ssg-build/index.mjs

@@ -0,0 +1,253 @@
+/**
+ * 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';
+import { findEmptyRenders } from './findEmptyRenders.mjs';
+
+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). 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 + 1; // + /404
+}
+
+// Emitted by usePageConfig's SSR catch (see src/composables/usePageConfig.js).
+// Its presence in a child's output means at least one route pre-rendered with
+// no page content — a failure even when vite-ssg exits 0.
+const CONFIG_FAIL_MARKER = 'PAGE CONFIG LOAD FAILED';
+
+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, stream = false }) {
+  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 });
+    // Output is always accumulated (the failure tail and the config-failure
+    // marker scan need it); `stream` additionally forwards it live so a
+    // multi-minute single build isn't a silent terminal.
+    let out = '';
+    child.stdout.on('data', (d) => { out += d; if (stream) process.stdout.write(d); });
+    child.stderr.on('data', (d) => { out += d; if (stream) process.stderr.write(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');
+    return true;
+  }
+  // A client-shell homepage is blank for crawlers and until JS boots — that
+  // is a failed build, not a warning (the empty-root detector can't catch a
+  // shell: it has no SSR comment node to match).
+  console.error(`${TAG} no shard produced a server-rendered home page; dist/index.html would be a client shell.`);
+  return false;
+}
+
+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, stream: true });
+    if (r.code === 0) {
+      if (r.out.includes(CONFIG_FAIL_MARKER)) {
+        console.error(`${TAG} build exited 0 but at least one route failed to load its page config during pre-render (see "${CONFIG_FAIL_MARKER}" above). Failing the build.`);
+        process.exit(1);
+      }
+      const empties = await findEmptyRenders(path.join(CWD, 'dist'));
+      if (empties.length) {
+        console.error(`${TAG} build succeeded but ${empties.length} page(s) rendered with an empty body — a known intermittent SSR race (see findEmptyRenders in this file). Re-run the build:`);
+        for (const f of empties) console.error(`${TAG}   - ${f}`);
+        process.exit(1);
+      }
+    }
+    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 on the shared image-variant cache (node_modules/.cache/@koehler8/cms/image-variants: concurrent evictions, duplicate renders, last-writer-wins manifest), 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 });
+    let empties = [];
+    const configFailed = r.code === 0 && r.out.includes(CONFIG_FAIL_MARKER);
+    if (r.code === 0 && !configFailed) {
+      empties = await findEmptyRenders(path.join(CWD, s.outDir));
+    }
+    const ok = r.code === 0 && !configFailed && empties.length === 0;
+    process.stdout.write(`${TAG} shard ${s.k + 1}/${N} ${ok ? 'ok' : 'FAILED'} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
+    if (configFailed) {
+      return {
+        ...r,
+        code: 1,
+        out: `${r.out}\n${TAG} at least one route failed to load its page config during pre-render ("${CONFIG_FAIL_MARKER}").\n`,
+        k: s.k,
+      };
+    }
+    if (empties.length) {
+      return {
+        ...r,
+        code: 1,
+        out: `${r.out}\n${TAG} ${empties.length} page(s) rendered with an empty body — a known intermittent SSR race (see findEmptyRenders in this file):\n${empties.map((f) => `  - ${f}`).join('\n')}\n`,
+        k: s.k,
+      };
+    }
+    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);
+  }
+
+  const homeOk = await mergeShards(shards.map((s) => path.join(CWD, s.outDir)), path.join(CWD, 'dist'));
+  if (!homeOk) {
+    process.exit(1);
+  }
+  // Belt-and-suspenders: re-check the merged output as a whole.
+  const mergedEmpties = await findEmptyRenders(path.join(CWD, 'dist'));
+  if (mergedEmpties.length) {
+    console.error(`${TAG} merged dist/ contains ${mergedEmpties.length} empty-bodied page(s):`);
+    for (const f of mergedEmpties) console.error(`${TAG}   - ${f}`);
+    process.exit(1);
+  }
+  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); });