@koehler8/cms 1.0.0-beta.26 → 1.0.0-beta.27

package/bin/cms-migrate-image-variants.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Thin wrapper that runs the migration helper from the consuming site's cwd.
+// The script does its own argument handling and prints its own status.
+
+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', 'migrate-image-variants.mjs'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.26",
+  "version": "1.0.0-beta.27",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -54,7 +54,7 @@
   },
   "bin": {
     "cms-generate-public-assets": "./bin/cms-generate-public-assets.js",
-    "cms-generate-image-variants": "./bin/cms-generate-image-variants.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",
     "cms-create-theme": "./bin/cms-create-theme.js",

package/scripts/image-variants/cache.js

@@ -0,0 +1,40 @@
+/**
+ * Compute the per-site variant cache directory.
+ *
+ * Layout:
+ *   {siteRoot}/node_modules/.cache/@koehler8/cms/image-variants/{siteKey}/
+ *
+ * where siteKey is the first 8 hex chars of sha1(siteDir). The keying
+ * prevents cache collisions when @koehler8/cms is hoisted in a workspace
+ * (one framework install serves multiple sites — without per-site keys,
+ * concurrent builds would clobber each other).
+ *
+ * The cache lives under the SITE's node_modules (matching Vite's own
+ * node_modules/.vite/ convention) so each site's cache is local to its
+ * own project tree.
+ */
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+export function siteKeyFor(siteDir) {
+  return crypto
+    .createHash('sha1')
+    .update(path.resolve(siteDir))
+    .digest('hex')
+    .slice(0, 8);
+}
+
+export function computeVariantCacheDir(siteRoot, siteDir) {
+  const root = path.resolve(siteRoot);
+  const key = siteKeyFor(siteDir || siteRoot);
+  return path.join(
+    root,
+    'node_modules',
+    '.cache',
+    '@koehler8',
+    'cms',
+    'image-variants',
+    key,
+  );
+}

package/scripts/image-variants/classifier.js

@@ -0,0 +1,53 @@
+/**
+ * Classify a file under site/assets/img/** as one of:
+ *   'original' — a hand-authored source image we should generate variants from
+ *   'variant'  — a previously-generated variant matching {name}-{width}.{format}
+ *                where width is one of the configured widths
+ *   'ignore'   — anything else (non-image file, README, etc.)
+ *
+ * The classifier is the bridge between the flat-dir convention and the old
+ * _source/ convention: by recognizing the variant naming pattern, we can keep
+ * originals and variants in the same directory without confusion. Files that
+ * happen to look variant-shaped but use widths outside the configured set
+ * (e.g. `team-2024.jpg`) are treated as originals — the documented escape
+ * hatch is to rename source files that genuinely conflict.
+ */
+
+import path from 'node:path';
+
+export const SOURCE_EXTENSIONS = new Set([
+  '.jpg', '.jpeg', '.png', '.webp', '.avif', '.tiff', '.tif',
+]);
+
+export const FORMAT_OUTPUT_EXT = {
+  avif: 'avif',
+  webp: 'webp',
+  jpg: 'jpg',
+  jpeg: 'jpg',
+  png: 'png',
+};
+
+const VARIANT_FORMAT_EXTS = new Set(['avif', 'webp', 'jpg', 'jpeg']);
+
+/**
+ * @param {string} relPath - File path relative to site/assets/img/
+ * @param {Set<number>} configWidths - Set of widths considered "variant widths"
+ * @returns {'original' | 'variant' | 'ignore'}
+ */
+export function classifyImageFile(relPath, configWidths) {
+  const parsed = path.parse(relPath);
+  const ext = parsed.ext.toLowerCase().slice(1);
+
+  if (ext === 'svg') return 'original';
+  if (!ext) return 'ignore';
+  if (!SOURCE_EXTENSIONS.has(`.${ext}`)) return 'ignore';
+
+  const m = parsed.name.match(/^(.+)-(\d+)$/);
+  if (!m) return 'original';
+  if (!VARIANT_FORMAT_EXTS.has(ext)) return 'original';
+
+  const width = Number.parseInt(m[2], 10);
+  if (!configWidths.has(width)) return 'original';
+
+  return 'variant';
+}

package/scripts/image-variants/config.js

@@ -0,0 +1,54 @@
+/**
+ * Image-variant pipeline configuration.
+ *
+ * Resolves the `imageVariants` block from a site's `site.json` into a
+ * normalized config object: { widths: number[], formats: string[],
+ * quality: { avif, webp, jpg } }. Falls back to sensible marketing-site
+ * defaults when fields are missing or invalid.
+ */
+
+import { FORMAT_OUTPUT_EXT } from './classifier.js';
+
+export const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 2560];
+export const DEFAULT_FORMATS = ['avif', 'webp', 'jpg'];
+export const DEFAULT_QUALITY = { avif: 60, webp: 75, jpg: 80 };
+
+function normalizeWidths(input) {
+  if (!Array.isArray(input)) return [...DEFAULT_WIDTHS];
+  const filtered = input
+    .map((v) => Number.parseInt(v, 10))
+    .filter((v) => Number.isFinite(v) && v > 0);
+  if (!filtered.length) return [...DEFAULT_WIDTHS];
+  return [...new Set(filtered)].sort((a, b) => a - b);
+}
+
+function normalizeFormats(input) {
+  if (!Array.isArray(input)) return [...DEFAULT_FORMATS];
+  const filtered = input
+    .map((v) => (typeof v === 'string' ? v.trim().toLowerCase() : ''))
+    .filter((v) => v && FORMAT_OUTPUT_EXT[v]);
+  if (!filtered.length) return [...DEFAULT_FORMATS];
+  return [...new Set(filtered)];
+}
+
+function normalizeQuality(input) {
+  const merged = { ...DEFAULT_QUALITY };
+  if (input && typeof input === 'object') {
+    for (const [k, v] of Object.entries(input)) {
+      const n = Number.parseInt(v, 10);
+      if (Number.isFinite(n) && n >= 1 && n <= 100) merged[k] = n;
+    }
+  }
+  return merged;
+}
+
+export function resolveImageVariantConfig(siteConfig) {
+  const block = (siteConfig?.imageVariants && typeof siteConfig.imageVariants === 'object')
+    ? siteConfig.imageVariants
+    : {};
+  return {
+    widths: normalizeWidths(block.widths),
+    formats: normalizeFormats(block.formats),
+    quality: normalizeQuality(block.quality),
+  };
+}

