@lad-sapienza/scms-core 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -29,9 +29,9 @@ export default defineConfig({
   integrations: [
     ...scms({
       // all optional, default to the paths below
-      contentDir: 'usr/content',
-      pagesDir: 'usr/pages',
-      galleriesDir: 'usr/galleries',
+      contentDir: 'src/content',
+      pagesDir: 'src/pages',
+      galleriesDir: 'src/galleries',
     }),
   ],
 });
@@ -51,6 +51,7 @@ import { DataTb, Map, Gallery } from '@lad-sapienza/scms-core';
 | `MapComponent` (`Map`) | Interactive map with MapLibre GL JS |
 | `Gallery` | Responsive image gallery with lightbox |
 | `TableOfContents` | Auto-generated TOC from headings |
+| `RedirectPage` | Static client-side redirect stub (meta-refresh + JS fallback) for static hosts |
 | `ZoteroGeoViewer` | Zotero library visualised on a map |
 | `RecordProvider`, `Field`, `Image`, `RecordFetcher`, `useRecordFetcher` | Build single-record detail pages against Directus |
 | `SearchUI`, `SearchUISimple`, `SearchUIAdvanced` | Field/operator/value search UI (used by `Map`'s `searchInFields`) |
@@ -63,18 +64,30 @@ import BSNavbar from '@lad-sapienza/scms-core/components/BSNavbar';
 import { directusLoader } from '@lad-sapienza/scms-core/integrations/directusLoader';
 ```
 
-See each component folder's own `README.md` (`components/DataTb`, `components/Gallery`, `components/ZoteroGeoViewer`, `components/`) for detailed API docs and examples.
+See each component folder's own `README.md` (`components/DataTb`, `components/Gallery`, `components/Map`, `components/RedirectPage`, `components/ZoteroGeoViewer`, `components/`) for detailed API docs and examples.
+
+## Creating a new site
+
+```bash
+npx --package=@lad-sapienza/scms-core scms-create my-site
+cd my-site
+npm run dev
+```
+
+Prompts for a title, description, author, and site URL, then scaffolds a minimal, ready-to-run Astro + s:CMS project (`src/content.config.ts`, `src/pages/index.astro`, `astro.config.mjs`, etc.) and runs `npm install`.
 
 ## Scaffolding CLI
 
-This package also ships the interactive scaffolding tools sCMS sites use to add content, as `bin` commands — run from the consuming site's project root:
+This package also ships the interactive scaffolding tools s:CMS sites use to add content, as `bin` commands — run from the consuming site's project root:
 
 ```bash
-npx scms-add-collection   # scaffold a new Astro content collection under usr/
+npx scms-add-collection   # scaffold a new Astro content collection under src/
 npx scms-add-content      # add a new content file to an existing collection
 ```
 
-A consuming site typically wires these up as `npm run add-collection` / `npm run add-content` in its own `package.json`.
+A consuming site typically wires these up as `npm run add-collection` / `npm run add-content` in its own `package.json` (this is what `scms-create` sets up automatically).
+
+Both commands are multilingual-aware. `scms-add-collection` optionally takes a list of locale codes and scaffolds one sample per `src/content/<name>/<locale>/` folder; `scms-add-content` detects those language folders (every sub-folder is a locale code, nothing loose at the collection root) and asks which language the new file belongs in — a single locale, a comma-separated subset, or `all`.
 
 ## Development
 

package/bin/add-collection.mjs

@@ -11,7 +11,7 @@ import { join, relative } from 'node:path';
 // own location says nothing about the consuming site's layout. ROOT_DIR must
 // be the invoking project's root, i.e. wherever the CLI was run from.
 const ROOT_DIR    = process.cwd();
-const CONFIG_FILE = join(ROOT_DIR, 'usr', 'content.config.ts');
+const CONFIG_FILE = join(ROOT_DIR, 'src', 'content.config.ts');
 
 // ─── Color helpers ────────────────────────────────────────────────────────────
 const G = '\x1b[32m', Y = '\x1b[33m', R = '\x1b[31m';
@@ -150,7 +150,7 @@ const entries = (await getCollection('__COL__'))
     {entries.length === 0 && (
       <p class="text-center text-muted mt-5">
         No entries yet — add Markdown files to{' '}
-        <code>usr/content/__COL__/</code> and set <code>draft: false</code>.
+        <code>src/content/__COL__/</code> and set <code>draft: false</code>.
       </p>
     )}
   </main>
@@ -207,7 +207,7 @@ const entries = (await getCollection('__COL__'))
     {entries.length === 0 && (
       <p class="text-center text-muted mt-5">
         No entries yet — add Markdown files to{' '}
-        <code>usr/content/__COL__/</code> and set <code>draft: false</code>.
+        <code>src/content/__COL__/</code> and set <code>draft: false</code>.
       </p>
     )}
   </main>
@@ -254,7 +254,7 @@ const entries = (await getCollection('__COL__'))
     {entries.length === 0 && (
       <p class="text-center text-muted mt-5">
         No entries yet — add Markdown files to{' '}
-        <code>usr/content/__COL__/</code> and set <code>draft: false</code>.
+        <code>src/content/__COL__/</code> and set <code>draft: false</code>.
       </p>
     )}
   </main>
@@ -420,10 +420,15 @@ const { Content } = await render(entry);
 
 // ─── Main ─────────────────────────────────────────────────────────────────────
 async function main() {
-  // Parse existing collections
-  const cfgSrc    = readFileSync(CONFIG_FILE, 'utf8');
-  const exportM   = cfgSrc.match(/export const collections\s*=\s*\{([^}]+)\}/s);
-  const existing  = exportM
+  // Parse existing collections. Search only from the `// Export all
+  // collections` marker onward (the real export always follows it) — a plain
+  // whole-file regex would also match doc-comment examples mentioning the
+  // same "export const collections = {...}" text earlier in the file.
+  const cfgSrc     = readFileSync(CONFIG_FILE, 'utf8');
+  const markerIdx  = cfgSrc.indexOf('// Export all collections');
+  const searchFrom = markerIdx === -1 ? cfgSrc : cfgSrc.slice(markerIdx);
+  const exportM    = searchFrom.match(/export const collections\s*=\s*\{([^}]+)\}/s);
+  const existing   = exportM
     ? [...exportM[1].matchAll(/(?:['"]([\w-]+)['"]|(\w+))\s*:/g)].map(m => m[1] ?? m[2])
     : [];
 
@@ -463,16 +468,37 @@ async function main() {
   const typeRaw = (await ask('Choose type [1/2/3] (default: 3): ')).trim() || '3';
   const colType = typeRaw === '1' ? 'blog' : typeRaw === '2' ? 'docs' : 'generic';
   ok(`Type: ${colType}`);
+
+  // ─── Prompt: language folders (multilingual collection) ──────────────────
+  // A site can organise a collection's content per language, as
+  // src/content/<col>/<locale>/… — s:CMS's i18n layer is structural, it keys
+  // off those folders existing rather than a config flag. Ask up front so the
+  // sample file(s) land in the right place. (The page templates written below
+  // are single-language starting points regardless — see the closing notes.)
+  console.log('');
+  console.log(`${B}Language folders${X} — for a multilingual collection, list the locale`);
+  console.log(`  codes to scaffold (e.g. ${B}en, it${X}). Leave blank for a single-language collection.`);
+  let locales = [];
+  while (true) {
+    const raw = (await ask('  Locale codes [blank = none]: ')).trim();
+    if (!raw) break;
+    const parsed = raw.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    const bad = parsed.filter(p => !/^[a-z]{2}(?:[-_][a-z0-9]{2,4})?$/i.test(p));
+    if (bad.length) { warn(`Not a locale code: ${bad.join(', ')} (expected e.g. en, it, pt-BR)`); continue; }
+    locales = [...new Set(parsed)];
+    break;
+  }
+  if (locales.length) ok(`Language folders: ${locales.join(', ')}`);
   rl.close();
 
-  // ─── 1. Update usr/content.config.ts ──────────────────────────────────────
+  // ─── 1. Update src/content.config.ts ──────────────────────────────────────
   const newBlock =
     `\n// Schema for ${colName} entries  [${colType} type]\n` +
     `// TODO: customize the schema fields to match your content structure\n` +
     `const ${varName} = defineCollection({\n` +
     `  loader: glob({\n` +
     `    pattern: '**/*.{md,mdx}',\n` +
-    `    base: './usr/content/${colName}',\n` +
+    `    base: './src/content/${colName}',\n` +
     `  }),\n` +
     `  schema: z.object({\n` +
     `${SCHEMA[colType]}\n` +
@@ -480,21 +506,29 @@ async function main() {
     `});\n`;
 
   const MARKER = '// Export all collections';
-  let cfg = readFileSync(CONFIG_FILE, 'utf8');
-  if (!cfg.includes(MARKER)) error(`Marker '${MARKER}' not found in config.ts`);
-
-  cfg = cfg.replace(MARKER, newBlock + MARKER);
-  cfg = cfg.replace(
-    /(export const collections\s*=\s*\{)([^}]+)(\};)/s,
+  const cfg = readFileSync(CONFIG_FILE, 'utf8');
+  const markerIndex = cfg.indexOf(MARKER);
+  if (markerIndex === -1) error(`Marker '${MARKER}' not found in config.ts`);
+
+  // Only ever scan/edit the file from the marker onward — the real `export
+  // const collections = {...}` always lives there. Scanning the whole file
+  // for that pattern is fragile: doc-comment examples earlier in the file
+  // (e.g. in the template this script ships against) can contain the exact
+  // same text, and a plain first-match regex would silently edit the
+  // comment instead of the real export.
+  const before = cfg.slice(0, markerIndex);
+  const after = (newBlock + cfg.slice(markerIndex)).replace(
+    // [^}]* (zero or more), not [^}]+ — a fresh scms-create site starts with
+    // an empty `export const collections = {};`, and `+` would fail to match it.
+    /(export const collections\s*=\s*\{)([^}]*)(\};)/s,
     (_, open, inner, close) => `${open}${inner.trimEnd()}\n  ${toObjectKey(colName)}: ${varName},\n${close}`
   );
-  writeFileSync(CONFIG_FILE, cfg, 'utf8');
-  ok('usr/content.config.ts updated');
+  writeFileSync(CONFIG_FILE, before + after, 'utf8');
+  ok('src/content.config.ts updated');
 
-  // ─── 2. Sample content file ───────────────────────────────────────────────
+  // ─── 2. Sample content file(s) ───────────────────────────────────────────
   const today      = new Date().toISOString().slice(0, 10);
-  const contentDir = join(ROOT_DIR, 'usr', 'content', colName);
-  mkdirSync(contentDir, { recursive: true });
+  const contentDir = join(ROOT_DIR, 'src', 'content', colName);
 
   const SAMPLE_NAME = { blog: 'sample-post.md', docs: 'sample-doc.md', generic: 'sample.md' };
   const SAMPLE_BODY = {
@@ -515,12 +549,19 @@ async function main() {
       `# Sample Entry\n\nThis is a sample entry. Replace this file with real content.\n`,
   };
 
-  const samplePath = join(contentDir, SAMPLE_NAME[colType]);
-  writeFileSync(samplePath, SAMPLE_BODY[colType], 'utf8');
-  ok(relative(ROOT_DIR, samplePath));
+  // One sample per language folder for a multilingual collection, otherwise a
+  // single sample in the collection root. The copies are identical starting
+  // points — translations get written by hand afterwards.
+  const sampleDirs = locales.length ? locales.map(loc => join(contentDir, loc)) : [contentDir];
+  for (const dir of sampleDirs) {
+    mkdirSync(dir, { recursive: true });
+    const samplePath = join(dir, SAMPLE_NAME[colType]);
+    writeFileSync(samplePath, SAMPLE_BODY[colType], 'utf8');
+    ok(relative(ROOT_DIR, samplePath));
+  }
 
   // ─── 3. Page templates ────────────────────────────────────────────────────
-  const pagesDir = join(ROOT_DIR, 'usr', 'pages', colName);
+  const pagesDir = join(ROOT_DIR, 'src', 'pages', colName);
   mkdirSync(pagesDir, { recursive: true });
 
   const sub       = (s) => s.replaceAll('__COL__', colName);
@@ -537,9 +578,13 @@ async function main() {
   console.log(`${G}${B}Collection '${colName}' scaffolded successfully!${X}`);
   console.log('');
   console.log(`  ${B}Next steps:${X}`);
-  console.log(`    1. Open ${B}usr/content.config.ts${X} and review the schema for '${colName}'`);
-  console.log(`    2. Edit the page files in ${B}usr/pages/${colName}/${X} to customise the UI`);
-  console.log(`    3. Replace the sample file in ${B}usr/content/${colName}/${X} with real content`);
+  console.log(`    1. Open ${B}src/content.config.ts${X} and review the schema for '${colName}'`);
+  console.log(`    2. Edit the page files in ${B}src/pages/${colName}/${X} to customise the UI`);
+  if (locales.length) {
+    console.log(`       ${Y}These render a single language — adapt them to your locale`);
+    console.log(`       routing (e.g. move them under src/pages/[locale]/${colName}/).${X}`);
+  }
+  console.log(`    3. Replace the sample file${locales.length ? 's' : ''} in ${B}src/content/${colName}/${X} with real content`);
   console.log(`    4. Run ${B}npm run dev${X} and visit ${B}/${colName}${X}`);
   console.log('');
 }

package/bin/add-content.mjs

@@ -12,8 +12,8 @@ import { execSync } from 'node:child_process';
 // own location says nothing about the consuming site's layout. ROOT_DIR must
 // be the invoking project's root, i.e. wherever the CLI was run from.
 const ROOT_DIR     = process.cwd();
-const CONFIG_FILE  = join(ROOT_DIR, 'usr', 'content.config.ts');
-const CONTENT_BASE = join(ROOT_DIR, 'usr', 'content');
+const CONFIG_FILE  = join(ROOT_DIR, 'src', 'content.config.ts');
+const CONTENT_BASE = join(ROOT_DIR, 'src', 'content');
 
 // ─── Color helpers ────────────────────────────────────────────────────────────
 const G = '\x1b[32m', Y = '\x1b[33m', R = '\x1b[31m';
@@ -43,9 +43,16 @@ const ask = async (prompt) => {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-/** Parse top-level collection keys from export const collections = { ... } */
+/**
+ * Parse top-level collection keys from export const collections = { ... }.
+ * Searches only from the `// Export all collections` marker onward (the real
+ * export always follows it) — a plain whole-file regex would also match
+ * doc-comment examples mentioning the same text earlier in the file.
+ */
 function parseCollections(src) {
-  const m = src.match(/export const collections\s*=\s*\{([^}]+)\}/s);
+  const markerIdx = src.indexOf('// Export all collections');
+  const searchFrom = markerIdx === -1 ? src : src.slice(markerIdx);
+  const m = searchFrom.match(/export const collections\s*=\s*\{([^}]+)\}/s);
   if (!m) return [];
   // Keys may be quoted (e.g. 'my-collection': ...) when the name isn't a
   // valid bare identifier — see toObjectKey() in add-collection.mjs.
@@ -68,10 +75,40 @@ function hasMdx(dir) {
   } catch { return false; }
 }
 
+/** True if any .md/.mdx file sits directly in dir (not in a sub-folder) */
+function hasRootContentFiles(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .some(d => d.isFile() && /\.mdx?$/.test(d.name));
+  } catch { return false; }
+}
+
+/**
+ * Locale-code sub-directories directly inside a collection dir — e.g.
+ * `en`, `it`, `pt-BR`. Their presence is how a site opts a collection in to
+ * per-language content: there is no config flag (s:CMS's i18n layer is
+ * structural — it keys off these folders existing). The pattern is a
+ * 2-letter base with an optional region/script suffix (`pt-BR`, `zh-Hans`),
+ * and — to keep ordinary topic folders (`api`, `guides`) from being taken
+ * for languages — this returns nothing unless *every* sub-folder matches.
+ * Sorted, for a stable prompt order.
+ */
+function detectLocaleDirs(dir) {
+  let subdirs;
+  try {
+    subdirs = readdirSync(dir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch { return []; }
+  if (subdirs.length === 0) return [];
+  const locales = subdirs.filter(n => /^[a-z]{2}(?:[-_][a-z0-9]{2,4})?$/i.test(n));
+  return locales.length === subdirs.length ? locales.sort() : [];
+}
+
 /** Extract z.object field lines for a named collection from config.ts */
 function parseSchemaFields(src, colName) {
   const pat = new RegExp(
-    `defineCollection\\(\\{.*?base\\s*:\\s*['"]\\./usr/content/${colName}['"].*?z\\.object\\(\\{(.*?)\\}\\)`,
+    `defineCollection\\(\\{.*?base\\s*:\\s*['"]\\./src/content/${colName}['"].*?z\\.object\\(\\{(.*?)\\}\\)`,
     's'
   );
   const m = src.match(pat);
@@ -156,9 +193,37 @@ async function main() {
   }
   ok(`Collection: ${collection}`);
 
+  const colDir = join(CONTENT_BASE, collection);
+
+  // ─── Prompt: language folder (multilingual collections only) ─────────────
+  // A collection counts as multilingual purely by its layout: content split
+  // into locale-named sub-folders (src/content/<col>/<locale>/…) with nothing
+  // loose at the collection root. When that's the case, ask which locale
+  // folder(s) the new file belongs in — one, a comma-separated subset, or
+  // `all`. Collections that aren't organised this way skip the step entirely
+  // and behave exactly as before.
+  const localeDirs = hasRootContentFiles(colDir) ? [] : detectLocaleDirs(colDir);
+  let targetLocales = ['']; // '' → straight into the collection root (single-language)
+  if (localeDirs.length > 0) {
+    console.log('');
+    console.log(`  This collection is organised by language folder: ${B}${localeDirs.join(', ')}${X}`);
+    console.log('  Enter one language, a comma-separated list, or "all".');
+    console.log('');
+    while (true) {
+      const raw = (await ask(`${B}Language${X} [${[...localeDirs, 'all'].join(' / ')}]: `)).trim().toLowerCase();
+      if (!raw) { warn('Please choose a language (or "all").'); continue; }
+      if (raw === 'all') { targetLocales = [...localeDirs]; break; }
+      const picked  = raw.split(',').map(s => s.trim()).filter(Boolean);
+      const unknown = picked.filter(p => !localeDirs.includes(p));
+      if (unknown.length) { warn(`Not an available language: ${unknown.join(', ')}`); continue; }
+      targetLocales = [...new Set(picked)];
+      break;
+    }
+    ok(`Language: ${targetLocales.join(', ')}`);
+  }
+
   // ─── Prompt: file format ─────────────────────────────────────────────────
-  const colDir     = join(CONTENT_BASE, collection);
-  const defaultExt = hasMdx(colDir) ? 'mdx' : 'md';
+  const defaultExt = targetLocales.some(loc => hasMdx(join(colDir, loc))) ? 'mdx' : 'md';
   console.log('');
   const extRaw = (await ask(`${B}File format${X} [md/mdx] (default: ${defaultExt}): `)).trim() || defaultExt;
   const ext    = (extRaw === 'md' || extRaw === 'mdx') ? extRaw : defaultExt;
@@ -176,8 +241,9 @@ async function main() {
       warn('Slug must contain only lowercase letters, numbers, hyphens, underscores, and forward slashes.');
       continue;
     }
-    if (existsSync(join(colDir, raw, `index.${ext}`))) {
-      warn(`File already exists: usr/content/${collection}/${raw}/index.${ext}`);
+    const clash = targetLocales.find(loc => existsSync(join(colDir, loc, raw, `index.${ext}`)));
+    if (clash !== undefined) {
+      warn(`File already exists: ${relative(ROOT_DIR, join(colDir, clash, raw, `index.${ext}`))}`);
       continue;
     }
     slug = raw;
@@ -227,11 +293,7 @@ async function main() {
 
   rl.close();
 
-  // ─── Write file ───────────────────────────────────────────────────────────
-  const targetDir  = join(colDir, slug);
-  const targetPath = join(targetDir, `index.${ext}`);
-  mkdirSync(targetDir, { recursive: true });
-
+  // ─── Write file(s) ────────────────────────────────────────────────────────
   const content = [
     '---',
     ...fmLines,
@@ -243,19 +305,39 @@ async function main() {
     '',
   ].join('\n');
 
-  writeFileSync(targetPath, content, 'utf8');
+  // One copy per chosen language folder (just one entry, '', for a
+  // single-language collection). Each copy is an identical starting point —
+  // the per-locale translations are written afterwards, by hand.
+  const created = [];
+  for (const loc of targetLocales) {
+    const targetDir  = join(colDir, loc, slug);
+    const targetPath = join(targetDir, `index.${ext}`);
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(targetPath, content, 'utf8');
+    created.push(relative(ROOT_DIR, targetPath));
+  }
 
   console.log('');
-  ok(`Created: ${relative(ROOT_DIR, targetPath)}`);
+  for (const p of created) ok(`Created: ${p}`);
 
   // ─── Summary ──────────────────────────────────────────────────────────────
+  const multilingual = targetLocales.some(Boolean);
   console.log('');
   console.log(`${G}${B}Done!${X}`);
   console.log('');
   console.log(`  ${B}Next steps:${X}`);
-  console.log(`    1. Open ${B}usr/content/${collection}/${slug}/index.${ext}${X} and write your content`);
+  if (multilingual) {
+    console.log(`    1. Open the new file${created.length > 1 ? 's' : ''} and write ${created.length > 1 ? 'each translation' : 'your content'}:`);
+    for (const p of created) console.log(`         ${B}${p}${X}`);
+  } else {
+    console.log(`    1. Open ${B}${created[0]}${X} and write your content`);
+  }
   console.log(`    2. Set ${B}draft: false${X} when the content is ready to publish`);
-  console.log(`    3. Run ${B}npm run dev${X} and visit ${B}/${collection}/${slug}${X}`);
+  if (multilingual) {
+    console.log(`    3. Run ${B}npm run dev${X} and visit the new page (e.g. ${B}/${targetLocales[0]}/${collection}/${slug}${X}, depending on your locale routing)`);
+  } else {
+    console.log(`    3. Run ${B}npm run dev${X} and visit ${B}/${collection}/${slug}${X}`);
+  }
   console.log('');
 }
 

package/bin/create.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// create.mjs — Guided scaffold of a new s:CMS site.
+// Usage: npx --package=@lad-sapienza/scms-core scms-create [directory]
+
+import { createInterface } from 'node:readline';
+import {
+  existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync,
+} from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, execSync } from 'node:child_process';
+
+const __dirname     = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT   = join(__dirname, '..');
+const TEMPLATE_DIR   = join(PACKAGE_ROOT, 'template');
+const OWN_PACKAGE     = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+
+// ─── Color helpers ────────────────────────────────────────────────────────────
+const G = '\x1b[32m', Y = '\x1b[33m', R = '\x1b[31m';
+const B = '\x1b[1m',  X = '\x1b[0m';
+const ok    = (...a) => console.log(`${G}✔${X}  ${a.join(' ')}`);
+const warn  = (...a) => console.log(`${Y}⚠${X}  ${a.join(' ')}`);
+const error = (...a) => { console.error(`${R}✖${X}  ${a.join(' ')}`); process.exit(1); };
+
+// ─── Readline helper ──────────────────────────────────────────────────────────
+// Same async-iterator pattern as add-collection.mjs / add-content.mjs — avoids
+// the readline hang on piped/pasted (non-TTY) input those scripts already fixed.
+const rl  = createInterface({ input: process.stdin, output: process.stdout });
+rl.on('SIGINT', () => { console.log(''); process.exit(0); });
+const rlIterator = rl[Symbol.asyncIterator]();
+const ask = async (prompt) => {
+  process.stdout.write(prompt);
+  const { value, done } = await rlIterator.next();
+  if (done) { console.log(''); process.exit(0); }
+  return value;
+};
+
+/** Strip a leading semver range operator (^, ~, >=, etc.) to get a bare version. */
+const bareVersion = (range) => range.replace(/^[^\d]*/, '');
+
+/** Recursively copy `template/`, substituting placeholders and stripping .tmpl suffixes. */
+function copyTemplate(srcDir, destDir, replacements) {
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = join(srcDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTemplate(srcPath, join(destDir, entry.name), replacements);
+      continue;
+    }
+    const isTemplate = entry.name.endsWith('.tmpl');
+    const destName = isTemplate ? entry.name.slice(0, -'.tmpl'.length) : entry.name;
+    const destPath = join(destDir, destName);
+    let content = readFileSync(srcPath, 'utf8');
+    if (isTemplate) {
+      for (const [placeholder, value] of Object.entries(replacements)) {
+        content = content.replaceAll(placeholder, value);
+      }
+    }
+    writeFileSync(destPath, content, 'utf8');
+  }
+}
+
+async function main() {
+  console.log('');
+  console.log(`${B}Create a new s:CMS site${X}`);
+  console.log('');
+
+  // ─── Prompt: target directory ────────────────────────────────────────────
+  const argDir = process.argv[2];
+  let targetDir;
+  if (argDir) {
+    targetDir = argDir;
+  } else {
+    while (true) {
+      const raw = (await ask(`${B}Directory${X} (will be created): `)).trim();
+      if (!raw) { warn('Please enter a directory name.'); continue; }
+      targetDir = raw;
+      break;
+    }
+  }
+  const targetPath = join(process.cwd(), targetDir);
+  if (existsSync(targetPath) && readdirSync(targetPath).length > 0) {
+    error(`${targetDir}/ already exists and is not empty.`);
+  }
+
+  // ─── Prompt: site info ────────────────────────────────────────────────────
+  const dirBasedTitle = targetDir.split('/').pop().replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  const title = (await ask(`${B}Site title${X} [${dirBasedTitle}]: `)).trim() || dirBasedTitle;
+
+  const description = (await ask(`${B}Description${X}: `)).trim() || `A site built with s:CMS.`;
+
+  let gitAuthor = '';
+  try {
+    gitAuthor = execSync('git config user.name', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { /* git not available or no config */ }
+  const author = (await ask(`${B}Author${X}${gitAuthor ? ` [${gitAuthor}]` : ''}: `)).trim() || gitAuthor;
+
+  const siteUrl = (await ask(`${B}Site URL${X} (for sitemap/canonical URLs, e.g. https://example.com): `)).trim();
+
+  const installNow = (await ask(`${B}Run npm install now?${X} [Y/n]: `)).trim().toLowerCase() !== 'n';
+
+  rl.close();
+
+  // ─── Copy + customize the template ────────────────────────────────────────
+  const npmPackageName = targetDir.split('/').pop().toLowerCase().replace(/[^a-z0-9-]/g, '-');
+  const peers = OWN_PACKAGE.peerDependencies || {};
+
+  const replacements = {
+    __NAME__: npmPackageName,
+    __TITLE__: title,
+    __DESCRIPTION__: description,
+    __AUTHOR__: author,
+    __SITE_URL__: siteUrl,
+    __SCMS_VERSION__: OWN_PACKAGE.version,
+    __ASTRO_VERSION__: bareVersion(peers.astro ?? '7.0.0'),
+    __REACT_VERSION__: bareVersion(peers.react ?? '19.0.0'),
+    __REACT_DOM_VERSION__: bareVersion(peers['react-dom'] ?? '19.0.0'),
+    __MAPLIBRE_VERSION__: bareVersion(peers['maplibre-gl'] ?? '5.0.0'),
+    __TYPES_REACT_VERSION__: bareVersion(peers['@types/react'] ?? '19.0.0'),
+    __TYPES_REACT_DOM_VERSION__: bareVersion(peers['@types/react-dom'] ?? '19.0.0'),
+  };
+
+  copyTemplate(TEMPLATE_DIR, targetPath, replacements);
+  ok(`Created ${relative(process.cwd(), targetPath) || '.'}/`);
+
+  // ─── Install ───────────────────────────────────────────────────────────────
+  if (installNow) {
+    console.log('');
+    console.log(`${B}Installing dependencies...${X}`);
+    const result = spawnSync('npm', ['install'], { cwd: targetPath, stdio: 'inherit' });
+    if (result.status !== 0) {
+      warn('npm install failed — run it yourself once you\'ve reviewed the error above.');
+    } else {
+      ok('Dependencies installed');
+    }
+  }
+
+  // ─── Summary ──────────────────────────────────────────────────────────────
+  console.log('');
+  console.log(`${G}${B}Site scaffolded successfully!${X}`);
+  console.log('');
+  console.log(`  ${B}Next steps:${X}`);
+  console.log(`    1. cd ${targetDir}`);
+  if (!installNow) console.log(`    2. npm install`);
+  console.log(`    ${installNow ? 2 : 3}. npm run dev`);
+  console.log('');
+}
+
+main().catch((err) => error(String(err)));