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

package/README.md

@@ -18,15 +18,20 @@ Register the integration in `astro.config.mjs`:
 
 ```js
 import { defineConfig } from 'astro/config';
-import { scms } from '@lad-sapienza/scms-core';
+// Import from the `/scms` subpath, not the bare `@lad-sapienza/scms-core`
+// specifier — the bare specifier resolves to index.ts, which re-exports
+// .astro components (Gallery, TableOfContents). Astro can't compile .astro
+// files yet at config-load time, before its own Vite plugin is registered,
+// so a bare import here breaks with a Vite parse error.
+import { scms } from '@lad-sapienza/scms-core/scms';
 
 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',
     }),
   ],
 });
@@ -46,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`) |
@@ -58,7 +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 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 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` (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

@@ -0,0 +1,592 @@
+#!/usr/bin/env node
+// add-collection.mjs — Scaffold a new Astro content collection in s:CMS
+// Usage: npx scms-add-collection
+//    or: npm run add-collection (from a consuming site's package.json)
+
+import { createInterface } from 'node:readline';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+// This file ships inside the @lad-sapienza/scms-core package (bin/), so its
+// 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, 'src', 'content.config.ts');
+
+// ─── 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); };
+
+if (!existsSync(CONFIG_FILE)) error(`Cannot find ${CONFIG_FILE} — are you running from the project root?`);
+
+// ─── Object key helper ─────────────────────────────────────────────────────
+// Collection names may contain hyphens (the prompt below explicitly allows
+// them), which aren't valid in a bare JS/TS object-key identifier — e.g.
+// `my-collection: fooCollection` is a syntax error (parsed as subtraction).
+// Quote the key whenever it isn't a valid identifier on its own.
+const toObjectKey = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`;
+
+// ─── Readline helper ──────────────────────────────────────────────────────────
+// Uses the readline interface as an async iterator rather than repeated
+// rl.question() calls: with piped/pasted (non-TTY) input, multiple lines can
+// arrive in a single chunk, and question()'s one-shot 'line' listener isn't
+// registered in time to catch answers past the first — they're silently
+// dropped and the prompt hangs forever with no error. Iterating the interface
+// consumes lines through its internal queue instead, so it doesn't race.
+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;
+};
+
+// ─── Schema fields per collection type ───────────────────────────────────────
+const SCHEMA = {
+  blog: [
+    '    title: z.string(),',
+    '    description: z.string(),',
+    '    date: z.coerce.date(),',
+    '    author: z.string().optional(),',
+    '    tags: z.array(z.string()).optional(),',
+    '    image: z.string().optional(),',
+    '    draft: z.boolean().optional(),',
+  ].join('\n'),
+  docs: [
+    '    title: z.string(),',
+    '    description: z.string().optional(),',
+    '    order: z.number().optional(),',
+    '    category: z.string().optional(),',
+    '    draft: z.boolean().optional(),',
+  ].join('\n'),
+  generic: [
+    '    title: z.string(),',
+    '    description: z.string().optional(),',
+    '    draft: z.boolean().optional(),',
+  ].join('\n'),
+};
+
+// ─── Page templates ───────────────────────────────────────────────────────────
+// __COL__ is substituted with the collection name after the template is defined.
+// Inside templates: \` → ` and \${ → ${ so JS doesn't interpolate them.
+// \\ → \ in the output (needed for JS regex /\.mdx?$/ inside Astro files).
+
+const INDEX = {
+
+  blog: `---
+import { getCollection } from 'astro:content';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+
+export const prerender = true;
+
+// TODO: customise title and description below
+const title = '__COL__';
+const description = 'All entries in the __COL__ collection';
+
+const entries = (await getCollection('__COL__'))
+  .filter(e => !e.data.draft)
+  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
+---
+
+<BaseLayout title={title} description={description}>
+  <main class="container py-5">
+    <div class="mb-5">
+      <h1 class="mb-0">{title}</h1>
+      <p class="lead">{description}</p>
+    </div>
+
+    <div class="row g-4">
+      {entries.map(entry => (
+        <div class="col-12 col-md-6 col-lg-4">
+          <article class="card h-100 shadow-sm">
+            {entry.data.image && (
+              <img
+                src={entry.data.image}
+                alt={entry.data.title}
+                class="card-img-top"
+                style="height:200px;object-fit:cover;"
+              />
+            )}
+            <div class="card-body d-flex flex-column">
+              <h5 class="card-title">
+                <a
+                  href={\`/__COL__/\${entry.id.replace(/\\.mdx?$/, '')}\`}
+                  class="text-decoration-none text-dark"
+                >
+                  {entry.data.title}
+                </a>
+              </h5>
+              <p class="card-text text-muted small flex-grow-1">
+                {entry.data.description}
+              </p>
+              {entry.data.tags && (
+                <div class="d-flex flex-wrap gap-1 mt-2">
+                  {entry.data.tags.map(tag => (
+                    <span class="badge bg-primary-subtle text-primary-emphasis">
+                      {tag}
+                    </span>
+                  ))}
+                </div>
+              )}
+            </div>
+            <div class="card-footer text-muted small">
+              <time datetime={entry.data.date.toISOString()}>
+                {entry.data.date.toLocaleDateString('en-US', {
+                  year: 'numeric', month: 'long', day: 'numeric',
+                })}
+              </time>
+              {entry.data.author && <span> · {entry.data.author}</span>}
+            </div>
+          </article>
+        </div>
+      ))}
+    </div>
+
+    {entries.length === 0 && (
+      <p class="text-center text-muted mt-5">
+        No entries yet — add Markdown files to{' '}
+        <code>src/content/__COL__/</code> and set <code>draft: false</code>.
+      </p>
+    )}
+  </main>
+</BaseLayout>
+`,
+
+  docs: `---
+import { getCollection, type CollectionEntry } from 'astro:content';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+
+export const prerender = true;
+
+// TODO: customise title, description, and category groupings below
+const title = '__COL__';
+const description = 'Documentation for __COL__';
+
+type Entry = CollectionEntry<'__COL__'>;
+
+const entries = (await getCollection('__COL__'))
+  .filter((e: Entry) => !e.data.draft)
+  .sort((a: Entry, b: Entry) => (a.data.order ?? 999) - (b.data.order ?? 999));
+---
+
+<BaseLayout title={title} description={description}>
+  <main class="container py-5">
+    <div class="mb-5">
+      <h1 class="mb-0">{title}</h1>
+      <p class="lead text-secondary">{description}</p>
+    </div>
+
+    <div class="row g-3">
+      {entries.map(entry => (
+        <div class="col-12 col-md-6">
+          <a
+            href={\`/__COL__/\${entry.id.replace(/\\.mdx?$/, '')}\`}
+            class="card p-4 h-100 text-decoration-none border shadow-sm d-block"
+          >
+            <h3 class="h5 fw-semibold text-body mb-2 mt-0">
+              {entry.data.title}
+            </h3>
+            {entry.data.description && (
+              <p class="text-secondary mb-0 small">{entry.data.description}</p>
+            )}
+            {entry.data.category && (
+              <span class="badge bg-secondary-subtle text-secondary-emphasis mt-2">
+                {entry.data.category}
+              </span>
+            )}
+          </a>
+        </div>
+      ))}
+    </div>
+
+    {entries.length === 0 && (
+      <p class="text-center text-muted mt-5">
+        No entries yet — add Markdown files to{' '}
+        <code>src/content/__COL__/</code> and set <code>draft: false</code>.
+      </p>
+    )}
+  </main>
+</BaseLayout>
+`,
+
+  generic: `---
+import { getCollection } from 'astro:content';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+
+export const prerender = true;
+
+// TODO: customise title and description below
+const title = '__COL__';
+const description = 'All entries in the __COL__ collection';
+
+const entries = (await getCollection('__COL__'))
+  .filter(e => !e.data.draft);
+---
+
+<BaseLayout title={title} description={description}>
+  <main class="container py-5">
+    <div class="mb-5">
+      <h1 class="mb-0">{title}</h1>
+      <p class="lead">{description}</p>
+    </div>
+
+    <ul class="list-group list-group-flush">
+      {entries.map(entry => (
+        <li class="list-group-item">
+          <a
+            href={\`/__COL__/\${entry.id.replace(/\\.mdx?$/, '')}\`}
+            class="text-decoration-none fw-semibold"
+          >
+            {entry.data.title}
+          </a>
+          {entry.data.description && (
+            <p class="mb-0 text-muted small">{entry.data.description}</p>
+          )}
+        </li>
+      ))}
+    </ul>
+
+    {entries.length === 0 && (
+      <p class="text-center text-muted mt-5">
+        No entries yet — add Markdown files to{' '}
+        <code>src/content/__COL__/</code> and set <code>draft: false</code>.
+      </p>
+    )}
+  </main>
+</BaseLayout>
+`,
+};
+
+const SLUG = {
+
+  blog: `---
+import { getCollection, render } from 'astro:content';
+import { type CollectionEntry } from 'astro:content';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+
+export const prerender = true;
+
+export async function getStaticPaths() {
+  const entries = await getCollection('__COL__');
+  return entries.map(entry => ({
+    params: { slug: entry.id.replace(/\\.mdx?$/, '') },
+    props:  { entry },
+  }));
+}
+
+interface Props { entry: CollectionEntry<'__COL__'>; }
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+
+const formattedDate = entry.data.date.toLocaleDateString('en-US', {
+  year: 'numeric', month: 'long', day: 'numeric',
+});
+---
+
+<BaseLayout title={entry.data.title} description={entry.data.description}>
+  <main class="container py-5">
+    <article>
+      <div class="mb-4 text-end">
+        <a href="/__COL__" class="btn btn-outline-secondary btn-sm">
+          ← Back to __COL__
+        </a>
+      </div>
+
+      <h1 class="mb-3">{entry.data.title}</h1>
+      <p class="lead text-muted mb-4">{entry.data.description}</p>
+
+      <div class="d-flex flex-wrap align-items-center gap-3 small text-muted mb-4 pb-4 border-bottom">
+        <time datetime={entry.data.date.toISOString()}>{formattedDate}</time>
+        {entry.data.author && <span>· By {entry.data.author}</span>}
+        {entry.data.tags && entry.data.tags.map(tag => (
+          <span class="badge bg-primary-subtle text-primary-emphasis">{tag}</span>
+        ))}
+      </div>
+
+      {entry.data.image && (
+        <img
+          src={entry.data.image}
+          alt={entry.data.title}
+          class="img-fluid rounded mb-5 w-100"
+          style="max-height:400px;object-fit:cover;"
+        />
+      )}
+
+      <div class="markdown-content">
+        <Content />
+      </div>
+    </article>
+  </main>
+</BaseLayout>
+`,
+
+  docs: `---
+import { getCollection, render } from 'astro:content';
+import { type CollectionEntry } from 'astro:content';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+
+export const prerender = true;
+
+export async function getStaticPaths() {
+  const entries = await getCollection('__COL__');
+  return entries.map(entry => ({
+    params: { slug: entry.id.replace(/\\.mdx?$/, '') },
+    props:  { entry },
+  }));
+}
+
+interface Props { entry: CollectionEntry<'__COL__'>; }
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+<BaseLayout title={entry.data.title} description={entry.data.description}>
+  <main class="container py-4">
+    <article>
+      <div class="mb-4 text-end">
+        <a href="/__COL__" class="small btn btn-outline-secondary btn-sm">
+          ← Back to __COL__
+        </a>
+      </div>
+
+      <h1 class="mb-2">{entry.data.title}</h1>
+      {entry.data.description && (
+        <p class="lead text-muted mb-4">{entry.data.description}</p>
+      )}
+      {entry.data.category && (
+        <span class="badge bg-secondary-subtle text-secondary-emphasis mb-4 d-inline-block">
+          {entry.data.category}
+        </span>
+      )}
+
+      <div class="markdown-content mt-4">
+        <Content />
+      </div>
+    </article>
+  </main>
+</BaseLayout>
+`,
+
+  generic: `---
+import { getCollection, render } from 'astro:content';
+import { type CollectionEntry } from 'astro:content';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+
+export const prerender = true;
+
+export async function getStaticPaths() {
+  const entries = await getCollection('__COL__');
+  return entries.map(entry => ({
+    params: { slug: entry.id.replace(/\\.mdx?$/, '') },
+    props:  { entry },
+  }));
+}
+
+interface Props { entry: CollectionEntry<'__COL__'>; }
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+<BaseLayout title={entry.data.title} description={entry.data.description}>
+  <main class="container py-5">
+    <article>
+      <div class="mb-4 text-end">
+        <a href="/__COL__" class="btn btn-outline-secondary btn-sm">
+          ← Back to __COL__
+        </a>
+      </div>
+
+      <h1 class="mb-3">{entry.data.title}</h1>
+      {entry.data.description && (
+        <p class="lead text-muted mb-4">{entry.data.description}</p>
+      )}
+
+      <div class="markdown-content mt-4">
+        <Content />
+      </div>
+    </article>
+  </main>
+</BaseLayout>
+`,
+};
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  // 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])
+    : [];
+
+  console.log('');
+  console.log(`${B}Existing collections:${X}`);
+  if (existing.length === 0) console.log('  (none)');
+  else for (const c of existing) console.log(`  • ${c}`);
+  console.log('');
+
+  // ─── Prompt: collection name ────────────────────────────────────────────────
+  let colName;
+  while (true) {
+    const raw = (await ask(`${B}New collection name${X} (lowercase letters, numbers, hyphens): `)).replace(/\s/g, '');
+    if (!/^[a-z]([a-z0-9-]*[a-z0-9])?$/.test(raw)) {
+      warn('Name must start with a letter and contain only lowercase letters, numbers, and hyphens.');
+      continue;
+    }
+    if (existing.includes(raw)) {
+      warn(`Collection '${raw}' already exists. Choose a different name.`);
+      continue;
+    }
+    colName = raw;
+    break;
+  }
+
+  // ─── Derive camelCase variable name: my-news → myNewsCollection ──────────
+  const parts   = colName.split('-');
+  const varName = parts[0] + parts.slice(1).map(p => p[0].toUpperCase() + p.slice(1)).join('') + 'Collection';
+
+  // ─── Prompt: collection type ──────────────────────────────────────────────
+  console.log('');
+  console.log(`${B}Collection type:${X}`);
+  console.log('  1) blog    — articles (date, author, tags, image, draft)');
+  console.log('  2) docs    — documentation pages (order, category, draft)');
+  console.log('  3) generic — simple entries (title, optional description, draft)');
+  console.log('');
+  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 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: './src/content/${colName}',\n` +
+    `  }),\n` +
+    `  schema: z.object({\n` +
+    `${SCHEMA[colType]}\n` +
+    `  }),\n` +
+    `});\n`;
+
+  const MARKER = '// Export all collections';
+  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, before + after, 'utf8');
+  ok('src/content.config.ts updated');
+
+  // ─── 2. Sample content file(s) ───────────────────────────────────────────
+  const today      = new Date().toISOString().slice(0, 10);
+  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 = {
+    blog:
+      `---\ntitle: "Sample Post"\n` +
+      `description: "A sample post in the ${colName} collection."\n` +
+      `date: ${today}\nauthor: "Your Name"\ntags: ["sample"]\ndraft: true\n---\n\n` +
+      `# Sample Post\n\nThis is a sample post. Replace this file with real content.\n`,
+    docs:
+      `---\ntitle: "Sample Document"\n` +
+      `description: "A sample document in the ${colName} collection."\n` +
+      `order: 1\ncategory: "general"\ndraft: true\n---\n\n` +
+      `# Sample Document\n\nThis is a sample document. Replace this file with real content.\n`,
+    generic:
+      `---\ntitle: "Sample Entry"\n` +
+      `description: "A sample entry in the ${colName} collection."\n` +
+      `draft: true\n---\n\n` +
+      `# Sample Entry\n\nThis is a sample entry. Replace this file with real content.\n`,
+  };
+
+  // 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, 'src', 'pages', colName);
+  mkdirSync(pagesDir, { recursive: true });
+
+  const sub       = (s) => s.replaceAll('__COL__', colName);
+  const indexPath = join(pagesDir, 'index.astro');
+  const slugPath  = join(pagesDir, '[...slug].astro');
+
+  writeFileSync(indexPath, sub(INDEX[colType]), 'utf8');
+  writeFileSync(slugPath,  sub(SLUG[colType]),  'utf8');
+  ok(relative(ROOT_DIR, indexPath));
+  ok(relative(ROOT_DIR, slugPath));
+
+  // ─── Summary ──────────────────────────────────────────────────────────────
+  console.log('');
+  console.log(`${G}${B}Collection '${colName}' scaffolded successfully!${X}`);
+  console.log('');
+  console.log(`  ${B}Next steps:${X}`);
+  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('');
+}
+
+main().catch(err => error(String(err)));