@koehler8/cms 1.0.0-beta.14 → 1.0.0-beta.16

package/bin/cms-create-site.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'create-site.mjs');
+await import(pathToFileURL(scriptPath).href);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.16",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",
@@ -49,7 +49,8 @@
     "cms-validate-themes": "./bin/cms-validate-themes.js",
     "cms-validate-extensions": "./bin/cms-validate-extensions.js",
     "cms-create-theme": "./bin/cms-create-theme.js",
-    "cms-create-extension": "./bin/cms-create-extension.js"
+    "cms-create-extension": "./bin/cms-create-extension.js",
+    "cms-create-site": "./bin/cms-create-site.js"
   },
   "files": [
     "src",

package/scripts/create-site.mjs

@@ -0,0 +1,11 @@
+import { runScaffold } from './scaffold.mjs';
+
+const result = await runScaffold({
+  kind: 'site',
+  argv: process.argv.slice(2),
+});
+
+if (result.message) {
+  process[result.ok ? 'stdout' : 'stderr'].write(result.message + '\n');
+}
+process.exit(result.ok ? 0 : 1);

package/scripts/scaffold.mjs

@@ -53,11 +53,16 @@ async function pathExists(p) {
   }
 }
 
+// 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 (entry.name.startsWith('.')) continue;
+    if (TEMPLATE_SKIP.has(entry.name)) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...(await collectTemplateFiles(full)));
@@ -86,7 +91,7 @@ function applySubstitutions(content, subs) {
  * @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') {
+  if (kind !== 'theme' && kind !== 'extension' && kind !== 'site') {
     return { ok: false, message: `unknown kind: ${kind}` };
   }
   const root = frameworkRoot || defaultFrameworkRoot();
@@ -115,10 +120,18 @@ export async function runScaffold({ kind, argv, cwd = process.cwd(), frameworkRo
   const displayName = toDisplayName(slug);
   const subs = { __SLUG__: slug, __DISPLAY_NAME__: displayName };
   const templateDir = path.join(root, 'templates', 'scaffolds', kind);
-  const defaultDirName = kind === 'theme' ? 'themes' : 'extensions';
-  const targetDir = args.out
-    ? path.resolve(cwd, args.out)
-    : path.join(cwd, defaultDirName, slug);
+  // 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 {
@@ -153,8 +166,7 @@ export async function runScaffold({ kind, argv, cwd = process.cwd(), frameworkRo
 }
 
 function successHeader(kind, slug, targetRel) {
-  const fileCount = kind === 'theme' ? 5 : 4;
-  return `✓ Scaffolded ${kind} "${slug}" → ${targetRel}/ (${fileCount} files)`;
+  return `✓ Scaffolded ${kind} "${slug}" → ${targetRel}/`;
 }
 
 function nextSteps(kind, slug, targetRel) {
@@ -173,33 +185,57 @@ function nextSteps(kind, slug, targetRel) {
       '',
     ].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. 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.`,
+    `  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 cmd = kind === 'theme' ? 'cms-create-theme' : 'cms-create-extension';
-  const dir = kind === 'theme' ? 'themes' : 'extensions';
+  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 site.
+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 ./${dir}/<slug>/.
+  --out <dir>     Where to create the ${kind}. Defaults to ${defaultDir}.
   --force         Overwrite an existing target directory.
   -h, --help      Show this message.
 `;

package/src/components/Home.vue

@@ -10,21 +10,6 @@
       :key="entry.key"
       v-bind="entry.props"
     />
-    <div
-      v-if="showLoadingIndicator"
-      class="page-loading-placeholder"
-      role="status"
-      aria-live="polite"
-    >
-      Loading…
-    </div>
-    <div
-      v-else-if="loadErrorMessage"
-      class="page-error-message"
-      role="alert"
-    >
-      {{ loadErrorMessage }}
-    </div>
   </main>
   <ComingSoonModal
     :open="isComingSoonVisible"
@@ -35,7 +20,7 @@
 </template>
 
 <script setup>
-import { computed, nextTick, onMounted, provide, ref, watch } from 'vue';
+import { computed, nextTick, provide, watch } from 'vue';
 
 import ComingSoonModal from '../components/ComingSoonModal.vue';
 import IntroGate from '../components/IntroGate.vue';
@@ -106,25 +91,13 @@ provide('pageContent', pageContent);
 provide('pageConfig', currentPage);
 provide('currentPageId', computed(() => currentPage.value.id));
 
-// Suppress the loading placeholder during the initial hydration tick
-// so SSG-rendered pages don't flash "Loading…" while the client-side
-// syncPage briefly resets componentKeys to []. After the first mount
-// completes, genuine slow loads (real navigation) can still surface
-// the placeholder.
-const isHydrating = ref(true);
-onMounted(() => {
-  nextTick().then(() => {
-    isHydrating.value = false;
-  });
-});
-
-const showLoadingIndicator = computed(() =>
-  !isHydrating.value &&
-  isLoading.value &&
-  componentKeys.value.length === 0 &&
-  !loadError.value
-);
-const loadErrorMessage = computed(() => loadError.value ? (loadError.value.message || 'Unable to load page content.') : '');
+// Loading + error state are exposed via inject so sites can build their
+// own preloader / error surface as a component (e.g. site/components/
+// Preloader.vue or the bundled Preloader). Home itself no longer renders
+// any built-in placeholder UI — sites that want one opt in by listing a
+// preloader component in their pages/{pageId}.json `components[]`.
+provide('pageIsLoading', isLoading);
+provide('pageLoadError', loadError);
 
 watch(componentKeys, async () => {
   await nextTick();
@@ -142,20 +115,3 @@ watch(
 );
 </script>
 
-<style scoped>
-.page-loading-placeholder,
-.page-error-message {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 40vh;
-  font-size: 1.125rem;
-  font-weight: 600;
-  color: #111;
-  text-align: center;
-}
-
-.page-error-message {
-  color: #b00020;
-}
-</style>

package/templates/scaffolds/site/.nvmrc

@@ -0,0 +1 @@
+20.19.0

package/templates/scaffolds/site/CLAUDE.md

@@ -0,0 +1,121 @@
+# site-__SLUG__
+
+(staging URL TBD)
+
+A site built on the [`@koehler8/cms`](https://github.com/koehler8/cms) framework. **Owner: TBD.** This file is auto-loaded by Claude Code in this directory — read it before making changes.
+
+## Project status
+
+Freshly scaffolded via `npx cms-create-site`. Home page renders the bundled `Header` + `Hero` + `Footer` components with placeholder copy. No theme, extension, or custom components yet — see "Where things go" below for the path each new addition should take.
+
+## Working with the site owner
+
+Assume the owner is not a developer unless you know otherwise. Default behaviors:
+
+- Explain trade-offs in plain language; propose options, don't present decisions.
+- Confirm before structural or visual changes that will be hard to reverse.
+- Push small, reviewable changes frequently and verify on the live URL.
+- Don't over-engineer — most requests can be satisfied by editing `pages/*.json` + bundled CMS components. Reach for a custom Vue component only when the bundled set clearly can't do the job.
+
+## Where things go (the navigation guide)
+
+| Goal | Where |
+|---|---|
+| Edit page copy / hero text / section content | `site/content/{locale}/pages/{pageId}.json` under `content.{configKey}.*` keys |
+| Edit site title, theme key, support email | `site/content/{locale}/site.json` |
+| Edit header logo text, nav items, footer flags | `site/content/{locale}/shared.json` |
+| Add a translation | Mirror the keys you want to override into `site/content/{otherLocale}/...` (only set the keys that differ — the rest inherit from the base locale) |
+| Add an asset (image, icon) | `site/assets/img/...`. Reference it from a component via `resolveAsset('img/foo.png')` or a URL string in content (`"img/foo.png"`) |
+| Override the favicon | Drop a real `.ico` at `site/favicon.ico`; the `cms-generate-public-assets` script picks it up |
+| Add a one-off Vue component (this site only) | `site/components/Foo.vue`. Auto-globbed by the CMS — reference it as `"Foo"` in any page's `components[]`. Read content via `inject('pageContent')`, use `<style scoped>` with `var(--brand-*)` tokens. |
+| Add a component intended to be reused on other sites | The local extension at `extensions/<slug>/`. Add `components/Foo.vue`, register it in `extension.config.json`, and add a dynamic import to `index.js`. Eventually publishable as `@koehler8/cms-ext-<slug>`. |
+| Customize colors, typography, surfaces | `themes/<slug>/theme.config.js`. The CMS regenerates `virtual:cms-theme-vars.css` from the manifest on next build; CMS components consume the vars via `var(--brand-*)`. |
+| Activate a theme | Set `"theme": "<slug>"` in `site/content/{baseLocale}/site.json`. |
+| Add a new page | Create `site/content/{locale}/pages/{pageId}.json` with a `path` and `components[]` array. vite-ssg pre-renders one HTML file per page automatically. |
+| Add a new locale | Create `site/content/{locale}/...` mirroring the base locale's structure. Auto-discovered. |
+| Add a new theme to the project | `npx cms-create-theme <slug>` (scaffolds `themes/<slug>/`, then follow the printed next-steps). |
+| Add a new local extension | `npx cms-create-extension <slug>`. |
+
+If you find yourself writing a component that conceptually belongs in a "regions" or "agents" or "podcasts" sister site, **promote it from `site/components/` into `extensions/<slug>/`** so it can eventually become a published shared package.
+
+## Stack at a glance
+
+- `@koehler8/cms` ^1.0.0-beta.15+ — Vue 3 + vite-ssg framework
+- `@koehler8/cms-ext-compliance` — cookie banner / legal pages (registered by default)
+- `[site/components/](site/components/)` — auto-globbed Vue files for one-off custom UI specific to this site. **The default home for new components.**
+- `[themes/](themes/)`, `[extensions/](extensions/)` — currently empty. Add via the `cms-create-{theme,extension}` CLIs above.
+
+## File layout
+
+```
+site/content/{locale}/        per-locale content (auto-discovered)
+  site.json                   site title, description, theme key, support email
+  shared.json                 cross-page settings — header logo / nav, footer flags
+  pages/{pageId}.json         per-page components[] + content.{configKey}.* keys
+  pages/home.json             home page (the only page in a freshly scaffolded site)
+site/components/              auto-globbed Vue files (the default home for one-off
+                              custom UI). Reference by basename in components[].
+site/assets/img/              site-specific images / icons
+site/style.css                non-critical site overrides (loaded async by the CMS;
+                              fine for things that wouldn't cause a visible flash)
+site/favicon.ico              optional override; `cms-generate-public-assets`
+                              picks it up over the auto-generated letter-favicon
+themes/<slug>/                site-local CMS theme — destined to lift into a
+                              standalone @koehler8/cms-theme-<slug> repo
+extensions/<slug>/            site-local CMS extension — destined to lift into a
+                              standalone @koehler8/cms-ext-<slug> repo
+```
+
+## Common tasks (quick recipes)
+
+### Edit hero / footer copy
+Open `site/content/{baseLocale}/pages/home.json`. Hero text lives under `content.promo.*`; footer text under `content.footer.*` (or whatever configKey the components use). Push and the deploy pipeline picks it up.
+
+### Edit nav links
+`site/content/{baseLocale}/shared.json` → `content.header.navItems[N]`. Each entry is `{ text, href, target? }`. Add `"target": "_blank"` for off-site links.
+
+### Add a custom component
+1. Create `site/components/Foo.vue`.
+2. `inject('pageContent')` for content; `<style scoped>` with `var(--brand-*)` tokens.
+3. Reference as `"Foo"` in any page's `components[]`.
+
+### Add a new page
+1. Create `site/content/{baseLocale}/pages/{pageId}.json` with a `path` (e.g. `/about`) and `components[]`.
+2. Add a `navItems` entry pointing at the new path in `shared.json` if it should be in the nav.
+3. Push — vite-ssg generates `dist/{path}/index.html` automatically.
+
+### Change colors / typography
+Edit `themes/<slug>/theme.config.js`. The CMS regenerates `virtual:cms-theme-vars.css` from the manifest on next build; CMS components and your custom components consume the vars via `var(--brand-*)`, so the change cascades.
+
+## Lockfile and npm version — read before bumping any dep
+
+This project pins **Node 20.19 / npm 10.8** to match AWS Amplify exactly. Local installs with a different npm version produce subtly different lockfiles that look fine locally but break CI.
+
+Two failure modes seen on sister sites:
+1. `Cannot find module '@rolldown/binding-linux-x64-gnu'` — npm 11 regen stripped optional-dep entries Amplify needs.
+2. `npm ci ... Missing: @types/react@..., @noble/hashes@... from lock file` — npm 11 omitted entries npm 10 expects.
+
+Rules:
+- **Always run `nvm use` before `npm install`**. `.nvmrc` pins 20.19.0 (which ships npm 10.8.x).
+- **Prefer targeted bumps**: `npm install <pkg>@<ver> --no-audit --no-fund`. **Never** `rm package-lock.json && npm install` unless you're on the pinned npm version.
+- **The build uses `npm install`**, not `npm ci` (see `amplify.yml`) for drift tolerance.
+
+## Local dev
+
+```bash
+nvm use
+cp .env.example .env       # placeholder values; not used by default
+npm install
+npm run dev                # Vite dev server on http://localhost:5173
+```
+
+Build:
+
+```bash
+npm run generate:public-assets   # generates favicon/og-image from site.json
+npm run build:ssg                # pre-renders dist/{locale}/{page}/index.html
+```
+
+## Deploy
+
+Pushes to `main` trigger an automatic AWS Amplify build per `amplify.yml`. Set up the Amplify app + custom domain via the AWS console (or `aws amplify create-app` + `create-domain-association`) — see the existing sister sites' setup notes if available, or the koehler8 site repos as reference.

package/templates/scaffolds/site/README.md

@@ -0,0 +1,25 @@
+# site-__SLUG__
+
+A site built on [`@koehler8/cms`](https://github.com/koehler8/cms).
+
+For architecture, conventions, and a navigation guide for "where things go" (content, components, themes, extensions), read **[CLAUDE.md](CLAUDE.md)**.
+
+## Local development
+
+```bash
+nvm use                    # Node 20.19.0 per .nvmrc
+cp .env.example .env
+npm install
+npm run dev
+```
+
+## Build
+
+```bash
+npm run generate:public-assets
+npm run build:ssg
+```
+
+## Deployment
+
+Pushes to `main` trigger an automatic AWS Amplify build (see [amplify.yml](amplify.yml)).

package/templates/scaffolds/site/amplify.yml

@@ -0,0 +1,22 @@
+version: 1
+frontend:
+  phases:
+    preBuild:
+      commands:
+        - nvm install 20.19.0 && nvm use 20.19.0
+        # Use `npm install` (not `npm ci`) so the build tolerates
+        # lockfile/npm-version drift. See CLAUDE.md → "Lockfile and
+        # npm version" for the rationale.
+        - npm install --prefer-offline --no-audit --no-fund
+        - npm run generate:public-assets
+    build:
+      commands:
+        - npm run build:ssg
+  artifacts:
+    baseDirectory: dist
+    files:
+      - '**/*'
+  cache:
+    paths:
+      - node_modules/**/*
+      - .npm/**/*

package/templates/scaffolds/site/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@koehler8/site-__SLUG__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:ssg": "vite-ssg build",
+    "preview": "vite preview",
+    "generate:public-assets": "cms-generate-public-assets --site-dir ./site"
+  },
+  "dependencies": {
+    "@koehler8/cms": "^1.0.0-beta.15",
+    "@koehler8/cms-ext-compliance": "^1.0.0-beta.4",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "vite": "^8.0.3",
+    "vite-ssg": "^28.2.2",
+    "vue": "^3.5.22",
+    "vue-router": "^5.0.4"
+  },
+  "engines": {
+    "node": ">=20.19.0",
+    "npm": "^10.8.0"
+  }
+}

package/templates/scaffolds/site/site/content/content.config.json

@@ -0,0 +1,3 @@
+{
+  "baseLocale": "en"
+}

package/templates/scaffolds/site/site/content/en/pages/home.json

@@ -0,0 +1,8 @@
+{
+  "components[0]": "Header",
+  "components[1]": "Hero",
+  "components[2]": "Footer",
+  "content.promo.mainText": "__DISPLAY_NAME__",
+  "content.promo.tagLine": "Welcome",
+  "path": "/"
+}

package/templates/scaffolds/site/site/content/en/shared.json

@@ -0,0 +1,5 @@
+{
+  "content.header.logoText": "__DISPLAY_NAME__",
+  "content.header.showLocaleLinks": false,
+  "content.header.showWallet": false
+}

package/templates/scaffolds/site/site/content/en/site.json

@@ -0,0 +1,7 @@
+{
+  "description": "",
+  "googleId": "",
+  "supportEmail": "",
+  "title": "__DISPLAY_NAME__",
+  "url": ""
+}

package/templates/scaffolds/site/site/style.css

@@ -0,0 +1,4 @@
+/* Site-specific style overrides. Loaded async by the CMS bootstrap, so
+ * fine for things that wouldn't cause a visible flash if they applied
+ * a few hundred ms late. For critical-path styles (above-the-fold,
+ * hide-this-default), see CLAUDE.md → Styles. */

package/templates/scaffolds/site/vite.config.js

@@ -0,0 +1,15 @@
+import cms from '@koehler8/cms/vite';
+
+export default {
+  plugins: cms({
+    siteDir: './site',
+    // Add local themes (created via `npx cms-create-theme <slug>`) here:
+    //   themes: ['cms-theme-<slug>'],
+    // Then activate by setting `"theme": "<slug>"` in site.json.
+    extensions: [
+      '@koehler8/cms-ext-compliance',
+      // Add local extensions (created via `npx cms-create-extension <slug>`) here:
+      //   'cms-ext-<slug>',
+    ],
+  }),
+};