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

package/README.md

@@ -18,7 +18,12 @@ 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: [
@@ -60,6 +65,17 @@ import { directusLoader } from '@lad-sapienza/scms-core/integrations/directusLoa
 
 See each component folder's own `README.md` (`components/DataTb`, `components/Gallery`, `components/ZoteroGeoViewer`, `components/`) for detailed API docs and examples.
 
+## 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:
+
+```bash
+npx scms-add-collection   # scaffold a new Astro content collection under usr/
+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`.
+
 ## Development
 
 ```bash

package/bin/add-collection.mjs

@@ -0,0 +1,547 @@
+#!/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, 'usr', '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>usr/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>usr/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>usr/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
+  const cfgSrc    = readFileSync(CONFIG_FILE, 'utf8');
+  const exportM   = cfgSrc.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}`);
+  rl.close();
+
+  // ─── 1. Update usr/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` +
+    `  }),\n` +
+    `  schema: z.object({\n` +
+    `${SCHEMA[colType]}\n` +
+    `  }),\n` +
+    `});\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,
+    (_, open, inner, close) => `${open}${inner.trimEnd()}\n  ${toObjectKey(colName)}: ${varName},\n${close}`
+  );
+  writeFileSync(CONFIG_FILE, cfg, 'utf8');
+  ok('usr/content.config.ts updated');
+
+  // ─── 2. Sample content file ───────────────────────────────────────────────
+  const today      = new Date().toISOString().slice(0, 10);
+  const contentDir = join(ROOT_DIR, 'usr', 'content', colName);
+  mkdirSync(contentDir, { recursive: true });
+
+  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`,
+  };
+
+  const samplePath = join(contentDir, 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);
+  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}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(`    4. Run ${B}npm run dev${X} and visit ${B}/${colName}${X}`);
+  console.log('');
+}
+
+main().catch(err => error(String(err)));