package/scripts/image-variants/index.js

@@ -0,0 +1,20 @@
+/**
+ * Public API for the image-variant pipeline.
+ *
+ * Used by:
+ *   - The Vite plugin (vite-plugin.js) — buildStart hook + dev watcher.
+ *   - The migration helper (scripts/migrate-image-variants.mjs) — reads
+ *     `_source/` presence to know whether to migrate.
+ *
+ * The pipeline runs at build/dev time, generates variants to
+ * node_modules/.cache/@koehler8/cms/image-variants/{siteKey}/, and never
+ * touches the site's source tree.
+ */
+
+export { resolveImageVariantConfig, DEFAULT_WIDTHS, DEFAULT_FORMATS, DEFAULT_QUALITY } from './config.js';
+export { classifyImageFile, SOURCE_EXTENSIONS, FORMAT_OUTPUT_EXT } from './classifier.js';
+export { planVariantJobsFromFlatDir, walkRecursive } from './planner.js';
+export { renderOutput } from './renderer.js';
+export { readManifest, writeManifest, configsEqual, MANIFEST_VERSION } from './manifest.js';
+export { computeVariantCacheDir, siteKeyFor } from './cache.js';
+export { reconcileVariantCache } from './reconcile.js';

package/scripts/image-variants/manifest.js

