@koehler8/cms 1.0.0-beta.5 → 1.0.0-beta.7

package/README.md

@@ -75,15 +75,25 @@ vite-ssg build    # Static site generation
 
 ## Site Configuration
 
-Site content lives in `site/config/`:
+Site content lives in `site/content/`, organized by locale:
 
-- **`site.json`** -- Site-level metadata (title, description, URL, theme, Google Analytics ID)
-- **`shared.json`** -- Content blocks shared across pages (header, footer, socials)
-- **`pages/*.json`** -- Per-page content keyed by page ID
-
-### Locale Overrides
+```
+site/content/
+  content.config.json        # { "baseLocale": "en" }
+  en/
+    site.json                # Site metadata (flat dot-notation keys, sorted)
+    shared.json              # Shared content (header, footer, socials)
+    pages/
+      home.json              # Per-page content
+      privacy.json
+  de/
+    site.json                # German overrides (only translated keys)
+    shared.json
+    pages/
+      home.json
+```
 
-Place locale-specific configs in `site/config/i18n/{locale}/` mirroring the same structure. They are deep-merged over the base config at runtime.
+All files use flat dot-notation keys in alphabetical order. The base locale (specified in `content.config.json`) is loaded first; other locale directories override only the keys they specify. Missing keys fall back to the base locale value.
 
 **Supported locales:** en, fr, es, de, ja, ko, pt, ru, tr, vi, id, zh, th, hi, fil
 
@@ -91,7 +101,7 @@ Place locale-specific configs in `site/config/i18n/{locale}/` mirroring the same
 
 Themes export a manifest with design tokens (palette, typography, surfaces, CTAs, etc.) that are applied as CSS variables at runtime.
 
-- Set `site.theme` in `site.json` to a theme slug
+- Set the `theme` key in `content/{baseLocale}/site.json` to a theme slug
 - Omit it to use the built-in `base` theme
 - External themes are npm packages registered via the `themes` plugin option
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/scripts/generate-public-assets.js

@@ -3,7 +3,7 @@
 //
 // Reads from CMS_SITE_DIR env var (e.g. /path/to/my-site/site/).
 // Assets are read from {CMS_SITE_DIR}/assets/, config from
-// {CMS_SITE_DIR}/config/site.json, output is written to
+// {CMS_SITE_DIR}/content/{baseLocale}/site.json, output is written to
 // {dirname(CMS_SITE_DIR)}/public/.
 
 import 'dotenv/config';