package/bin/add-content.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// add-content.mjs — Add a new content file to an existing s:CMS collection.
+// Usage: npx scms-add-content
+//    or: npm run add-content (from a consuming site's package.json)
+
+import { createInterface } from 'node:readline';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+
+// 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, 'usr', 'content.config.ts');
+const CONTENT_BASE = join(ROOT_DIR, 'usr', 'content');
+
+// ─── 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}`);
+
+// ─── 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;
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Parse top-level collection keys from export const collections = { ... } */
+function parseCollections(src) {
+  const m = src.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.
+  return [...m[1].matchAll(/(?:['"]([\w-]+)['"]|(\w+))\s*:/g)].map(x => x[1] ?? x[2]);
+}
+
+/** Count .md / .mdx files recursively in a directory */
+function countMdFiles(dir) {
+  try {
+    return readdirSync(dir, { recursive: true })
+      .filter(f => f.endsWith('.md') || f.endsWith('.mdx'))
+      .length;
+  } catch { return 0; }
+}
+
+/** Return true if any .mdx file exists under dir */
+function hasMdx(dir) {
+  try {
+    return readdirSync(dir, { recursive: true }).some(f => f.endsWith('.mdx'));
+  } catch { return false; }
+}
+
+/** 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\\(\\{(.*?)\\}\\)`,
+    's'
+  );
+  const m = src.match(pat);
+  if (!m) return [];
+
+  const fields = [];
+  for (let line of m[1].split('\n')) {
+    line = line.trim().replace(/,$/, '');
+    if (!line || line.startsWith('//')) continue;
+    const fm = line.match(/^(\w+)\s*:\s*(.+)$/);
+    if (!fm) continue;
+    const [, name, ztype] = fm;
+    const optional = ztype.includes('.optional()');
+    let kind;
+    if      (ztype.includes('z.array'))                                   kind = 'array';
+    else if (ztype.includes('z.number'))                                  kind = 'number';
+    else if (ztype.includes('z.boolean'))                                 kind = 'boolean';
+    else if (ztype.includes('z.coerce.date') || ztype.includes('z.date')) kind = 'date';
+    else                                                                  kind = 'string';
+    fields.push({ name, kind, optional });
+  }
+  return fields;
+}
+
+/** Escape a value for a YAML double-quoted scalar (backslash first, then quotes) */
+function yamlQuote(value) {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** Format a single frontmatter line for a given value and Zod kind */
+function toYamlLine(name, value, kind) {
+  if (kind === 'boolean') {
+    const b = ['true', 'yes', '1'].includes(value.toLowerCase());
+    return `${name}: ${b ? 'true' : 'false'}`;
+  }
+  if (kind === 'number') return `${name}: ${value}`;
+  if (kind === 'array') {
+    const items = value.split(',').map(s => s.trim()).filter(Boolean);
+    return `${name}: [${items.map(yamlQuote).join(', ')}]`;
+  }
+  if (kind === 'date') return `${name}: ${value}`;
+  return `${name}: ${yamlQuote(value)}`;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const cfgSrc = readFileSync(CONFIG_FILE, 'utf8');
+  const allCollections = parseCollections(cfgSrc);
+
+  // Keep only collections that have a content directory with actual files
+  const collections = allCollections.filter(col => {
+    const dir = join(CONTENT_BASE, col);
+    return existsSync(dir) && statSync(dir).isDirectory();
+  });
+
+  console.log('');
+  console.log(`${B}Available collections:${X}`);
+  if (collections.length === 0) {
+    console.log("  (none found — run 'npm run add-collection' first)");
+    rl.close();
+    process.exit(1);
+  }
+  collections.forEach((col, i) => {
+    const count = countMdFiles(join(CONTENT_BASE, col));
+    console.log(`  ${i + 1}) ${col}  (${count} file(s))`);
+  });
+  console.log('');
+
+  // ─── Prompt: collection ───────────────────────────────────────────────────
+  let collection;
+  while (true) {
+    const raw = (await ask(`${B}Collection${X} [name or number]: `)).trim();
+    if (!raw) { warn('Please enter a name or number.'); continue; }
+    if (/^\d+$/.test(raw)) {
+      const idx = parseInt(raw, 10) - 1;
+      if (idx >= 0 && idx < collections.length) { collection = collections[idx]; break; }
+      warn('Number out of range.');
+    } else {
+      if (collections.includes(raw)) { collection = raw; break; }
+      warn(`'${raw}' is not an available collection.`);
+    }
+  }
+  ok(`Collection: ${collection}`);
+
+  // ─── Prompt: file format ─────────────────────────────────────────────────
+  const colDir     = join(CONTENT_BASE, collection);
+  const defaultExt = hasMdx(colDir) ? '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;
+
+  // ─── Prompt: slug ─────────────────────────────────────────────────────────
+  console.log('');
+  console.log('  Slug becomes the URL path and file name.');
+  console.log('  Use lowercase letters, numbers, and hyphens. Subfolders allowed (e.g. guides/my-topic).');
+  console.log('');
+  let slug;
+  while (true) {
+    const raw = (await ask(`${B}Slug${X}: `)).trim().replace(/^\//, '').replace(/\/$/, '');
+    if (!raw) { warn('Slug cannot be empty.'); continue; }
+    if (!/^[a-z0-9/_-]+$/.test(raw)) {
+      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}`);
+      continue;
+    }
+    slug = raw;
+    break;
+  }
+
+  // ─── Collect frontmatter values ───────────────────────────────────────────
+  const today  = new Date().toISOString().slice(0, 10);
+  const fields = parseSchemaFields(cfgSrc, collection);
+
+  let gitAuthor = '';
+  try {
+    gitAuthor = execSync('git config user.name', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { /* git not available or no config */ }
+
+  console.log('');
+  console.log(`${B}Frontmatter fields${X} (press Enter to use the default value shown in brackets):`);
+  console.log('');
+
+  const fmLines  = [];
+  let titleValue = slug; // used as the markdown H1 heading fallback
+
+  for (const { name, kind, optional } of fields) {
+    let defaultVal = '';
+    if      (kind === 'date')                defaultVal = today;
+    else if (name === 'draft')               defaultVal = 'true';
+    else if (name === 'author' && gitAuthor) defaultVal = gitAuthor;
+
+    let prompt = `  ${name}`;
+    if (optional)        prompt += '  (optional)';
+    if (kind === 'array') prompt += ' [comma-separated]';
+    if (defaultVal)       prompt += ` [${defaultVal}]`;
+    prompt += ': ';
+
+    let value = (await ask(prompt)).trim();
+    if (!value && defaultVal) value = defaultVal;
+
+    if (!value) {
+      if (optional) continue; // skip optional empty fields
+      fmLines.push(`${name}: ""`);
+      continue;
+    }
+
+    if (name === 'title') titleValue = value;
+    fmLines.push(toYamlLine(name, value, kind));
+  }
+
+  rl.close();
+
+  // ─── Write file ───────────────────────────────────────────────────────────
+  const targetDir  = join(colDir, slug);
+  const targetPath = join(targetDir, `index.${ext}`);
+  mkdirSync(targetDir, { recursive: true });
+
+  const content = [
+    '---',
+    ...fmLines,
+    '---',
+    '',
+    `# ${titleValue}`,
+    '',
+    '<!-- Write your content here -->',
+    '',
+  ].join('\n');
+
+  writeFileSync(targetPath, content, 'utf8');
+
+  console.log('');
+  ok(`Created: ${relative(ROOT_DIR, targetPath)}`);
+
+  // ─── Summary ──────────────────────────────────────────────────────────────
+  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`);
+  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}`);
+  console.log('');
+}
+
+main().catch(err => error(String(err)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lad-sapienza/scms-core",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Framework components and Astro integrations for s:CMS — DataTb, Gallery, Map, ZoteroGeoViewer, Record.",
   "type": "module",
   "license": "BSD-0-Clause",
@@ -10,9 +10,14 @@
   },
   "author": "Julian Bogdani <julian.bogdani@uniroma1.it>",
   "main": "./index.ts",
+  "bin": {
+    "scms-add-collection": "./bin/add-collection.mjs",
+    "scms-add-content": "./bin/add-content.mjs"
+  },
   "files": [
     "index.ts",
     "scms.ts",
+    "bin",
     "components",
     "integrations",
     "utils",