@@ -0,0 +1,71 @@
+/**
+ * Cache manifest: persisted record of what's in the variant cache directory.
+ *
+ * Format:
+ *   {
+ *     version: 1,
+ *     config:  { widths, formats, quality },
+ *     sources: {
+ *       "img/logo.png": { mtimeMs, variants: ["assets/img/logo-320.webp", ...] },
+ *       ...
+ *     }
+ *   }
+ *
+ * Used by reconcileVariantCache to:
+ *   - Skip regeneration when source mtime is unchanged AND config matches.
+ *   - Detect orphaned entries (source removed) and delete their cached files.
+ *   - Force a full regen when config changes (e.g. user added a new width).
+ */
+
+import fs from 'node:fs';
+
+export const MANIFEST_VERSION = 1;
+
+export function readManifest(manifestPath) {
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    if (parsed && parsed.version === MANIFEST_VERSION) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeManifest(manifestPath, manifest) {
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Deep equality check for image-variant config blocks. Returns true when
+ * widths, formats, and quality (per-format) all match. Order-insensitive
+ * for arrays.
+ */
+export function configsEqual(a, b) {
+  if (!a || !b) return false;
+  if (!arraysEqualUnordered(a.widths, b.widths)) return false;
+  if (!arraysEqualUnordered(a.formats, b.formats)) return false;
+  return objectsEqual(a.quality, b.quality);
+}
+
+function arraysEqualUnordered(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return false;
+  if (a.length !== b.length) return false;
+  const sa = [...a].sort();
+  const sb = [...b].sort();
+  for (let i = 0; i < sa.length; i += 1) {
+    if (sa[i] !== sb[i]) return false;
+  }
+  return true;
+}
+
+function objectsEqual(a, b) {
+  if (!a || !b) return a === b;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}

package/scripts/image-variants/planner.js

@@ -0,0 +1,95 @@
+/**
+ * Walk site/assets/img/** (recursive), classify each file, and build a list
+ * of variant-generation jobs.
+ *
+ * Each job is { sourceKey, sourcePath, outputs: [{ width, format, cacheRelPath }] }
+ * where:
+ *   sourceKey    - posix path relative to site/assets/ (e.g. "img/logo.png")
+ *   sourcePath   - absolute disk path of the original
+ *   cacheRelPath - posix path relative to the cache dir root, including the
+ *                  `assets/img/` parent — so that the cache directory mirrors
+ *                  the site's `assets/` layout. The `assets/` parent is
+ *                  load-bearing: createAssetResolver's normalizeAssetKey
+ *                  strips up to and including `assets/`, so cache entries
+ *                  surface in the URL map under the same `img/...` keys as
+ *                  flat-dir variants would.
+ *
+ * SVGs are originals but produce no jobs (no variant generation).
+ * Files classified as 'variant' (leftover from the old pipeline) or 'ignore'
+ * are skipped.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { classifyImageFile, FORMAT_OUTPUT_EXT } from './classifier.js';
+
+export function* walkRecursive(dir) {
+  if (!fs.existsSync(dir)) return;
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const entry of fs.readdirSync(cur, { withFileTypes: true })) {
+      const full = path.join(cur, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (entry.isFile()) yield full;
+    }
+  }
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.siteImgDir - absolute path to site/assets/img/
+ * @param {{ widths: number[], formats: string[] }} args.config
+ * @returns {Array<{sourceKey: string, sourcePath: string, outputs: Array<{width: number, format: string, cacheRelPath: string}>}>}
+ */
+export function planVariantJobsFromFlatDir({ siteImgDir, config }) {
+  if (!fs.existsSync(siteImgDir)) return [];
+
+  const configWidths = new Set(config.widths);
+  const jobs = [];
+
+  for (const sourcePath of walkRecursive(siteImgDir)) {
+    const relFromImg = path.relative(siteImgDir, sourcePath);
+
+    if (relFromImg.split(path.sep)[0] === '_source') continue;
+
+    const cls = classifyImageFile(relFromImg, configWidths);
+    if (cls !== 'original') continue;
+
+    const ext = path.extname(relFromImg).toLowerCase();
+    if (ext === '.svg') continue;
+
+    const parsed = path.parse(relFromImg);
+    const subdir = parsed.dir;
+    const baseName = parsed.name;
+
+    const outputs = [];
+    for (const width of config.widths) {
+      for (const format of config.formats) {
+        const outExt = FORMAT_OUTPUT_EXT[format];
+        if (!outExt) continue;
+        const variantName = `${baseName}-${width}.${outExt}`;
+        const cacheRelPath = path.posix.join(
+          'assets',
+          'img',
+          subdir.split(path.sep).join('/'),
+          variantName,
+        );
+        outputs.push({ width, format, cacheRelPath });
+      }
+    }
+
+    const sourceKey = path.posix.join(
+      'img',
+      relFromImg.split(path.sep).join('/'),
+    );
+
+    jobs.push({ sourceKey, sourcePath, outputs });
+  }
+
+  return jobs;
+}

package/scripts/image-variants/reconcile.js

@@ -0,0 +1,125 @@
+/**
+ * Reconcile the variant cache directory against the planned jobs:
+ *   - Generate variants whose source mtime is newer than cached, or whose
+ *     cached file no longer exists, or when the config block has changed.
+ *   - Skip jobs whose cached variants are all up-to-date.
+ *   - Delete cached variants for sources that no longer exist (orphans).
+ *   - Write the new manifest at the end.
+ *
+ * Sharp is imported lazily — only when there is actual rendering work to do.
+ * This keeps dev-mode cold-start fast when the cache is fully populated.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readManifest, writeManifest, configsEqual, MANIFEST_VERSION } from './manifest.js';
+import { renderOutput } from './renderer.js';
+
+/**
+ * @param {object} args
+ * @param {Array} args.jobs - planVariantJobsFromFlatDir output
+ * @param {string} args.cacheDir - absolute path to the variant cache root
+ * @param {string} args.manifestPath - absolute path to .manifest.json
+ * @param {{widths, formats, quality}} args.currentConfig
+ * @param {(msg: string) => void} [args.log]
+ * @returns {Promise<{generated: number, skipped: number, evicted: number}>}
+ */
+export async function reconcileVariantCache({
+  jobs,
+  cacheDir,
+  manifestPath,
+  currentConfig,
+  log = () => {},
+}) {
+  await fs.promises.mkdir(cacheDir, { recursive: true });
+
+  const saved = readManifest(manifestPath);
+  const configChanged = !saved || !configsEqual(saved.config, currentConfig);
+
+  const currentSourceKeys = new Set(jobs.map((j) => j.sourceKey));
+
+  let evicted = 0;
+  if (saved) {
+    for (const oldKey of Object.keys(saved.sources || {})) {
+      if (currentSourceKeys.has(oldKey)) continue;
+      const oldEntry = saved.sources[oldKey];
+      for (const variantRel of (oldEntry.variants || [])) {
+        const fullPath = path.join(cacheDir, variantRel);
+        if (fs.existsSync(fullPath)) {
+          await fs.promises.rm(fullPath, { force: true });
+          evicted += 1;
+        }
+      }
+    }
+  }
+
+  const plannedRenders = [];
+  for (const job of jobs) {
+    const previous = saved?.sources?.[job.sourceKey];
+    let sourceMtime;
+    try {
+      sourceMtime = fs.statSync(job.sourcePath).mtimeMs;
+    } catch {
+      continue;
+    }
+
+    const allCached = !configChanged
+      && previous
+      && previous.mtimeMs >= sourceMtime
+      && job.outputs.every((o) => fs.existsSync(path.join(cacheDir, o.cacheRelPath)));
+
+    if (allCached) {
+      plannedRenders.push({ job, sourceMtime, render: false });
+    } else {
+      plannedRenders.push({ job, sourceMtime, render: true });
+    }
+  }
+
+  const renderJobs = plannedRenders.filter((p) => p.render);
+
+  let generated = 0;
+  let skipped = 0;
+  let sharp = null;
+
+  if (renderJobs.length > 0) {
+    const mod = await import('sharp');
+    sharp = mod.default;
+  }
+
+  for (const { job, sourceMtime, render } of plannedRenders) {
+    if (!render) {
+      skipped += job.outputs.length;
+      continue;
+    }
+    for (const output of job.outputs) {
+      const outPath = path.join(cacheDir, output.cacheRelPath);
+      try {
+        await renderOutput(sharp, job.sourcePath, { ...output, outPath }, currentConfig);
+        generated += 1;
+      } catch (err) {
+        log(`failed ${output.cacheRelPath}: ${err.message}`);
+      }
+    }
+    void sourceMtime;
+  }
+
+  const newManifest = {
+    version: MANIFEST_VERSION,
+    config: currentConfig,
+    sources: {},
+  };
+  for (const { job, sourceMtime } of plannedRenders) {
+    newManifest.sources[job.sourceKey] = {
+      mtimeMs: sourceMtime,
+      variants: job.outputs.map((o) => o.cacheRelPath),
+    };
+  }
+  writeManifest(manifestPath, newManifest);
+
+  if (generated || evicted) {
+    log(`sources: ${jobs.length}, generated: ${generated}, skipped: ${skipped}, evicted: ${evicted}`);
+  }
+
+  return { generated, skipped, evicted };
+}

package/scripts/image-variants/renderer.js

@@ -0,0 +1,41 @@
+/**
+ * Sharp-powered variant renderer. Reads a source image, resizes to the
+ * requested width (clamped to source size — no enlargement), and writes
+ * the encoded output to outPath.
+ *
+ * Pure function: takes paths and config, performs IO, returns nothing.
+ * Sharp is imported lazily by the caller (see reconcile.js) so dev-mode
+ * cold start doesn't pay sharp's native-binding load cost when there's
+ * nothing to render.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export async function renderOutput(sharp, sourcePath, output, config) {
+  const { width, format, outPath } = output;
+  await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+
+  let pipeline = sharp(sourcePath, { failOn: 'truncated' }).rotate();
+  pipeline = pipeline.resize({ width, withoutEnlargement: true });
+
+  switch (format) {
+    case 'avif':
+      pipeline = pipeline.avif({ quality: config.quality.avif });
+      break;
+    case 'webp':
+      pipeline = pipeline.webp({ quality: config.quality.webp });
+      break;
+    case 'jpg':
+    case 'jpeg':
+      pipeline = pipeline.jpeg({ quality: config.quality.jpg, mozjpeg: true });
+      break;
+    case 'png':
+      pipeline = pipeline.png();
+      break;
+    default:
+      throw new Error(`unsupported format: ${format}`);
+  }
+
+  await pipeline.toFile(outPath);
+}

package/scripts/migrate-image-variants.mjs

@@ -0,0 +1,316 @@
+/**
+ * Per-site migration helper for the cms@1.0.0-beta.27 in-plugin image
+ * variant pipeline.
+ *
+ * Run from a site directory:
+ *   npx @koehler8/cms migrate-image-variants
+ *
+ * What it does (idempotent — running it on an already-migrated site is a
+ * series of no-ops):
+ *   1. Validate this is a cms-using site (check package.json deps).
+ *   2. Promote site/assets/img/_source/* originals to flat dir, delete
+ *      duplicate copies left over from beta.26's auto-copy step, then
+ *      remove the now-empty _source/ directory.
+ *   3. git rm --cached any committed variants matching {name}-{N}.{ext}
+ *      and append the patterns to .gitignore for future-proofing.
+ *   4. Drop the `generate:image-variants` entry from package.json scripts.
+ *   5. Drop the `npm run generate:image-variants` line from amplify.yml.
+ *   6. Bump @koehler8/cms range to ^1.0.0-beta.27.
+ *   7. Run npm install --prefer-offline --no-audit --no-fund.
+ *   8. Print verification instructions.
+ *
+ * Does NOT auto-commit or auto-push — humans review the diff.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+
+const TARGET_CMS_VERSION = '^1.0.0-beta.27';
+const VARIANT_NAME_RE = /-\d+\.(?:avif|webp|jpg|jpeg)$/i;
+
+function log(msg) {
+  console.log(msg);
+}
+function step(n, msg) {
+  console.log(`${BOLD}[${n}]${RESET} ${msg}`);
+}
+function ok(msg) {
+  console.log(`    ${GREEN}✓${RESET} ${msg}`);
+}
+function info(msg) {
+  console.log(`    ${DIM}·${RESET} ${DIM}${msg}${RESET}`);
+}
+function warn(msg) {
+  console.log(`    ${YELLOW}!${RESET} ${msg}`);
+}
+function fail(msg) {
+  console.log(`    ${RED}✗${RESET} ${RED}${msg}${RESET}`);
+}
+
+function readJsonOrNull(p) {
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(p, obj) {
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+
+function* walkRecursive(dir) {
+  if (!fs.existsSync(dir)) return;
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const entry of fs.readdirSync(cur, { withFileTypes: true })) {
+      const full = path.join(cur, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (entry.isFile()) yield full;
+    }
+  }
+}
+
+function gitTryRm(siteDir, files) {
+  if (!files.length) return 0;
+  try {
+    const args = files.map((f) => `'${path.relative(siteDir, f).replace(/'/g, "'\\''")}'`).join(' ');
+    execSync(`git rm --cached --quiet ${args}`, { cwd: siteDir, stdio: 'pipe' });
+    return files.length;
+  } catch {
+    return 0;
+  }
+}
+
+function isCmsSite(siteDir) {
+  const pkg = readJsonOrNull(path.join(siteDir, 'package.json'));
+  if (!pkg) return false;
+  return Boolean(pkg.dependencies?.['@koehler8/cms'] || pkg.devDependencies?.['@koehler8/cms']);
+}
+
+function migrateSourceDir(siteDir) {
+  const imgDir = path.join(siteDir, 'assets', 'img');
+  const altImgDir = path.join(siteDir, 'site', 'assets', 'img');
+  const target = fs.existsSync(altImgDir) ? altImgDir : imgDir;
+  const sourceDir = path.join(target, '_source');
+  if (!fs.existsSync(sourceDir)) {
+    info('no site/assets/img/_source/ to migrate');
+    return;
+  }
+  let promoted = 0;
+  let deletedDup = 0;
+  for (const sourcePath of walkRecursive(sourceDir)) {
+    const rel = path.relative(sourceDir, sourcePath);
+    const flatPath = path.join(target, rel);
+    if (fs.existsSync(flatPath)) {
+      fs.rmSync(sourcePath, { force: true });
+      deletedDup += 1;
+    } else {
+      fs.mkdirSync(path.dirname(flatPath), { recursive: true });
+      fs.renameSync(sourcePath, flatPath);
+      promoted += 1;
+    }
+  }
+  function removeEmptyDirs(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) removeEmptyDirs(path.join(dir, entry.name));
+    }
+    if (!fs.readdirSync(dir).length) {
+      fs.rmdirSync(dir);
+    }
+  }
+  removeEmptyDirs(sourceDir);
+  if (promoted) ok(`promoted ${promoted} originals from _source/ to flat dir`);
+  if (deletedDup) ok(`removed ${deletedDup} duplicate copies left in _source/`);
+  if (!fs.existsSync(sourceDir)) ok('removed empty _source/ directory');
+}
+
+function untrackVariants(siteDir) {
+  const candidates = [
+    path.join(siteDir, 'assets', 'img'),
+    path.join(siteDir, 'site', 'assets', 'img'),
+  ].filter((d) => fs.existsSync(d));
+  const variantPaths = [];
+  for (const dir of candidates) {
+    for (const f of walkRecursive(dir)) {
+      if (f.includes(`${path.sep}_source${path.sep}`)) continue;
+      if (VARIANT_NAME_RE.test(f)) variantPaths.push(f);
+    }
+  }
+  if (!variantPaths.length) {
+    info('no committed variants to untrack');
+    return;
+  }
+  const untracked = gitTryRm(siteDir, variantPaths);
+  if (untracked) {
+    ok(`git rm --cached on ${untracked} variant file(s) (kept on disk)`);
+    for (const v of variantPaths) {
+      try { fs.rmSync(v, { force: true }); } catch { /* noop */ }
+    }
+    ok(`removed ${variantPaths.length} variant file(s) from working tree`);
+  } else {
+    warn(`found ${variantPaths.length} variant-shaped files but git rm failed (not in git or git not present); deleting from disk anyway`);
+    for (const v of variantPaths) {
+      try { fs.rmSync(v, { force: true }); } catch { /* noop */ }
+    }
+  }
+}
+
+function appendGitignore(siteDir) {
+  const gi = path.join(siteDir, '.gitignore');
+  const block = [
+    '',
+    '# Image variants are generated at build time into node_modules/.cache/',
+    '# (cms@1.0.0-beta.27+ pipeline). Defensive ignore so accidental local',
+    '# variants in the source tree don’t get committed.',
+    'site/assets/img/*-[0-9]*.avif',
+    'site/assets/img/*-[0-9]*.webp',
+    'site/assets/img/*-[0-9]*.jpg',
+    'site/assets/img/*-[0-9]*.jpeg',
+    'site/assets/img/**/*-[0-9]*.avif',
+    'site/assets/img/**/*-[0-9]*.webp',
+    'site/assets/img/**/*-[0-9]*.jpg',
+    'site/assets/img/**/*-[0-9]*.jpeg',
+    'assets/img/*-[0-9]*.avif',
+    'assets/img/*-[0-9]*.webp',
+    'assets/img/*-[0-9]*.jpg',
+    'assets/img/*-[0-9]*.jpeg',
+    '',
+  ].join('\n');
+  let cur = '';
+  if (fs.existsSync(gi)) cur = fs.readFileSync(gi, 'utf-8');
+  if (cur.includes('# Image variants are generated at build time')) {
+    info('.gitignore already has image-variant patterns');
+    return;
+  }
+  fs.writeFileSync(gi, cur + (cur.endsWith('\n') ? '' : '\n') + block);
+  ok('appended image-variant patterns to .gitignore');
+}
+
+function dropPackageJsonScript(siteDir) {
+  const pkgPath = path.join(siteDir, 'package.json');
+  const pkg = readJsonOrNull(pkgPath);
+  if (!pkg) {
+    fail('package.json missing');
+    return;
+  }
+  if (pkg.scripts?.['generate:image-variants']) {
+    delete pkg.scripts['generate:image-variants'];
+    writeJson(pkgPath, pkg);
+    ok('removed generate:image-variants script from package.json');
+  } else {
+    info('package.json scripts already clean');
+  }
+}
+
+function dropAmplifyStep(siteDir) {
+  const ymlPath = path.join(siteDir, 'amplify.yml');
+  if (!fs.existsSync(ymlPath)) {
+    info('no amplify.yml present');
+    return;
+  }
+  const cur = fs.readFileSync(ymlPath, 'utf-8');
+  const next = cur
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*-\s*npm\s+run\s+generate:image-variants\s*$/.test(line))
+    .join('\n');
+  if (next === cur) {
+    info('amplify.yml already clean');
+    return;
+  }
+  fs.writeFileSync(ymlPath, next);
+  ok('removed generate:image-variants step from amplify.yml');
+}
+
+function bumpCmsVersion(siteDir) {
+  const pkgPath = path.join(siteDir, 'package.json');
+  const pkg = readJsonOrNull(pkgPath);
+  if (!pkg) return;
+  let bumped = false;
+  if (pkg.dependencies?.['@koehler8/cms'] && pkg.dependencies['@koehler8/cms'] !== TARGET_CMS_VERSION) {
+    pkg.dependencies['@koehler8/cms'] = TARGET_CMS_VERSION;
+    bumped = true;
+  }
+  if (pkg.devDependencies?.['@koehler8/cms'] && pkg.devDependencies['@koehler8/cms'] !== TARGET_CMS_VERSION) {
+    pkg.devDependencies['@koehler8/cms'] = TARGET_CMS_VERSION;
+    bumped = true;
+  }
+  if (bumped) {
+    writeJson(pkgPath, pkg);
+    ok(`bumped @koehler8/cms to ${TARGET_CMS_VERSION}`);
+  } else {
+    info(`@koehler8/cms already at ${TARGET_CMS_VERSION}`);
+  }
+}
+
+function runNpmInstall(siteDir) {
+  try {
+    execSync('npm install --prefer-offline --no-audit --no-fund', {
+      cwd: siteDir,
+      stdio: 'inherit',
+    });
+    ok('npm install completed');
+  } catch (err) {
+    fail(`npm install failed: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function main() {
+  const siteDir = path.resolve(process.cwd());
+  log('');
+  log(`${BOLD}cms image-variant migration${RESET}`);
+  log(`${DIM}site:${RESET} ${siteDir}`);
+  log('');
+
+  if (!isCmsSite(siteDir)) {
+    fail('Not a @koehler8/cms-consuming site (no @koehler8/cms in package.json deps).');
+    process.exit(1);
+  }
+
+  step(1, 'Promote originals from _source/ to flat dir');
+  migrateSourceDir(siteDir);
+
+  step(2, 'Untrack and remove committed variants');
+  untrackVariants(siteDir);
+
+  step(3, 'Append image-variant patterns to .gitignore');
+  appendGitignore(siteDir);
+
+  step(4, 'Remove generate:image-variants script from package.json');
+  dropPackageJsonScript(siteDir);
+
+  step(5, 'Remove generate:image-variants step from amplify.yml');
+  dropAmplifyStep(siteDir);
+
+  step(6, `Bump @koehler8/cms to ${TARGET_CMS_VERSION}`);
+  bumpCmsVersion(siteDir);
+
+  step(7, 'npm install');
+  runNpmInstall(siteDir);
+
+  log('');
+  log(`${BOLD}${GREEN}Done.${RESET}`);
+  log('');
+  log('Next steps:');
+  log(`  ${DIM}·${RESET} npm run build:ssg     # verify variants render in dist/`);
+  log(`  ${DIM}·${RESET} git diff               # review the changes`);
+  log(`  ${DIM}·${RESET} git add -A && git commit && git push`);
+  log('');
+}
+
+main();

package/vite-plugin.js

@@ -17,6 +17,12 @@ 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 {
+  computeVariantCacheDir,
+  resolveImageVariantConfig,
+  planVariantJobsFromFlatDir,
+  reconcileVariantCache,
+} from './scripts/image-variants/index.js';
 
 // ---- Helpers ----
 
@@ -349,6 +355,8 @@ export default function cmsPlugin(options = {}) {
   let metadata;
   let tempIndexPath;
   let tempEntryPath;
+  let variantCacheDir;
+  let variantManifestPath;
 
   const writeTempFiles = () => {
     // Write entry file (with optional external theme registrations)
@@ -453,6 +461,8 @@ export default function cmsPlugin(options = {}) {
       siteRoot = path.dirname(siteDir);
       tempIndexPath = path.join(siteRoot, 'index.html');
       tempEntryPath = path.join(siteRoot, ENTRY_FILENAME);
+      variantCacheDir = computeVariantCacheDir(siteRoot, siteDir);
+      variantManifestPath = path.join(variantCacheDir, '.manifest.json');
 
       // Load site config at config-resolution time (needed for SSG routes + HTML injection)
       const contentDir = path.join(siteDir, 'content');
@@ -498,6 +508,7 @@ export default function cmsPlugin(options = {}) {
           alias: {
             '@cms-site': siteDir,
             '@cms-framework': frameworkRoot,
+            '@cms-variant-cache': variantCacheDir,
             '@': path.join(frameworkRoot, 'src'),
             '@extensions': extensionsDir,
           },
@@ -722,6 +733,18 @@ export default modules;
       }
 
       if (virtualId === VIRTUAL_ASSETS) {
+        // Three globs:
+        //   shared    — framework-bundled assets
+        //   site      — site/assets/** flat-dir originals (everything the
+        //               author put on disk, including any leftover variants
+        //               from the old pipeline that haven't been cleaned up)
+        //   variants  — generated variants from node_modules/.cache/
+        //               @koehler8/cms/image-variants/{siteKey}/assets/**.
+        //               The cache mirrors the site's `assets/` layout so
+        //               normalizeAssetKey strips the same `assets/` prefix
+        //               and surfaces variants under canonical `img/...` keys.
+        // Spread order: variants first so site flat-dir wins on collision —
+        // a hand-placed file in site/assets/img/ overrides the cached variant.
         return `
 import { createAssetResolver } from '@koehler8/cms/utils/assetResolver';
 const shared = import.meta.glob('@cms-framework/src/assets/**/*', {
@@ -729,15 +752,17 @@ const shared = import.meta.glob('@cms-framework/src/assets/**/*', {
   query: '?url',
   import: 'default',
 });
-const site = import.meta.glob([
-  '@cms-site/assets/**/*',
-  '!@cms-site/assets/_source/**',
-], {
+const site = import.meta.glob('@cms-site/assets/**/*', {
   eager: true,
   query: '?url',
   import: 'default',
 });
-const resolver = createAssetResolver(shared, site);
+const variants = import.meta.glob('@cms-variant-cache/assets/**/*', {
+  eager: true,
+  query: '?url',
+  import: 'default',
+});
+const resolver = createAssetResolver(shared, { ...variants, ...site });
 export const resolveAssetUrl = resolver.resolveAssetUrl;
 export const resolveAsset = resolver.resolveAsset;
 export const resolveMedia = resolver.resolveMedia;
@@ -765,6 +790,50 @@ export const assetUrlMap = resolver.assetUrlMap;
       return { code: transformed, map: null };
     },
 
+    async buildStart() {
+      // Generate image variants into the cache dir BEFORE the VIRTUAL_ASSETS
+      // load() block runs its import.meta.glob — that glob picks up the cache
+      // files and surfaces them as Vite-pipelined assets (hashed, emitted to
+      // dist/assets/) at build, or served straight from disk during dev.
+      //
+      // Errors here are warned, not thrown — a broken variant pipeline should
+      // not kill the entire build. Sites without source images (no img dir,
+      // empty img dir) are no-ops.
+      const siteImgDir = path.join(siteDir, 'assets', 'img');
+
+      // Strict deprecation: warn loudly if the legacy _source/ dir exists.
+      // Pipeline only reads the flat dir — sites that haven't migrated will
+      // see broken image URLs until they run `npx @koehler8/cms migrate-image-variants`.
+      const legacySourceDir = path.join(siteImgDir, '_source');
+      if (fs.existsSync(legacySourceDir)) {
+        this.warn(
+          `[@koehler8/cms] Found legacy site/assets/img/_source/ directory.`
+          + ` As of beta.27 image originals live directly in site/assets/img/`
+          + ` and variants generate at build time into node_modules/.cache/.`
+          + ` Run \`npx @koehler8/cms migrate-image-variants\` from the site`
+          + ` directory to migrate. The pipeline is NOT reading from _source/`
+          + ` — image URLs will 404 until you migrate.`,
+        );
+      }
+
+      try {
+        const variantConfig = resolveImageVariantConfig(siteConfig);
+        const jobs = planVariantJobsFromFlatDir({
+          siteImgDir,
+          config: variantConfig,
+        });
+        await reconcileVariantCache({
+          jobs,
+          cacheDir: variantCacheDir,
+          manifestPath: variantManifestPath,
+          currentConfig: variantConfig,
+          log: (msg) => this.warn(`[@koehler8/cms image-variants] ${msg}`),
+        });
+      } catch (err) {
+        this.warn(`[@koehler8/cms image-variants] generation failed: ${err.message}`);
+      }
+    },
+
     configResolved(resolvedConfig) {
       // Write temp files as soon as config is resolved so vite-ssg's
       // detectEntry (which runs before Vite's build lifecycle) finds them.
@@ -831,8 +900,55 @@ export const assetUrlMap = resolver.assetUrlMap;
       // Watch site content for HMR
       server.watcher.add(siteDir);
 
+      // Image-variant regen on source-image change. Debounced so bulk
+      // drag-and-drop adds don't trigger N pipeline runs. Writes to the
+      // cache dir don't re-trigger because we early-return on those events.
+      const siteImgDir = path.join(siteDir, 'assets', 'img');
+      let pendingVariantRegen = null;
+      const scheduleVariantRegen = () => {
+        if (pendingVariantRegen) clearTimeout(pendingVariantRegen);
+        pendingVariantRegen = setTimeout(async () => {
+          pendingVariantRegen = null;
+          try {
+            const variantConfig = resolveImageVariantConfig(siteConfig);
+            const jobs = planVariantJobsFromFlatDir({
+              siteImgDir,
+              config: variantConfig,
+            });
+            await reconcileVariantCache({
+              jobs,
+              cacheDir: variantCacheDir,
+              manifestPath: variantManifestPath,
+              currentConfig: variantConfig,
+              log: (msg) => console.log(`[@koehler8/cms image-variants] ${msg}`),
+            });
+            // Invalidate the asset-resolver virtual module so its
+            // import.meta.glob re-evaluates and the new variant URLs land
+            // in the asset map. The full-reload below picks them up.
+            const assetMod = server.moduleGraph.getModuleById(resolved(VIRTUAL_ASSETS));
+            if (assetMod) server.moduleGraph.invalidateModule(assetMod);
+            server.ws.send({ type: 'full-reload' });
+          } catch (err) {
+            console.warn(`[@koehler8/cms image-variants] regen failed: ${err.message}`);
+          }
+        }, 250);
+      };
+      const handleImageEvent = (file) => {
+        if (typeof file !== 'string') return;
+        // Ignore writes our own pipeline made into the cache dir.
+        if (variantCacheDir && file.startsWith(variantCacheDir)) return;
+        if (!file.startsWith(siteImgDir)) return;
+        scheduleVariantRegen();
+      };
+      server.watcher.on('add', handleImageEvent);
+      server.watcher.on('change', handleImageEvent);
+      server.watcher.on('unlink', handleImageEvent);
+
       // Invalidate virtual modules when site content changes
       const invalidate = (file) => {
+        // Don't double-handle image events — the dedicated handler above
+        // already invalidates VIRTUAL_ASSETS and triggers full-reload.
+        if (variantCacheDir && file.startsWith(variantCacheDir)) return;
         if (!file.startsWith(siteDir)) return;
         for (const id of VIRTUAL_IDS) {
           const mod = server.moduleGraph.getModuleById(resolved(id));

package/bin/cms-generate-image-variants.js

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-// Wrapper that runs the framework's generate-image-variants.js from the
-// consuming site repo's CWD. Accepts --site-dir <path> to locate site assets;
-// defaults to ./site.
-
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const args = process.argv.slice(2);
-let siteDir = './site';
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--site-dir' && args[i + 1]) {
-    siteDir = args[i + 1];
-    i++;
-  }
-}
-
-const resolvedSiteDir = path.resolve(process.cwd(), siteDir);
-process.env.CMS_SITE_DIR = resolvedSiteDir;
-
-const { generateVariants } = await import(
-  path.resolve(__dirname, '..', 'scripts', 'generate-image-variants.js')
-);
-
-try {
-  await generateVariants({ siteDir: resolvedSiteDir });
-} catch (err) {
-  console.error(`❌ ${err.message}`);
-  process.exit(1);
-}

package/scripts/generate-image-variants.js

@@ -1,268 +0,0 @@
-/**
- * Generate responsive image variants from `{siteDir}/assets/img/_source/**`
- * into `{siteDir}/assets/img/`.
- *
- * For each source image (jpg/jpeg/png/webp/avif/tiff), produces:
- *   {name}-{width}.avif
- *   {name}-{width}.webp
- *   {name}-{width}.jpg
- * across the configured widths. Subdirectory layout is preserved.
- *
- * Skips variants whose mtime is newer than the source's mtime — re-running
- * the script after a `git pull` only regenerates the images that changed.
- *
- * Configuration is read from `{siteDir}/content/{baseLocale}/site.json`'s
- * optional `imageVariants` block; defaults are sensible for marketing sites.
- *
- * Usage from a consuming site:
- *   CMS_SITE_DIR=./site node node_modules/@koehler8/cms/scripts/generate-image-variants.js
- *
- * Or via the CLI wrapper:
- *   npx cms-generate-image-variants --site-dir ./site
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import sharp from 'sharp';
-
-import { inflateFlatConfig } from '../src/utils/inflateFlatConfig.js';
-
-// ---- Configuration ----
-
-const DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920, 2560];
-const DEFAULT_FORMATS = ['avif', 'webp', 'jpg'];
-const DEFAULT_QUALITY = { avif: 60, webp: 75, jpg: 80 };
-const SOURCE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.webp', '.avif', '.tiff', '.tif']);
-
-const FORMAT_OUTPUT_EXT = {
-  avif: 'avif',
-  webp: 'webp',
-  jpg: 'jpg',
-  jpeg: 'jpg',
-  png: 'png',
-};
-
-function readJsonIfExists(filePath) {
-  if (!fs.existsSync(filePath)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-function resolveSiteConfig(siteDir) {
-  const contentDir = path.join(siteDir, 'content');
-  const contentConfig = readJsonIfExists(path.join(contentDir, 'content.config.json')) || {};
-  const baseLocale = contentConfig.baseLocale || 'en';
-  const sitePath = path.join(contentDir, baseLocale, 'site.json');
-  const raw = readJsonIfExists(sitePath) || {};
-  return inflateFlatConfig(raw);
-}
-
-function normalizeWidths(input) {
-  if (!Array.isArray(input)) return [...DEFAULT_WIDTHS];
-  const filtered = input
-    .map((v) => Number.parseInt(v, 10))
-    .filter((v) => Number.isFinite(v) && v > 0);
-  if (!filtered.length) return [...DEFAULT_WIDTHS];
-  return [...new Set(filtered)].sort((a, b) => a - b);
-}
-
-function normalizeFormats(input) {
-  if (!Array.isArray(input)) return [...DEFAULT_FORMATS];
-  const filtered = input
-    .map((v) => (typeof v === 'string' ? v.trim().toLowerCase() : ''))
-    .filter((v) => v && FORMAT_OUTPUT_EXT[v]);
-  if (!filtered.length) return [...DEFAULT_FORMATS];
-  return [...new Set(filtered)];
-}
-
-function normalizeQuality(input) {
-  const merged = { ...DEFAULT_QUALITY };
-  if (input && typeof input === 'object') {
-    for (const [k, v] of Object.entries(input)) {
-      const n = Number.parseInt(v, 10);
-      if (Number.isFinite(n) && n >= 1 && n <= 100) merged[k] = n;
-    }
-  }
-  return merged;
-}
-
-// Resolve `imageVariants` config block, with safe defaults.
-export function resolveImageVariantConfig(siteConfig) {
-  const block = (siteConfig?.imageVariants && typeof siteConfig.imageVariants === 'object')
-    ? siteConfig.imageVariants
-    : {};
-  return {
-    widths: normalizeWidths(block.widths),
-    formats: normalizeFormats(block.formats),
-    quality: normalizeQuality(block.quality),
-  };
-}
-
-// ---- File walking ----
-
-function* walkSourceImages(sourceDir) {
-  if (!fs.existsSync(sourceDir)) return;
-  const stack = [sourceDir];
-  while (stack.length) {
-    const dir = stack.pop();
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(full);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      const ext = path.extname(entry.name).toLowerCase();
-      if (!SOURCE_EXTENSIONS.has(ext)) continue;
-      yield full;
-    }
-  }
-}
-
-// Build the list of (sourcePath, outputs[]) jobs without doing IO yet.
-export function planVariantJobs({ siteDir, config }) {
-  const imgDir = path.join(siteDir, 'assets', 'img');
-  const sourceDir = path.join(imgDir, '_source');
-  const jobs = [];
-  if (!fs.existsSync(sourceDir)) return jobs;
-
-  for (const sourcePath of walkSourceImages(sourceDir)) {
-    const relFromSource = path.relative(sourceDir, sourcePath);
-    const parsed = path.parse(relFromSource);
-    const subdir = parsed.dir;
-    const baseName = parsed.name;
-
-    const outputs = [];
-
-    // Copy the source to the flat dir under its bare name. Components that
-    // reference assets by their bare path (`resolveAsset('img/logo.png')`,
-    // useResponsiveImage's `${basePath}.${format}` fallback) need the
-    // original present at `site/assets/img/{name}.{ext}`; without this,
-    // sites that migrate originals into _source/ break every bare-path
-    // lookup.
-    outputs.push({
-      kind: 'copy',
-      outPath: path.join(imgDir, subdir, parsed.base),
-    });
-
-    for (const width of config.widths) {
-      for (const format of config.formats) {
-        const ext = FORMAT_OUTPUT_EXT[format];
-        if (!ext) continue;
-        const outName = `${baseName}-${width}.${ext}`;
-        const outPath = path.join(imgDir, subdir, outName);
-        outputs.push({ kind: 'variant', width, format, outPath });
-      }
-    }
-    jobs.push({ sourcePath, outputs });
-  }
-  return jobs;
-}
-
-// Apply a per-output sharp transform pipeline.
-async function renderOutput(sourcePath, output, config) {
-  const { width, format, outPath } = output;
-  await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
-
-  if (output.kind === 'copy') {
-    await fs.promises.copyFile(sourcePath, outPath);
-    return;
-  }
-
-  let pipeline = sharp(sourcePath, { failOn: 'truncated' }).rotate();
-  pipeline = pipeline.resize({ width, withoutEnlargement: true });
-  switch (format) {
-    case 'avif':
-      pipeline = pipeline.avif({ quality: config.quality.avif });
-      break;
-    case 'webp':
-      pipeline = pipeline.webp({ quality: config.quality.webp });
-      break;
-    case 'jpg':
-    case 'jpeg':
-      pipeline = pipeline.jpeg({ quality: config.quality.jpg, mozjpeg: true });
-      break;
-    case 'png':
-      pipeline = pipeline.png();
-      break;
-    default:
-      throw new Error(`unsupported format: ${format}`);
-  }
-  await pipeline.toFile(outPath);
-}
-
-function isUpToDate(sourcePath, outPath) {
-  if (!fs.existsSync(outPath)) return false;
-  try {
-    const src = fs.statSync(sourcePath).mtimeMs;
-    const dst = fs.statSync(outPath).mtimeMs;
-    return dst >= src;
-  } catch {
-    return false;
-  }
-}
-
-// ---- Main ----
-
-export async function generateVariants({ siteDir, log = console.log, warn = console.warn } = {}) {
-  if (!siteDir || !fs.existsSync(siteDir)) {
-    throw new Error(`siteDir does not exist: ${siteDir}`);
-  }
-  const siteConfig = resolveSiteConfig(siteDir);
-  const config = resolveImageVariantConfig(siteConfig);
-  const jobs = planVariantJobs({ siteDir, config });
-  if (jobs.length === 0) {
-    log(`[cms-image-variants] no sources found under ${path.join(siteDir, 'assets', 'img', '_source')}`);
-    return { generated: 0, skipped: 0, sources: 0 };
-  }
-
-  let generated = 0;
-  let skipped = 0;
-  for (const { sourcePath, outputs } of jobs) {
-    for (const output of outputs) {
-      if (isUpToDate(sourcePath, output.outPath)) {
-        skipped += 1;
-        continue;
-      }
-      try {
-        await renderOutput(sourcePath, output, config);
-        generated += 1;
-      } catch (err) {
-        warn(`[cms-image-variants] failed ${path.relative(siteDir, output.outPath)}: ${err.message}`);
-      }
-    }
-  }
-  log(
-    `[cms-image-variants] sources: ${jobs.length}, generated: ${generated}, skipped (up-to-date): ${skipped}`,
-  );
-  return { generated, skipped, sources: jobs.length };
-}
-
-// Allow invocation as `node scripts/generate-image-variants.js` (used by the
-// bin wrapper). Reads CMS_SITE_DIR like generate-public-assets does.
-const isMain = (() => {
-  try {
-    const __filename = new URL(import.meta.url).pathname;
-    return process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename);
-  } catch {
-    return false;
-  }
-})();
-
-if (isMain) {
-  const siteDir = process.env.CMS_SITE_DIR
-    ? path.resolve(process.env.CMS_SITE_DIR)
-    : null;
-  if (!siteDir) {
-    console.error('❌ CMS_SITE_DIR environment variable is required.');
-    console.error('   Example: CMS_SITE_DIR=./site npx cms-generate-image-variants');
-    process.exit(1);
-  }
-  generateVariants({ siteDir }).catch((err) => {
-    console.error(`❌ ${err.message}`);
-    process.exit(1);
-  });
-}