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

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])
     : [];
 
@@ -465,14 +470,14 @@ async function main() {
   ok(`Type: ${colType}`);
   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,20 +485,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 ───────────────────────────────────────────────
   const today      = new Date().toISOString().slice(0, 10);
-  const contentDir = join(ROOT_DIR, 'usr', 'content', colName);
+  const contentDir = join(ROOT_DIR, 'src', 'content', colName);
   mkdirSync(contentDir, { recursive: true });
 
   const SAMPLE_NAME = { blog: 'sample-post.md', docs: 'sample-doc.md', generic: 'sample.md' };
@@ -520,7 +534,7 @@ async function main() {
   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 +551,9 @@ 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`);
+  console.log(`    3. Replace the sample file 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.
@@ -71,7 +78,7 @@ function hasMdx(dir) {
 /** 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);
@@ -177,7 +184,7 @@ async function main() {
       continue;
     }
     if (existsSync(join(colDir, raw, `index.${ext}`))) {
-      warn(`File already exists: usr/content/${collection}/${raw}/index.${ext}`);
+      warn(`File already exists: src/content/${collection}/${raw}/index.${ext}`);
       continue;
     }
     slug = raw;
@@ -253,7 +260,7 @@ async function main() {
   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(`    1. Open ${B}src/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('');

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)));

package/components/BSNavbar.tsx

@@ -43,7 +43,7 @@ interface CssClasses {
  * Active state is computed internally from `currentPath` — no need to set
  * `isActive` on individual menu items.
  *
- * Menu data can be loaded from a YAML file (e.g. `usr/content/data/menu.yaml`)
+ * Menu data can be loaded from a YAML file (e.g. `src/content/data/menu.yaml`)
  * and passed straight to `menuItems`.
  *
  * Must be hydrated with `client:load` when used inside an Astro component.
@@ -63,7 +63,7 @@ interface CssClasses {
  * />
  * ```
  *
- * @example YAML menu structure (`usr/content/data/menu.yaml`)
+ * @example YAML menu structure (`src/content/data/menu.yaml`)
  * ```yaml
  * - href: /
  *   label: Home

package/components/Gallery/__tests__/galleryUtils.test.ts

@@ -2,23 +2,23 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 const manifest = {
   pagesImages: {
-    '/usr/pages/my-page/gallery/photo1.jpg': { default: { src: '/_astro/photo1.abc123.jpg', width: 1200, height: 800 } },
+    '/src/pages/my-page/gallery/photo1.jpg': { default: { src: '/_astro/photo1.abc123.jpg', width: 1200, height: 800 } },
   },
   contentImages: {
-    '/usr/content/blog/my-article/gallery/photo2.jpg': { default: { src: '/_astro/photo2.def456.jpg', width: 1000, height: 600 } },
-    '/usr/content/blog/other-article/gallery/photo3.jpg': { default: { src: '/_astro/photo3.ghi789.jpg', width: 900, height: 500 } },
+    '/src/content/blog/my-article/gallery/photo2.jpg': { default: { src: '/_astro/photo2.def456.jpg', width: 1000, height: 600 } },
+    '/src/content/blog/other-article/gallery/photo3.jpg': { default: { src: '/_astro/photo3.ghi789.jpg', width: 900, height: 500 } },
   },
   sharedImages: {
-    '/usr/galleries/scavi-2024/site-a.jpg': { default: { src: '/_astro/site-a.jkl000.jpg', width: 800, height: 600 } },
-    '/usr/galleries/scavi-2024/site-b_1920.jpg': { default: { src: '/_astro/site-b_1920.mno111.jpg', width: 800, height: 600 } },
-    '/usr/galleries/other-name/site-c.jpg': { default: { src: '/_astro/site-c.pqr222.jpg', width: 800, height: 600 } },
+    '/src/galleries/scavi-2024/site-a.jpg': { default: { src: '/_astro/site-a.jkl000.jpg', width: 800, height: 600 } },
+    '/src/galleries/scavi-2024/site-b_1920.jpg': { default: { src: '/_astro/site-b_1920.mno111.jpg', width: 800, height: 600 } },
+    '/src/galleries/other-name/site-c.jpg': { default: { src: '/_astro/site-c.pqr222.jpg', width: 800, height: 600 } },
   },
   pagesCaptions: {},
   contentCaptions: {
-    '/usr/content/blog/my-article/gallery/captions.json': { default: { 'photo2.jpg': 'A custom caption' } },
+    '/src/content/blog/my-article/gallery/captions.json': { default: { 'photo2.jpg': 'A custom caption' } },
   },
   sharedCaptions: {
-    '/usr/galleries/scavi-2024/captions.json': {
+    '/src/galleries/scavi-2024/captions.json': {
       default: {
         'site-a.jpg': 'Exact match caption',
         // Deliberately a different resolution suffix than the real file
@@ -146,7 +146,7 @@ describe('getSharedCaptions', () => {
   function parseMalformedFixture() {
     // Reuses the real function against a manifest entry shaped like a
     // malformed captions.json (nested object instead of Record<string,string>).
-    (manifest.sharedCaptions as any)['/usr/galleries/broken/captions.json'] = { default: { nested: { not: 'a string' } } };
+    (manifest.sharedCaptions as any)['/src/galleries/broken/captions.json'] = { default: { nested: { not: 'a string' } } };
     return getSharedCaptions('broken');
   }
 });

package/components/Gallery/galleryUtils.ts

@@ -152,7 +152,7 @@ export function getSharedCaptions(name: string): Record<string, string> | undefi
 /**
  * Images from a `gallery/` folder colocated with the current page/content
  * file, matched by comparing the current URL path against the folder
- * structure under usr/pages/ or usr/content/. Applies captions.json from
+ * structure under src/pages/ or src/content/. Applies captions.json from
  * the same folder, if present.
  *
  * Known limitation (unchanged from before this redesign): if a content
@@ -173,7 +173,7 @@ export function getColocatedGalleryImages(pathname: string): GalleryImage[] {
     .map(([filepath, mod]) => moduleToGalleryImage(filepath, mod, captionLookup));
 }
 
-/** Images from a shared gallery at usr/galleries/<name>/. Applies captions.json from the same folder, if present. */
+/** Images from a shared gallery at src/galleries/<name>/. Applies captions.json from the same folder, if present. */
 export function getSharedGalleryImages(name: string): GalleryImage[] {
   const captions = getSharedCaptions(name);
   const captionLookup = captions ? buildCaptionLookup(captions) : undefined;

package/components/Gallery/types.ts

@@ -13,7 +13,7 @@ export interface GalleryImage {
 
 export interface GalleryProps {
   /**
-   * Name of a shared gallery under usr/galleries/<name>/
+   * Name of a shared gallery under src/galleries/<name>/
    * If not provided (and `images` isn't either), auto-loads from the
    * `gallery/` folder colocated with the current page/content file.
    */

package/components/Record/useRecordFetcher.ts

@@ -31,7 +31,7 @@ export interface UseRecordFetcherResult {
  *
  * @example
  * ```tsx
- * // usr/components/RecordView.tsx
+ * // src/components/RecordView.tsx
  * import { useRecordFetcher } from '@lad-sapienza/scms-core/components/Record/useRecordFetcher';
  *
  * export default function RecordView() {
@@ -45,7 +45,7 @@ export interface UseRecordFetcherResult {
  * ```
  *
  * ```astro
- * <!-- usr/pages/record.astro -->
+ * <!-- src/pages/record.astro -->
  * <RecordView client:load />
  * ```
  */

package/integrations/__tests__/galleryIntegration.test.ts

@@ -26,17 +26,17 @@ describe('galleryIntegration', () => {
     expect(plugin.resolveId('some/other/id')).toBeUndefined();
   });
 
-  it('generates a virtual module with one static glob per source root, using the default usr/ paths', () => {
+  it('generates a virtual module with one static glob per source root, using the default src/ paths', () => {
     const plugin = getVitePlugin();
     const resolvedId = plugin.resolveId(GALLERY_VIRTUAL_MODULE_ID);
     const source = plugin.load(resolvedId);
 
-    expect(source).toContain("import.meta.glob('/usr/pages/**/gallery/*.");
-    expect(source).toContain("import.meta.glob('/usr/content/**/gallery/*.");
-    expect(source).toContain("import.meta.glob('/usr/galleries/*/*.");
-    expect(source).toContain("import.meta.glob('/usr/pages/**/gallery/captions.json'");
-    expect(source).toContain("import.meta.glob('/usr/content/**/gallery/captions.json'");
-    expect(source).toContain("import.meta.glob('/usr/galleries/*/captions.json'");
+    expect(source).toContain("import.meta.glob('/src/pages/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/src/content/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/src/galleries/*/*.");
+    expect(source).toContain("import.meta.glob('/src/pages/**/gallery/captions.json'");
+    expect(source).toContain("import.meta.glob('/src/content/**/gallery/captions.json'");
+    expect(source).toContain("import.meta.glob('/src/galleries/*/captions.json'");
 
     // Every glob call must use { eager: true } — a lazy glob would return
     // dynamic import() functions instead of already-resolved image metadata.
@@ -50,14 +50,14 @@ describe('galleryIntegration', () => {
     expect(plugin.load('/some/unrelated/module.js')).toBeUndefined();
   });
 
-  it('honors custom directory options', () => {
-    const plugin = getVitePlugin({ pagesDir: 'src/pages', contentDir: 'src/content', galleriesDir: 'src/galleries' });
+  it('honors custom directory options, overriding the src/ defaults', () => {
+    const plugin = getVitePlugin({ pagesDir: 'custom/pages', contentDir: 'custom/content', galleriesDir: 'custom/galleries' });
     const source = plugin.load(plugin.resolveId(GALLERY_VIRTUAL_MODULE_ID));
 
-    expect(source).toContain("import.meta.glob('/src/pages/**/gallery/*.");
-    expect(source).toContain("import.meta.glob('/src/content/**/gallery/*.");
-    expect(source).toContain("import.meta.glob('/src/galleries/*/*.");
-    expect(source).not.toContain('/usr/');
+    expect(source).toContain("import.meta.glob('/custom/pages/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/custom/content/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/custom/galleries/*/*.");
+    expect(source).not.toContain('/src/');
   });
 });
 

package/integrations/contentAssetsIntegration.ts

@@ -2,12 +2,12 @@
  * contentAssetsIntegration
  *
  * Astro integration that serves static assets (images, PDFs, etc.) co-located
- * in the content directory (usr/content/ by default) without requiring a
+ * in the content directory (src/content/ by default) without requiring a
  * manual copy step.
  *
  * - Dev server: a Vite middleware intercepts requests for static file extensions
  *   and serves them directly from the content directory, mapping URL paths 1:1
- *   (e.g. /blog/post/image.jpg → usr/content/blog/post/image.jpg).
+ *   (e.g. /blog/post/image.jpg → src/content/blog/post/image.jpg).
  *
  * - Production build: assets are copied from the content directory into dist/
  *   with the same relative path structure, so they are available at the
@@ -23,7 +23,7 @@ import { existsSync, statSync, mkdirSync, copyFileSync, readdirSync, createReadS
 import { fileURLToPath } from 'node:url';
 
 export interface ContentAssetsOptions {
-  /** Path to the content directory, relative to the project root. Defaults to 'usr/content'. */
+  /** Path to the content directory, relative to the project root. Defaults to 'src/content'. */
   contentDir?: string;
 }
 
@@ -60,7 +60,7 @@ function collectAssets(dir: string, results: string[] = []): string[] {
 }
 
 export function contentAssetsIntegration(options: ContentAssetsOptions = {}): AstroIntegration {
-  const contentDirSegment = options.contentDir ?? join('usr', 'content');
+  const contentDirSegment = options.contentDir ?? join('src', 'content');
   // Resolved from Astro's own config root in astro:config:setup below, rather
   // than assumed from process.cwd() — more portable if the process is ever
   // invoked from somewhere other than the project root.
@@ -76,7 +76,7 @@ export function contentAssetsIntegration(options: ContentAssetsOptions = {}): As
       /**
        * Dev server: add a Connect middleware that serves static assets directly
        * from the content directory without requiring them to be copied to
-       * usr/public/.
+       * public/.
        */
       'astro:server:setup': ({ server, logger }) => {
         const contentDir = resolve(projectRoot, contentDirSegment);

package/integrations/galleryIntegration.ts

@@ -22,23 +22,23 @@ const RESOLVED_VIRTUAL_MODULE_ID = '\0' + GALLERY_VIRTUAL_MODULE_ID;
 const IMAGE_EXTENSIONS = '{jpg,jpeg,png,gif,webp,avif,JPG,JPEG,PNG,GIF,WEBP,AVIF}';
 
 export interface GalleryIntegrationOptions {
-  /** Path to page files, relative to the project root. Defaults to 'usr/pages'. */
+  /** Path to page files, relative to the project root. Defaults to 'src/pages'. */
   pagesDir?: string;
-  /** Path to content collections, relative to the project root. Defaults to 'usr/content'. */
+  /** Path to content collections, relative to the project root. Defaults to 'src/content'. */
   contentDir?: string;
-  /** Path to shared galleries, relative to the project root. Defaults to 'usr/galleries'. */
+  /** Path to shared galleries, relative to the project root. Defaults to 'src/galleries'. */
   galleriesDir?: string;
 }
 
-/** Normalize a directory segment into a Vite root-relative glob prefix, e.g. 'usr/pages' -> '/usr/pages'. */
+/** Normalize a directory segment into a Vite root-relative glob prefix, e.g. 'src/pages' -> '/src/pages'. */
 function toRootGlobPrefix(dir: string): string {
   return '/' + dir.replace(/^\/+|\/+$/g, '');
 }
 
 export function buildGalleryVirtualModuleSource(options: GalleryIntegrationOptions = {}): string {
-  const pages = toRootGlobPrefix(options.pagesDir ?? 'usr/pages');
-  const content = toRootGlobPrefix(options.contentDir ?? 'usr/content');
-  const galleries = toRootGlobPrefix(options.galleriesDir ?? 'usr/galleries');
+  const pages = toRootGlobPrefix(options.pagesDir ?? 'src/pages');
+  const content = toRootGlobPrefix(options.contentDir ?? 'src/content');
+  const galleries = toRootGlobPrefix(options.galleriesDir ?? 'src/galleries');
 
   return `
 export const pagesImages = import.meta.glob('${pages}/**/gallery/*.${IMAGE_EXTENSIONS}', { eager: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lad-sapienza/scms-core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Framework components and Astro integrations for s:CMS — DataTb, Gallery, Map, ZoteroGeoViewer, Record.",
   "type": "module",
   "license": "BSD-0-Clause",
@@ -12,12 +12,14 @@
   "main": "./index.ts",
   "bin": {
     "scms-add-collection": "./bin/add-collection.mjs",
-    "scms-add-content": "./bin/add-content.mjs"
+    "scms-add-content": "./bin/add-content.mjs",
+    "scms-create": "./bin/create.mjs"
   },
   "files": [
     "index.ts",
     "scms.ts",
     "bin",
+    "template",
     "components",
     "integrations",
     "utils",

package/scms.ts

@@ -30,11 +30,11 @@ import { contentAssetsIntegration } from './integrations/contentAssetsIntegratio
 import { galleryIntegration } from './integrations/galleryIntegration';
 
 export interface ScmsOptions {
-  /** Path to the content directory, relative to the project root. Defaults to 'usr/content'. */
+  /** Path to the content directory, relative to the project root. Defaults to 'src/content'. */
   contentDir?: string;
-  /** Path to page files, relative to the project root. Defaults to 'usr/pages'. */
+  /** Path to page files, relative to the project root. Defaults to 'src/pages'. */
   pagesDir?: string;
-  /** Path to shared galleries, relative to the project root. Defaults to 'usr/galleries'. */
+  /** Path to shared galleries, relative to the project root. Defaults to 'src/galleries'. */
   galleriesDir?: string;
 }
 

package/template/.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/template/README.md.tmpl

@@ -0,0 +1,37 @@
+# __TITLE__
+
+__DESCRIPTION__
+
+Built with [s:CMS](https://github.com/lad-sapienza/scms-core), on top of [Astro](https://astro.build).
+
+## Commands
+
+| Command | Action |
+|---|---|
+| `npm install` | Install dependencies |
+| `npm run dev` | Start the local dev server at `localhost:4321` |
+| `npm run build` | Build the production site to `./dist/` |
+| `npm run preview` | Preview the production build locally |
+| `npm run add-collection` | Scaffold a new content collection |
+| `npm run add-content` | Add a new content file to an existing collection |
+
+## Updating the framework
+
+```bash
+npm update @lad-sapienza/scms-core
+```
+
+## Project structure
+
+```
+src/
+  content.config.ts     # Content collection schemas
+  user.config.mjs        # Site configuration and metadata
+  pages/                  # Routes
+  layouts/                 # Layouts
+  styles/global.css         # Stylesheet
+public/                   # Static assets, served as-is
+astro.config.mjs          # Registers the scms() integration
+```
+
+See the [s:CMS documentation](https://github.com/lad-sapienza/sCMS) for available components (`DataTb`, `Map`, `Gallery`, `ZoteroGeoViewer`, `Record`, and more).

package/template/astro.config.mjs

@@ -0,0 +1,26 @@
+import { defineConfig } from 'astro/config';
+import rehypeSlug from 'rehype-slug';
+import { unified } from '@astrojs/markdown-remark';
+import { userConfig } from './src/user.config.mjs';
+import { scms } from '@lad-sapienza/scms-core/scms';
+
+export default defineConfig({
+  site: userConfig.site,
+  base: userConfig.base,
+  output: 'static',
+
+  // rehypeSlug adds an id to every heading, which the TableOfContents
+  // component relies on for its anchor links.
+  markdown: {
+    processor: unified({ rehypePlugins: [rehypeSlug] }),
+  },
+
+  integrations: [
+    ...scms(),
+    ...(userConfig.integrations || []),
+  ],
+
+  vite: {
+    ...(userConfig.vite || {}),
+  },
+});

package/template/package.json.tmpl

@@ -0,0 +1,31 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "description": "__DESCRIPTION__",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro check && astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "add-collection": "scms-add-collection",
+    "add-content": "scms-add-content"
+  },
+  "dependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@astrojs/markdown-remark": "^__ASTRO_VERSION__",
+    "@lad-sapienza/scms-core": "^__SCMS_VERSION__",
+    "astro": "^__ASTRO_VERSION__",
+    "bootstrap": "^5.3.8",
+    "react": "^__REACT_VERSION__",
+    "react-dom": "^__REACT_DOM_VERSION__",
+    "maplibre-gl": "^__MAPLIBRE_VERSION__",
+    "rehype-slug": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^__TYPES_REACT_VERSION__",
+    "@types/react-dom": "^__TYPES_REACT_DOM_VERSION__",
+    "typescript": "^5.9.3"
+  }
+}

package/template/src/content.config.ts

@@ -0,0 +1,27 @@
+/**
+ * Content Collections Configuration
+ *
+ * Define your content collections here. Each collection needs a loader
+ * (usually `glob` for local Markdown/MDX files) and a Zod schema.
+ *
+ * Fastest way to add one: `npm run add-collection`.
+ *
+ * Example — a `blog` collection, added to the `collections` export below:
+ *
+ * const blog = defineCollection({
+ *   loader: glob({ pattern: '**\/*.{md,mdx}', base: './src/content/blog' }),
+ *   schema: z.object({
+ *     title: z.string(),
+ *     description: z.string(),
+ *     date: z.coerce.date(),
+ *     draft: z.boolean().optional(),
+ *   }),
+ * });
+ */
+
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { z } from 'zod';
+
+// Export all collections
+export const collections = {};

package/template/src/layouts/BaseLayout.astro

@@ -0,0 +1,62 @@
+---
+import "../styles/global.css"
+import SEO from "@lad-sapienza/scms-core/components/SEO/SEO.astro"
+import BSNavbar from "@lad-sapienza/scms-core/components/BSNavbar"
+import { siteMetadata } from "../user.config.mjs"
+
+interface Props {
+  title?: string
+  description?: string
+}
+
+const { title = siteMetadata.title, description = siteMetadata.description } =
+  Astro.props
+
+const currentPath = Astro.url.pathname
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <SEO title={title} description={description} siteMetadata={siteMetadata} />
+    <slot name="head" />
+  </head>
+
+  <body class="d-flex flex-column min-vh-100">
+    <BSNavbar
+      client:load
+      menuItems={[]}
+      currentPath={currentPath}
+      cssClasses={{
+        nav: "bg-body-tertiary navbar-expand-md sticky-top shadow-sm border-bottom",
+        ul: "ms-auto mb-2 mb-md-0",
+        li: "text-center fw-medium",
+      }}
+      brand={{
+        text: siteMetadata.title,
+        link: "/",
+        cssClasses: "fw-bold",
+      }}
+    />
+
+    <main
+      class="container flex-grow-1"
+      style="padding-top: 6rem; padding-bottom: 3rem;"
+    >
+      <slot />
+    </main>
+
+    <footer class="py-4 mt-auto border-top">
+      <div class="container text-center text-muted small">
+        Built with <a href="https://github.com/lad-sapienza/scms-core" target="_blank" rel="noreferrer">s:CMS</a>
+      </div>
+    </footer>
+
+    <script
+      src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"
+      defer
+      is:inline></script>
+  </body>
+</html>

package/template/src/pages/index.astro

@@ -0,0 +1,14 @@
+---
+import BaseLayout from '../layouts/BaseLayout.astro';
+---
+
+<BaseLayout>
+  <h1>Welcome to your new s:CMS site</h1>
+  <p class="lead">
+    Edit <code>src/pages/index.astro</code> to change this page.
+  </p>
+  <p>
+    Run <code>npm run add-collection</code> to scaffold your first content
+    collection, or start writing components directly in <code>src/</code>.
+  </p>
+</BaseLayout>

package/template/src/styles/global.css

@@ -0,0 +1,8 @@
+/* Bootstrap, compiled CSS */
+@import "bootstrap/dist/css/bootstrap.min.css";
+
+/* Add your own overrides below, e.g.:
+:root {
+  --bs-primary: #6366f1;
+}
+*/

package/template/src/user.config.mjs.tmpl

@@ -0,0 +1,34 @@
+/**
+ * Site Configuration
+ *
+ * Edit this file to configure your site's metadata, integrations, and more.
+ */
+
+export const userConfig = {
+  // Site URL (required for sitemap and canonical URLs)
+  site: '__SITE_URL__',
+
+  // Base path (if deploying to a subdirectory, e.g. GitHub Pages project sites)
+  // base: '/my-site',
+
+  // Additional Astro integrations (merged with scms()'s own)
+  integrations: [
+    // Add your custom integrations here
+  ],
+
+  // Custom Vite configuration
+  vite: {
+    // Your custom Vite config
+  },
+};
+
+/**
+ * Site Metadata
+ *
+ * Used throughout the site for SEO, social media cards, and general info.
+ */
+export const siteMetadata = {
+  title: '__TITLE__',
+  description: '__DESCRIPTION__',
+  author: '__AUTHOR__',
+};

package/template/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "strictNullChecks": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true
+  }
+}

package/utils/content.ts

@@ -49,7 +49,7 @@ export async function getSortedCollection(
   });
 }
 
-// Menu extraction logic should be implemented in user code (usr/), not in core.
+// Menu extraction logic should be implemented in the consuming site's own code, not here.
 
 /**
  * Parse CSV string to JSON