@koehler8/cms 1.0.0-beta.21 → 1.0.0-beta.23

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

@@ -0,0 +1,33 @@
+#!/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.23",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,15 @@
   "bugs": {
     "url": "https://github.com/koehler8/cms/issues"
   },
-  "keywords": ["vue", "cms", "vite", "ssg", "theming", "extensions", "config-driven"],
+  "keywords": [
+    "vue",
+    "cms",
+    "vite",
+    "ssg",
+    "theming",
+    "extensions",
+    "config-driven"
+  ],
   "scripts": {
     "postinstall": "node scripts/patch-lru-cache-tla.js",
     "test": "vitest run",
@@ -46,6 +54,7 @@
   },
   "bin": {
     "cms-generate-public-assets": "./bin/cms-generate-public-assets.js",
+    "cms-generate-image-variants": "./bin/cms-generate-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",
@@ -77,7 +86,8 @@
     "canvas": "^3.2.0",
     "dotenv": "^17.2.3",
     "pinia": "^3.0.1",
-    "png-to-ico": "^3.0.1"
+    "png-to-ico": "^3.0.1",
+    "sharp": "^0.33.5"
   },
   "devDependencies": {
     "@vue/test-utils": "^2.4.6",

package/scripts/generate-image-variants.js

@@ -0,0 +1,251 @@
+/**
+ * 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 = [];
+    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({ 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 });
+
+  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);
+  });
+}

package/src/composables/usePageMeta.js

@@ -4,6 +4,7 @@ import { isPathDraft } from '../utils/draftMode.js';
 import { buildCanonicalUrl } from '../utils/canonicalUrl.js';
 import { buildSocialMeta } from '../utils/socialMeta.js';
 import { buildJsonLdScripts } from '../utils/jsonLd.js';
+import { buildBreadcrumbList } from '../utils/breadcrumbs.js';
 import { availableLocales as configAvailableLocales, baseLocale as configBaseLocale } from '../utils/loadConfig.js';
 
 // Site-verification meta-tag names per platform. Authors set
@@ -205,6 +206,25 @@ export function usePageMeta({ siteData, currentPage, locale }) {
       isNotFound: isNotFound.value,
     });
 
+    // Auto-generated BreadcrumbList JSON-LD. Appended after any
+    // author-supplied jsonld blocks so authors can override by emitting a
+    // hand-authored BreadcrumbList of their own (Google takes the first
+    // valid one when multiple are present).
+    const breadcrumb = buildBreadcrumbList({
+      siteUrl: siteUrl.value,
+      currentPage: currentPage.value,
+      pages: siteData.value?.pages,
+      baseLocale: configBaseLocale,
+      locale: localeValue.value,
+    });
+    if (breadcrumb && !isDraft.value && !isNotFound.value) {
+      script.push({
+        type: 'application/ld+json',
+        innerHTML: JSON.stringify(breadcrumb),
+        key: 'jsonld-BreadcrumbList',
+      });
+    }
+
     return {
       title: pageMetaTitle.value,
       meta,

package/src/utils/breadcrumbs.js

@@ -0,0 +1,118 @@
+/**
+ * Build a JSON-LD `BreadcrumbList` for the current page from URL path
+ * segments and the inflated pages map. Drives Google's breadcrumb display
+ * in search results without authors having to hand-author the schema.
+ *
+ * Returns `null` when breadcrumbs aren't applicable (home, draft, 404,
+ * single-segment path with no resolvable hierarchy, missing site.url, or
+ * per-page opt-out via `currentPage.meta.breadcrumbs === false`).
+ *
+ * Label resolution priority for each path prefix `/seg1/seg2/...`:
+ *   1. A page in the inflated config whose `path` matches → its
+ *      `meta.title`, falling back to a slug-derived title-case label.
+ *   2. Otherwise → the last segment formatted (`my-post-title` →
+ *      `My Post Title`).
+ *
+ * The first entry is always `Home` linked at the canonical home URL. The
+ * last entry is the current page; its `item` URL is included (Google
+ * accepts both forms; including is more interoperable).
+ */
+
+import { buildCanonicalUrl } from './canonicalUrl.js';
+
+function normalizePath(value) {
+  if (typeof value !== 'string') return '/';
+  const trimmed = value.trim();
+  if (!trimmed) return '/';
+  let p = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  return p || '/';
+}
+
+function titleCaseSlug(slug) {
+  if (typeof slug !== 'string') return '';
+  return slug
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function findPageByPath(pages, targetPath) {
+  if (!pages || typeof pages !== 'object') return null;
+  const norm = normalizePath(targetPath);
+  for (const data of Object.values(pages)) {
+    if (!data || typeof data !== 'object') continue;
+    if (normalizePath(data.path) === norm) return data;
+  }
+  return null;
+}
+
+function resolveLabel(pages, prefixPath, lastSegment) {
+  const page = findPageByPath(pages, prefixPath);
+  const explicitTitle = page?.meta?.title;
+  if (typeof explicitTitle === 'string' && explicitTitle.trim()) {
+    return explicitTitle.trim();
+  }
+  return titleCaseSlug(lastSegment) || lastSegment || '';
+}
+
+export function buildBreadcrumbList({
+  siteUrl,
+  currentPage,
+  pages,
+  baseLocale,
+  locale,
+} = {}) {
+  if (!currentPage || typeof currentPage !== 'object') return null;
+  if (currentPage.isNotFound) return null;
+  if (currentPage.draft === true) return null;
+  if (currentPage.meta && currentPage.meta.breadcrumbs === false) return null;
+
+  const host = (typeof siteUrl === 'string' ? siteUrl : '').trim().replace(/\/+$/, '');
+  if (!host) return null;
+
+  const targetPath = normalizePath(currentPage.path);
+  if (targetPath === '/' || targetPath === '') return null;
+
+  const segments = targetPath.split('/').filter(Boolean);
+  if (segments.length === 0) return null;
+
+  const homeHref = buildCanonicalUrl({
+    siteUrl: host,
+    locale,
+    baseLocale,
+    path: '/',
+  });
+
+  const items = [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: 'Home',
+      item: homeHref,
+    },
+  ];
+
+  for (let i = 0; i < segments.length; i++) {
+    const prefixPath = `/${segments.slice(0, i + 1).join('/')}`;
+    const href = buildCanonicalUrl({
+      siteUrl: host,
+      locale,
+      baseLocale,
+      path: prefixPath,
+    });
+    items.push({
+      '@type': 'ListItem',
+      position: items.length + 1,
+      name: resolveLabel(pages, prefixPath, segments[i]),
+      item: href,
+    });
+  }
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items,
+  };
+}