@@ -260,12 +260,23 @@ function renderOgImageBuffer(text, { width = 1200, height = 630, bg = '#000000',
 }
 
 function loadSiteTitle() {
-  const configPath = path.join(CMS_SITE_DIR, 'config', 'site.json');
+  const contentDir = path.join(CMS_SITE_DIR, 'content');
+  const contentConfigPath = path.join(contentDir, 'content.config.json');
+  let baseLocale = 'en';
+  try {
+    if (fs.existsSync(contentConfigPath)) {
+      const cc = JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'));
+      baseLocale = cc.baseLocale || 'en';
+    }
+  } catch { /* use default */ }
+
+  const configPath = path.join(contentDir, baseLocale, 'site.json');
   if (!fs.existsSync(configPath)) return '';
   try {
     const raw = fs.readFileSync(configPath, 'utf-8');
     const parsed = JSON.parse(raw);
-    const title = parsed?.title || parsed?.site?.title;
+    // Flat format: key is "title"; nested format: key is "site.title" or nested
+    const title = parsed?.title || parsed?.['site.title'] || parsed?.site?.title;
     if (typeof title === 'string' && title.trim()) {
       return title.trim();
     }

package/scripts/migrate-to-content-dirs.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Migration script: converts site/config/ structure to site/content/ structure.
+ *
+ * Old layout:
+ *   site/config/site.json          (nested)
+ *   site/config/shared.json        (nested)
+ *   site/config/pages/*.json       (nested)
+ *   site/config/i18n/{locale}.json (flat dot-notation)
+ *
+ * New layout:
+ *   site/content/content.config.json  ({ "baseLocale": "en" })
+ *   site/content/en/site.json         (flat dot-notation, sorted)
+ *   site/content/en/shared.json       (flat dot-notation, sorted)
+ *   site/content/en/pages/*.json      (flat dot-notation, sorted)
+ *   site/content/{locale}/site.json   (flat dot-notation, sorted, overrides only)
+ *   site/content/{locale}/shared.json
+ *   site/content/{locale}/pages/*.json
+ *
+ * Usage:
+ *   node scripts/migrate-to-content-dirs.mjs /path/to/site-repo
+ *   node scripts/migrate-to-content-dirs.mjs /path/to/site-repo --commit
+ *
+ * Without --commit, runs in dry-run mode (prints what it would do).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---- Flatten utility ----
+
+const ARRAY_INDEX_RE = /\[(\d+)]/g;
+
+function flattenObject(obj, prefix = '') {
+  const result = {};
+  if (!obj || typeof obj !== 'object') return result;
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+
+    if (Array.isArray(value)) {
+      value.forEach((item, idx) => {
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+          Object.assign(result, flattenObject(item, `${fullKey}[${idx}]`));
+        } else {
+          result[`${fullKey}[${idx}]`] = item;
+        }
+      });
+    } else if (value && typeof value === 'object') {
+      Object.assign(result, flattenObject(value, fullKey));
+    } else {
+      result[fullKey] = value;
+    }
+  }
+  return result;
+}
+
+function sortedJson(obj) {
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = obj[key];
+  }
+  return JSON.stringify(sorted, null, 2) + '\n';
+}
+
+// ---- Main ----
+
+const siteRepoDir = process.argv[2];
+const commit = process.argv.includes('--commit');
+
+if (!siteRepoDir) {
+  console.error('Usage: node scripts/migrate-to-content-dirs.mjs /path/to/site-repo [--commit]');
+  process.exit(1);
+}
+
+const siteDir = path.join(siteRepoDir, 'site');
+const configDir = path.join(siteDir, 'config');
+const contentDir = path.join(siteDir, 'content');
+
+if (!fs.existsSync(configDir)) {
+  console.error(`Config directory not found: ${configDir}`);
+  process.exit(1);
+}
+
+const actions = [];
+
+function plan(action, detail) {
+  actions.push({ action, detail });
+  if (!commit) console.log(`  [dry-run] ${action}: ${detail}`);
+}
+
+// 1. Flatten and move English base files
+const enDir = path.join(contentDir, 'en');
+const enPagesDir = path.join(enDir, 'pages');
+
+// site.json
+const siteJsonPath = path.join(configDir, 'site.json');
+if (fs.existsSync(siteJsonPath)) {
+  const nested = JSON.parse(fs.readFileSync(siteJsonPath, 'utf-8'));
+  const flat = flattenObject(nested);
+  plan('write', `content/en/site.json (${Object.keys(flat).length} keys)`);
+  if (commit) {
+    fs.mkdirSync(enDir, { recursive: true });
+    fs.writeFileSync(path.join(enDir, 'site.json'), sortedJson(flat));
+  }
+}
+
+// shared.json
+const sharedJsonPath = path.join(configDir, 'shared.json');
+if (fs.existsSync(sharedJsonPath)) {
+  const nested = JSON.parse(fs.readFileSync(sharedJsonPath, 'utf-8'));
+  const flat = flattenObject(nested);
+  plan('write', `content/en/shared.json (${Object.keys(flat).length} keys)`);
+  if (commit) {
+    fs.mkdirSync(enDir, { recursive: true });
+    fs.writeFileSync(path.join(enDir, 'shared.json'), sortedJson(flat));
+  }
+}
+
+// pages/*.json
+const pagesDir = path.join(configDir, 'pages');
+if (fs.existsSync(pagesDir)) {
+  for (const file of fs.readdirSync(pagesDir)) {
+    if (!file.endsWith('.json')) continue;
+    const nested = JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8'));
+    const flat = flattenObject(nested);
+    plan('write', `content/en/pages/${file} (${Object.keys(flat).length} keys)`);
+    if (commit) {
+      fs.mkdirSync(enPagesDir, { recursive: true });
+      fs.writeFileSync(path.join(enPagesDir, file), sortedJson(flat));
+    }
+  }
+}
+
+// 2. Split i18n flat files into locale directories
+const i18nDir = path.join(configDir, 'i18n');
+if (fs.existsSync(i18nDir)) {
+  // Read page filenames from config/pages/ to know valid page scopes
+  const pageFiles = fs.existsSync(pagesDir)
+    ? fs.readdirSync(pagesDir).filter((f) => f.endsWith('.json')).map((f) => f.replace('.json', ''))
+    : [];
+
+  for (const file of fs.readdirSync(i18nDir)) {
+    if (!file.endsWith('.json')) continue;
+    const locale = file.replace('.json', '');
+    const localeDir = path.join(contentDir, locale);
+    const localePagesDir = path.join(localeDir, 'pages');
+
+    const raw = JSON.parse(fs.readFileSync(path.join(i18nDir, file), 'utf-8'));
+
+    // Buckets: site.*, shared.*, pages.{pageId}.*
+    const siteBucket = {};
+    const sharedBucket = {};
+    const pageBuckets = {};
+
+    for (const [key, value] of Object.entries(raw)) {
+      if (key.startsWith('$')) continue;
+
+      if (key.startsWith('site.')) {
+        siteBucket[key.slice('site.'.length)] = value;
+      } else if (key.startsWith('shared.')) {
+        sharedBucket[key.slice('shared.'.length)] = value;
+      } else if (key.startsWith('pages.')) {
+        const rest = key.slice('pages.'.length);
+        const dotIdx = rest.indexOf('.');
+        if (dotIdx === -1) continue;
+        const pageId = rest.slice(0, dotIdx);
+        const pageKey = rest.slice(dotIdx + 1);
+        if (!pageBuckets[pageId]) pageBuckets[pageId] = {};
+        pageBuckets[pageId][pageKey] = value;
+      }
+    }
+
+    if (Object.keys(siteBucket).length > 0) {
+      plan('write', `content/${locale}/site.json (${Object.keys(siteBucket).length} keys)`);
+      if (commit) {
+        fs.mkdirSync(localeDir, { recursive: true });
+        fs.writeFileSync(path.join(localeDir, 'site.json'), sortedJson(siteBucket));
+      }
+    }
+
+    if (Object.keys(sharedBucket).length > 0) {
+      plan('write', `content/${locale}/shared.json (${Object.keys(sharedBucket).length} keys)`);
+      if (commit) {
+        fs.mkdirSync(localeDir, { recursive: true });
+        fs.writeFileSync(path.join(localeDir, 'shared.json'), sortedJson(sharedBucket));
+      }
+    }
+
+    for (const [pageId, pageData] of Object.entries(pageBuckets)) {
+      if (Object.keys(pageData).length === 0) continue;
+      plan('write', `content/${locale}/pages/${pageId}.json (${Object.keys(pageData).length} keys)`);
+      if (commit) {
+        fs.mkdirSync(localePagesDir, { recursive: true });
+        fs.writeFileSync(path.join(localePagesDir, `${pageId}.json`), sortedJson(pageData));
+      }
+    }
+  }
+}
+
+// 3. Create content.config.json
+plan('write', 'content/content.config.json');
+if (commit) {
+  fs.mkdirSync(contentDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(contentDir, 'content.config.json'),
+    JSON.stringify({ baseLocale: 'en' }, null, 2) + '\n'
+  );
+}
+
+// 4. Remove old config directory
+if (commit) {
+  fs.rmSync(configDir, { recursive: true, force: true });
+  plan('remove', 'config/ directory');
+} else {
+  plan('remove', 'config/ directory (would be removed)');
+}
+
+console.log(`\n${commit ? 'Migration complete' : 'Dry run complete'}. ${actions.length} actions.`);
+if (!commit) {
+  console.log('Run with --commit to apply changes.');
+}

package/src/components/Header.vue

@@ -85,14 +85,14 @@ import { computed, inject, nextTick, onBeforeUnmount, onMounted, ref, watch } fr
   import { resolveAsset } from '../utils/assetResolver.js';
 import { trackEvent } from '../utils/analytics.js';
 import { getExtensionComponent } from '../extensions/extensionLoader.js';
-import SUPPORTED_LOCALES from '../constants/locales.js';
+import { availableLocales as siteLocales } from '../utils/loadConfig.js';
 
   const logoSrc = computed(() => resolveAsset('img/logo.png'));
 
 const isLangOpen = ref(false);
 const isHeaderCompact = ref(false);
 const currentLocale = ref('');
-const availableLocales = computed(() => SUPPORTED_LOCALES.map((code) => code.trim()).filter(Boolean));
+const availableLocales = computed(() => siteLocales.map((code) => code.trim()).filter(Boolean));
 const localeLabels = {
   en: 'English',
   fr: 'Français',

package/src/utils/loadConfig.js

@@ -133,44 +133,84 @@ export function mergeConfigTrees(target, source, options = {}) {
 export function createConfigLoader(allModules) {
     const toPlain = unwrapDefault;
 
-    // Find the site.json path and derive the config prefix (everything up to
-    // and including `/config/`) so subsequent lookups are scoped correctly.
-    function findSiteConfigPrefix() {
+    // Discover which locale directories exist in the content folder by
+    // extracting unique locale codes from the allModules glob keys.
+    function discoverAvailableLocales() {
+        const locales = new Set();
+        const re = /\/content\/([a-z]{2,3}(?:-[a-zA-Z]{2,4})?)\//;
+        for (const key of Object.keys(allModules)) {
+            const match = key.match(re);
+            if (match) locales.add(match[1].toLowerCase());
+        }
+        return Array.from(locales).sort();
+    }
+
+    const availableLocales = discoverAvailableLocales();
+
+    // Find the content root (path ending in `/content/`) and resolve the base
+    // locale from content.config.json.
+    function findContentRoot() {
         const keys = Object.keys(allModules);
-        const siteJsonKeys = keys.filter((key) => key.endsWith('/config/site.json'));
-        if (siteJsonKeys.length === 1) {
-            const key = siteJsonKeys[0];
-            return key.slice(0, key.length - 'site.json'.length);
+        const configKey = keys.find((key) => key.endsWith('/content/content.config.json'));
+        if (configKey) {
+            return configKey.slice(0, configKey.length - 'content.config.json'.length);
         }
         return null;
     }
 
-    async function assembleBaseConfig() {
-        const prefix = findSiteConfigPrefix();
-        if (!prefix) return null;
-
-        const siteLoader = allModules[`${prefix}site.json`];
-        if (!siteLoader) return null;
+    async function resolveBaseLocale(contentRoot) {
+        const configLoader = allModules[`${contentRoot}content.config.json`];
+        if (!configLoader) return 'en';
+        const config = toPlain(await configLoader());
+        return (config && config.baseLocale) || 'en';
+    }
 
-        const sharedLoader = allModules[`${prefix}shared.json`];
-        const [siteData, sharedData] = await Promise.all([
-            siteLoader().then(toPlain),
+    // Assemble a config from a locale directory: inflates flat-format files
+    // (site.json, shared.json, pages/*.json) and returns { site, shared, pages }.
+    // When require is true, returns null if site.json is missing (used for
+    // base config). When false, assembles whatever files exist (used for
+    // locale overrides that may only contain partial translations).
+    async function assembleSplitConfig(localePrefix, { require: requireSite = false } = {}) {
+        const siteLoader = allModules[`${localePrefix}site.json`];
+        if (!siteLoader && requireSite) return null;
+
+        const sharedLoader = allModules[`${localePrefix}shared.json`];
+        const [rawSite, rawShared] = await Promise.all([
+            siteLoader ? siteLoader().then(toPlain) : Promise.resolve({}),
             sharedLoader ? sharedLoader().then(toPlain) : Promise.resolve({}),
         ]);
+        const siteData = inflateFlatConfig(rawSite);
+        const sharedData = inflateFlatConfig(rawShared);
 
-        // Collect only the pages that belong to this site's config directory
-        const pagePrefix = `${prefix}pages/`;
+        const pagePrefix = `${localePrefix}pages/`;
         const pages = {};
         const pageLoads = [];
         for (const [path, loader] of Object.entries(allModules)) {
             if (path.startsWith(pagePrefix) && path.endsWith('.json')) {
                 const pageId = path.slice(pagePrefix.length, -5);
-                pageLoads.push(loader().then((mod) => { pages[pageId] = toPlain(mod); }));
+                pageLoads.push(
+                    loader().then((mod) => { pages[pageId] = inflateFlatConfig(toPlain(mod)); })
+                );
             }
         }
         await Promise.all(pageLoads);
 
-        return { site: siteData, shared: sharedData, pages, _configPrefix: prefix };
+        // Return null if no files were found at all for this locale
+        if (!siteLoader && !sharedLoader && Object.keys(pages).length === 0) return null;
+
+        return { site: siteData, shared: sharedData, pages };
+    }
+
+    async function assembleBaseConfig() {
+        const contentRoot = findContentRoot();
+        if (!contentRoot) return null;
+
+        const baseLocale = await resolveBaseLocale(contentRoot);
+        const basePrefix = `${contentRoot}${baseLocale}/`;
+        const config = await assembleSplitConfig(basePrefix, { require: true });
+        if (!config) return null;
+
+        return { ...config, _contentRoot: contentRoot, _baseLocale: baseLocale };
     }
 
     async function loadConfigData(options) {
@@ -202,22 +242,24 @@ export function createConfigLoader(allModules) {
 
         if (normalizedLocale === undefined) {
             const config = await getBaseConfig();
-            delete config._configPrefix;
+            delete config._contentRoot;
+            delete config._baseLocale;
             return config;
         }
 
         const baseConfig = await getBaseConfig();
 
         let mergedConfig = baseConfig;
-        // Find locale override scoped to the same config directory as the site
-        const configPrefix = baseConfig._configPrefix;
-        const localizedLoader = configPrefix
-            ? allModules[`${configPrefix}i18n/${normalizedLocale}.json`]
-            : undefined;
-        if (localizedLoader) {
-            const rawLocalized = toPlain(await localizedLoader());
-            const localizedConfig = inflateFlatConfig(rawLocalized);
-            mergedConfig = mergeConfigTrees(baseConfig, localizedConfig, { cloneTarget: true, skipEmpty: true });
+        const contentRoot = baseConfig._contentRoot;
+        const baseLocale = baseConfig._baseLocale;
+
+        // Only load locale overrides if the requested locale differs from the base
+        if (contentRoot && normalizedLocale !== baseLocale) {
+            const localePrefix = `${contentRoot}${normalizedLocale}/`;
+            const localeConfig = await assembleSplitConfig(localePrefix);
+            if (localeConfig) {
+                mergedConfig = mergeConfigTrees(baseConfig, localeConfig, { cloneTarget: true, skipEmpty: true });
+            }
         }
         if (mergedConfig && mergedConfig.pages && typeof mergedConfig.pages === 'object') {
             for (const page of Object.values(mergedConfig.pages)) {
@@ -247,11 +289,12 @@ export function createConfigLoader(allModules) {
                 });
             }
         }
-        delete mergedConfig._configPrefix;
+        delete mergedConfig._contentRoot;
+        delete mergedConfig._baseLocale;
         return mergedConfig;
     }
 
-    return { loadConfigData, mergeConfigTrees, cloneConfig };
+    return { loadConfigData, mergeConfigTrees, cloneConfig, availableLocales };
 }
 
 // ---- Runtime singleton ----
@@ -263,9 +306,14 @@ let _loadConfigData = async () => {
   throw new Error('[@koehler8/cms] loadConfigData() called before config loader was initialized');
 };
 
+let _availableLocales = [];
+
 export function setConfigLoader(instance) {
   if (!instance) return;
   _loadConfigData = instance.loadConfigData;
+  _availableLocales = instance.availableLocales || [];
 }
 
+export { _availableLocales as availableLocales };
+
 export const loadConfigData = (...args) => _loadConfigData(...args);

package/vite-plugin.js

@@ -12,24 +12,25 @@ import { fileURLToPath } from 'node:url';
 import vue from '@vitejs/plugin-vue';
 
 import { SUPPORTED_LOCALES } from './src/constants/locales.js';
+import { inflateFlatConfig } from './src/utils/inflateFlatConfig.js';
 
 // ---- Helpers ----
 
-function loadSplitConfig(configDir) {
-  const sitePath = path.join(configDir, 'site.json');
+function loadSplitConfig(contentLocaleDir) {
+  const sitePath = path.join(contentLocaleDir, 'site.json');
   if (!fs.existsSync(sitePath)) return null;
 
-  const site = JSON.parse(fs.readFileSync(sitePath, 'utf-8'));
-  const sharedPath = path.join(configDir, 'shared.json');
-  const shared = fs.existsSync(sharedPath) ? JSON.parse(fs.readFileSync(sharedPath, 'utf-8')) : {};
+  const site = inflateFlatConfig(JSON.parse(fs.readFileSync(sitePath, 'utf-8')));
+  const sharedPath = path.join(contentLocaleDir, 'shared.json');
+  const shared = fs.existsSync(sharedPath) ? inflateFlatConfig(JSON.parse(fs.readFileSync(sharedPath, 'utf-8'))) : {};
 
-  const pagesDir = path.join(configDir, 'pages');
+  const pagesDir = path.join(contentLocaleDir, 'pages');
   const pages = {};
   if (fs.existsSync(pagesDir)) {
     for (const file of fs.readdirSync(pagesDir)) {
       if (!file.endsWith('.json')) continue;
       const pageId = file.replace('.json', '');
-      pages[pageId] = JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8'));
+      pages[pageId] = inflateFlatConfig(JSON.parse(fs.readFileSync(path.join(pagesDir, file), 'utf-8')));
     }
   }
 
@@ -356,7 +357,13 @@ export default function cmsPlugin(options = {}) {
       tempEntryPath = path.join(siteRoot, ENTRY_FILENAME);
 
       // Load site config at config-resolution time (needed for SSG routes + HTML injection)
-      const configDir = path.join(siteDir, 'config');
+      const contentDir = path.join(siteDir, 'content');
+      const contentConfigPath = path.join(contentDir, 'content.config.json');
+      const contentConfig = fs.existsSync(contentConfigPath)
+        ? JSON.parse(fs.readFileSync(contentConfigPath, 'utf-8'))
+        : {};
+      const baseLocale = contentConfig.baseLocale || 'en';
+      const configDir = path.join(contentDir, baseLocale);
       siteConfig = loadSplitConfig(configDir);
       if (!siteConfig) {
         throw new Error(`[@koehler8/cms] site config not found at ${configDir}`);
@@ -431,7 +438,7 @@ export default function cmsPlugin(options = {}) {
           // native ESM resolver cannot handle.  Marking them as noExternal
           // tells Vite to bundle them during SSR so its Vue/JSON plugins
           // process the files instead of Node.
-          noExternal: ['@koehler8/cms', ...extensionPackages],
+          noExternal: ['@koehler8/cms', ...themePackages, ...extensionPackages],
         },
         test: {
           environment: 'happy-dom',
@@ -479,11 +486,12 @@ export default function cmsPlugin(options = {}) {
       if (virtualId === VIRTUAL_CONFIG) {
         return `
 import { createConfigLoader } from '@koehler8/cms/utils/loadConfig';
-const allModules = import.meta.glob('@cms-site/config/**/*.json');
+const allModules = import.meta.glob('@cms-site/content/**/*.json');
 const loader = createConfigLoader(allModules);
 export const loadConfigData = loader.loadConfigData;
 export const mergeConfigTrees = loader.mergeConfigTrees;
 export const cloneConfig = loader.cloneConfig;
+export const availableLocales = loader.availableLocales;
 `;
       }