@crombolo/cli 0.0.0-stage → 0.9.1

package/src/templates.ts

@@ -0,0 +1,309 @@
+/**
+ * Starter templates: what `crombolo init` writes, and the catalogue
+ * `--template list` prints.
+ *
+ * A template is a directory under `templates/`, one or two levels deep so a
+ * family can share a prefix (`demo/harbourstone`):
+ *
+ *   template.json   name and description, for the catalogue
+ *   files/          copied verbatim into the new site
+ *   bundle/         a content bundle, which the scaffolded `start` script
+ *                   applies; it carries its own media, so nothing else does
+ *
+ * Content arrives as a bundle rather than as seed code so that it is the same
+ * artifact `content export` produces: reviewable, committed with the site, and
+ * applied by the one import path that is already tested.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { siteMediaTypeFiles } from '@crombolo/schema'
+import { VERSION } from '@crombolo/server'
+
+/** `templates/`, beside `src/` and `bin/` in the published package. */
+export const TEMPLATES_DIR = join(import.meta.dir, '..', 'templates')
+
+/**
+ * A bundle whose server half a template wires into the site it scaffolds: the
+ * dependency, plus the import and the `bundles` entry in `crombolo.config.ts`.
+ *
+ * Written into the site's own files rather than hidden anywhere, because that
+ * import is the whole of what lets a bundle answer a request — so it has to be
+ * a line the developer owns from the first commit and can delete
+ * (`docs/17-bundles.md`).
+ */
+export interface TemplateServerBundle {
+  /** The npm package, added to the site's dependencies. */
+  package: string
+  /** The factory it exports, imported by name and called in `bundles`. */
+  import: string
+  /**
+   * The range to depend on. Defaults to this release, which is right for a
+   * bundle that ships with the CMS; a third-party one names its own.
+   */
+  version?: string
+}
+
+export interface SiteTemplate {
+  /** `basic`, or `demo/harbourstone` for one of a family. */
+  id: string
+  name: string
+  description: string
+  dir: string
+  /** `bundles/<slug>` in the new site, when the template ships content. */
+  bundle?: string
+  /** Server bundles the scaffolded site runs; empty for most templates. */
+  serverBundles: TemplateServerBundle[]
+}
+
+const MANIFEST = 'template.json'
+
+function read(dir: string, id: string): SiteTemplate | undefined {
+  const manifest = join(dir, MANIFEST)
+  if (!existsSync(manifest)) return undefined
+  const raw = JSON.parse(readFileSync(manifest, 'utf8')) as Record<string, unknown>
+  return {
+    id,
+    name: typeof raw.name === 'string' ? raw.name : id,
+    description: typeof raw.description === 'string' ? raw.description : '',
+    dir,
+    bundle: existsSync(join(dir, 'bundle')) ? `bundles/${id.replaceAll('/', '-')}` : undefined,
+    serverBundles: readServerBundles(raw.bundles),
+  }
+}
+
+/** `bundles` in `template.json`; anything malformed is dropped rather than guessed at. */
+function readServerBundles(raw: unknown): TemplateServerBundle[] {
+  if (!Array.isArray(raw)) return []
+  const out: TemplateServerBundle[] = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue
+    const record = entry as Record<string, unknown>
+    const name = typeof record.package === 'string' ? record.package : ''
+    const imported = typeof record.import === 'string' ? record.import : ''
+    if (!name || !imported) continue
+    out.push({
+      package: name,
+      import: imported,
+      ...(typeof record.version === 'string' ? { version: record.version } : {}),
+    })
+  }
+  return out
+}
+
+/** Every template, in id order; a directory without a manifest is a family. */
+export function listTemplates(root = TEMPLATES_DIR): SiteTemplate[] {
+  if (!existsSync(root)) return []
+  const out: SiteTemplate[] = []
+  for (const entry of readdirSync(root).sort()) {
+    const dir = join(root, entry)
+    if (!statSync(dir).isDirectory()) continue
+    const own = read(dir, entry)
+    if (own) {
+      out.push(own)
+      continue
+    }
+    for (const child of readdirSync(dir).sort()) {
+      const nested = read(join(dir, child), `${entry}/${child}`)
+      if (nested) out.push(nested)
+    }
+  }
+  return out
+}
+
+export function findTemplate(id: string, root = TEMPLATES_DIR): SiteTemplate | undefined {
+  return listTemplates(root).find((t) => t.id === id)
+}
+
+export interface ScaffoldOptions {
+  /** `--name`; also the package name, slugified. */
+  siteName?: string
+  /** `--postgres`: write a `.env` naming the Postgres variables instead of using the SQLite default. */
+  postgres?: boolean
+  template?: SiteTemplate
+  /**
+   * A bundle the site already has, for the `start` script to apply: the path,
+   * relative to the site, and any `content import` flags it needs beyond
+   * `--publish`. A template's own bundle is used when this is absent.
+   */
+  bundle?: { path: string; flags?: readonly string[] }
+}
+
+/** One file to write: literal text, or a path to copy (template media and bundles). */
+export interface ScaffoldFile {
+  /** Relative to the new site, `/`-separated. */
+  path: string
+  text?: string
+  copyFrom?: string
+}
+
+const DEFAULT_SITE_NAME = 'My Site'
+
+/** Kept in step with the root `package.json`, which is what the views are checked with. */
+const TYPESCRIPT_VERSION = '^7.0.2'
+
+/** Single quotes, because the file is TypeScript the site's own formatter owns. */
+const quote = (value: string): string => `'${value.replace(/[\\']/g, '\\$&')}'`
+
+/** A directory name npm accepts: lowercase, no spaces, no leading punctuation. */
+export function packageNameFor(siteName: string): string {
+  const slug = siteName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || 'my-site'
+}
+
+function tsconfig(): string {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ESNext',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
+        jsx: 'react-jsx',
+        jsxImportSource: '@crombolo/crombolo',
+        strict: true,
+        allowImportingTsExtensions: true,
+        noEmit: true,
+        types: ['bun'],
+      },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+/** Search & sharing defaults, commented out: editors can also set them in Settings. */
+const SEO_EXAMPLE = `  // Search & sharing defaults; each can also be set in Settings, which wins.
+  // seo: { titleSuffix: ' | My site', notFoundPage: '<page key>', indexable: true },
+`
+
+/**
+ * `crombolo.config.ts`. A template's server bundles are imported by name and
+ * listed in `bundles`, which is the only thing that lets their endpoints
+ * answer — so the scaffolded file carries a note saying so, and deleting the
+ * line is how a site declines one.
+ */
+function config(siteName: string, bundles: readonly TemplateServerBundle[]): string {
+  const imports = bundles
+    .map((bundle) => `import { ${bundle.import} } from ${quote(bundle.package)}\n`)
+    .join('')
+  if (bundles.length === 0)
+    return `import { defineConfig } from '@crombolo/crombolo'
+
+export default defineConfig({
+  siteName: ${quote(siteName)},
+${SEO_EXAMPLE}})
+`
+  return `${imports}import { defineConfig } from '@crombolo/crombolo'
+
+export default defineConfig({
+  siteName: ${quote(siteName)},
+  // Installing a bundle gives you its backoffice screen. This line is what lets
+  // its endpoints answer a request, so remove it to turn one off.
+  bundles: [${bundles.map((bundle) => `${bundle.import}()`).join(', ')}],
+${SEO_EXAMPLE}})
+`
+}
+
+function packageJson(options: {
+  name: string
+  start: string
+  bundles: readonly TemplateServerBundle[]
+}): string {
+  return `${JSON.stringify(
+    {
+      name: options.name,
+      private: true,
+      type: 'module',
+      scripts: { start: options.start, dev: 'bun --watch server.ts' },
+      dependencies: {
+        '@crombolo/crombolo': `^${VERSION}`,
+        ...Object.fromEntries(
+          options.bundles.map((bundle) => [bundle.package, bundle.version ?? `^${VERSION}`]),
+        ),
+      },
+      // So the tsconfig written beside this has something to run it, and
+      // `crombolo views check` checks types as well as compiling. The version
+      // is the one crombolo itself is checked with.
+      devDependencies: { typescript: TYPESCRIPT_VERSION },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+/** Every file in a scaffolded site, template files last so they win on a clash. */
+export function scaffoldFiles(options: ScaffoldOptions = {}): ScaffoldFile[] {
+  const siteName = options.siteName?.trim() || DEFAULT_SITE_NAME
+  const bundle = options.bundle?.path ?? options.template?.bundle
+  const bundleFlags = ['--publish', ...(options.bundle?.flags ?? [])].join(' ')
+  const serverBundles = options.template?.serverBundles ?? []
+  const files: ScaffoldFile[] = [
+    {
+      path: 'package.json',
+      text: packageJson({
+        name: packageNameFor(siteName),
+        // The import is a boot step rather than a config setting so that it is
+        // visible here, and so that dropping it is editing one line.
+        start: bundle ? `crombolo start --bundle ${bundle} ${bundleFlags}` : 'crombolo start',
+        bundles: serverBundles,
+      }),
+    },
+    { path: 'crombolo.config.ts', text: config(siteName, serverBundles) },
+    {
+      path: 'server.ts',
+      text: `import { crombolo } from '@crombolo/crombolo'
+
+export default await crombolo()
+`,
+    },
+    { path: 'tsconfig.json', text: tsconfig() },
+    { path: 'schema/schema.toml', text: '[schema]\nversion = "1.0.0"\n' },
+    // The media types a site owns as files rather than inheriting silently.
+    ...Object.entries(siteMediaTypeFiles()).map(([path, text]) => ({ path, text })),
+    { path: 'components/.gitkeep', text: '' },
+    {
+      path: '.gitignore',
+      // `.crombolo/` holds the view snapshots: pure cache, rebuilt from `components/`
+      // at every boot, and per node.
+      text: '*.sqlite\n*.sqlite-*\nnode_modules/\n.env\n.crombolo/\nmedia/\nlogs/\n',
+    },
+  ]
+
+  if (options.postgres)
+    files.push({
+      path: '.env',
+      text: `CROMBOLO_DB=postgres
+CROMBOLO_POSTGRES_URL=postgres://crombolo:crombolo@localhost:5432/${packageNameFor(siteName)}
+
+# Postgres has no file to copy, so anything that writes needs a backup first:
+# a command that takes one, or --backup-taken to vouch that you have.
+# CROMBOLO_PG_DUMP=pg_dump "$CROMBOLO_POSTGRES_URL" -f "backup-$CROMBOLO_BACKUP_STAMP.sql"
+`,
+    })
+
+  for (const file of componentFiles(options.template)) files.push(file)
+  // One entry per path, the last winning, so a template's own `schema.toml` is
+  // the one written rather than being skipped as a file that already exists.
+  return [...new Map(files.map((file) => [file.path, file])).values()]
+}
+
+/** `files/` into the site root, `bundle/` under `bundles/<slug>`. */
+export function componentFiles(template: SiteTemplate | undefined): ScaffoldFile[] {
+  if (!template) return []
+  const out: ScaffoldFile[] = []
+  const walk = (dir: string, target: (path: string) => string): void => {
+    if (!existsSync(dir)) return
+    for (const entry of readdirSync(dir, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile()) continue
+      const source = join(entry.parentPath, entry.name)
+      out.push({ path: target(relative(dir, source).split(sepRe).join('/')), copyFrom: source })
+    }
+  }
+  walk(join(template.dir, 'files'), (path) => path)
+  if (template.bundle) walk(join(template.dir, 'bundle'), (path) => `${template.bundle}/${path}`)
+  return out
+}
+
+const sepRe = /[\\/]/

package/templates/basic/bundle/bundle.json

@@ -0,0 +1,45 @@
+{
+  "formatVersion": 1,
+  "id": "2de473a2-d391-4161-801e-e34b202759b8",
+  "createdAt": "2026-10-01T00:00:00.000Z",
+  "createdBy": "bun run build:template",
+  "integrity": "sha256-5e0caa815b7238c8f691bb51692c4b222e8d564fd6490366752f80b98bbd9c70",
+  "snapshot": "published",
+  "provenance": {
+    "siteName": "Basic",
+    "schemaVersion": "1.0.0",
+    "schemaRevision": "0",
+    "schemaHash": "c138d226529a718d25ebca8e0c10e5ca3a5cba85b239b4327e7dd6f21fa45a27"
+  },
+  "selector": {
+    "roots": [
+      "36955f6e-d110-469e-b280-72096eccd148"
+    ],
+    "descendants": true,
+    "asGiven": [
+      "basic"
+    ]
+  },
+  "counts": {
+    "document": 1
+  },
+  "dependencies": {
+    "carried": [
+      "36955f6e-d110-469e-b280-72096eccd148"
+    ],
+    "expected": [],
+    "schema": {
+      "contentTypes": [
+        {
+          "key": "b8188492-dc05-43e6-98bf-04ee758e4c17",
+          "alias": "homePage"
+        }
+      ],
+      "components": [
+        "homePage"
+      ],
+      "languages": []
+    }
+  },
+  "blobs": []
+}

package/templates/basic/bundle/nodes/36955f6e-d110-469e-b280-72096eccd148.json

@@ -0,0 +1,38 @@
+{
+  "key": "36955f6e-d110-469e-b280-72096eccd148",
+  "kind": "document",
+  "contentType": {
+    "key": "b8188492-dc05-43e6-98bf-04ee758e4c17",
+    "alias": "homePage"
+  },
+  "parent": null,
+  "sortOrder": 0,
+  "template": "homePage",
+  "variants": [
+    {
+      "culture": null,
+      "segment": null,
+      "name": "Home",
+      "published": true
+    }
+  ],
+  "values": [
+    {
+      "property": "bodyText",
+      "culture": null,
+      "segment": null,
+      "editor": "Umbraco.RichText",
+      "value": {
+        "markup": "<p>This page is content: it lives in the database and you edit it in the backoffice. Its <em>shape</em> is code — <code>schema/content-types/home-page.toml</code> — and the markup around it is <code>components/homePage.tsx</code>.</p><p>Add a property to the TOML, run <code>crombolo schema check</code> to see what it would do to this page, then <code>crombolo start</code> to apply it.</p>",
+        "blocks": null
+      }
+    },
+    {
+      "property": "title",
+      "culture": null,
+      "segment": null,
+      "editor": "Umbraco.TextBox",
+      "value": "A new crombolo site"
+    }
+  ]
+}

package/templates/basic/files/components/homePage.tsx

@@ -0,0 +1,22 @@
+import { type PageProps, SeoHead } from '@crombolo/crombolo'
+
+export default function HomePage(props: PageProps) {
+  const { model } = props
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {/* The title, description and sharing tags, from the page's Search & sharing tab. */}
+        <SeoHead {...props} title={model.text('title')} />
+      </head>
+      <body>
+        <main>
+          <h1>{model.text('title')}</h1>
+          {/* Rich text is stored as HTML, so it is written out as HTML. */}
+          <div setInnerHTML={{ __html: model.text('bodyText'), dangerously: true }} />
+        </main>
+      </body>
+    </html>
+  )
+}

package/templates/basic/files/schema/content-types/home-page.toml

@@ -0,0 +1,28 @@
+[content-type]
+key = "b8188492-dc05-43e6-98bf-04ee758e4c17"
+alias = "homePage"
+name = "Home Page"
+description = "The site's landing page"
+icon = "icon-home"
+allow-at-root = true
+allow-children = ["homePage"]
+compositions = ["seoFields"]
+components = ["homePage"]
+default-component = "homePage"
+
+[[tab]]
+name = "Content"
+
+[[tab.property]]
+key = "41fc551c-4bc9-4a1e-acab-d3c8a11e35ff"
+alias = "title"
+name = "Title"
+description = "Shown as the page heading"
+type = "textstring"
+mandatory = true
+
+[[tab.property]]
+key = "f4b0420a-125c-49c6-863d-c40ad6f09703"
+alias = "bodyText"
+name = "Body"
+type = "richtext"

package/templates/basic/files/schema/schema.toml

@@ -0,0 +1,2 @@
+[schema]
+version = "1.0.0"

package/templates/basic/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "Basic",
+  "description": "a home page type, one view and one published page"
+}

package/templates/demo/harbourstone/CREDITS.md

@@ -0,0 +1,42 @@
+# Harbourstone demo site — image credits
+
+The Harbourstone site is distributed (`"distribute": true` in its `site.json`), so
+it is staged into `@crombolo/cli`'s `templates/` when the CLI is packed, and every
+binary in its bundle is **redistributed** to anyone who runs
+`crombolo init --template demo/harbourstone`. Each one therefore needs a recorded
+source and licence, and `tests/packaging.test.ts` asserts that none is missing
+from this file.
+
+| File | Source | Licence | Attribution |
+| --- | --- | --- | --- |
+| `bundles/demo-harbourstone/blobs/180cc8ef/distillery-from-the-cliff-path.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+| `bundles/demo-harbourstone/blobs/7b4713f8/copper-pot-stills.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+| `bundles/demo-harbourstone/blobs/fd337567/casks-in-the-sea-facing-warehouse.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+| `bundles/demo-harbourstone/blobs/6d8d6398/bottle-the-cove.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+| `bundles/demo-harbourstone/blobs/68c9cfdf/bottle-brine-and-kiln.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+| `bundles/demo-harbourstone/blobs/6be45535/bottle-oloroso-pier.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+| `bundles/demo-harbourstone/blobs/c114b7d8/bottle-neap-tide.jpg` | Generated with Grok (xAI), 5 October 2026 | No third-party rights | — |
+
+These are synthetic images of a distillery that does not exist. They depict no
+real place, product or person, and no photographer's work is being
+redistributed — which is the question this file exists to answer.
+
+## Where the originals live
+
+`assets/templates/harbourstone/` in this repository, at the size they ship at.
+That directory is **not** in the `files` list in `packages/cli/package.json`, so
+the photographs are published once, in the bundle, rather than twice.
+`bun run build:template demo/harbourstone` copies the bytes through untouched:
+re-encoding an already-compressed JPEG on every build would churn the committed
+bundle and lose a little more of the image each time.
+
+## Adding one
+
+Add a row. The test fails otherwise, which is the point: this is the kind of
+thing that is only ever noticed years later. Three ways to fill one in:
+
+1. **A stock source** (Unsplash, Pexels and the like) — record the URL, the
+   licence and the photographer, and satisfy any attribution the licence asks
+   for.
+2. **Generated** — record the tool and the date; nothing further is needed.
+3. **Origin unknown** — replace the image rather than ship it.