package/vite-plugin.js

@@ -466,16 +466,23 @@ export default function cmsPlugin(options = {}) {
       if (!siteConfig) {
         throw new Error(`[@koehler8/cms] site config not found at ${configDir}`);
       }
-      // Discover locales actually present on disk: directories under
-      // content/ that contain a site.json. This becomes the authoritative
-      // list for both the SSG route fanout and the runtime locale-aware
-      // canonical/hreflang emission.
+      // Discover locales actually present on disk: any directory under
+      // content/ that has at least one of `site.json`, `shared.json`, or
+      // a `pages/` subdir is treated as a real locale. (Earlier the check
+      // required `site.json` specifically — too strict for sites that
+      // author per-locale page overrides without overriding the site
+      // metadata, which is the common pattern for translation-only locale
+      // dirs.)
+      const localeDirHasContent = (dir) =>
+        fs.existsSync(path.join(dir, 'site.json'))
+        || fs.existsSync(path.join(dir, 'shared.json'))
+        || fs.existsSync(path.join(dir, 'pages'));
       availableLocales = fs.existsSync(contentDir)
         ? fs
             .readdirSync(contentDir, { withFileTypes: true })
             .filter((d) => d.isDirectory())
             .map((d) => d.name)
-            .filter((name) => fs.existsSync(path.join(contentDir, name, 'site.json')))
+            .filter((name) => localeDirHasContent(path.join(contentDir, name)))
             .sort()
         : [];
       pagePaths = collectPagePaths(siteConfig);