@crombolo/cli 0.14.4 → 0.16.0

package/src/commands/generate.ts

@@ -0,0 +1,33 @@
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { generateTypes, validateSchemaSet } from '@crombolo/schema'
+import { formTypesFor } from '@crombolo/server'
+import { BaseCommand } from '../base.ts'
+import { here } from '../support/describe.ts'
+import { siteConfig } from '../support/site.ts'
+import { loadTypes, refuseProblems } from '../support/types.ts'
+
+export default class Generate extends BaseCommand {
+  static override summary = 'TypeScript for the content types in schema/'
+  static override description = 'Writes schema/content-types.d.ts.'
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [{ name: 'wrote', type: 'string' }],
+    errors: ['refused'],
+  } as const
+
+  async run() {
+    await this.parse(Generate)
+    const config = await siteConfig()
+    const loaded = loadTypes(config)
+    refuseProblems([
+      ...loaded.problems,
+      ...validateSchemaSet(loaded.set, { types: formTypesFor(config) }),
+    ])
+    const target = join(config.schemaDir, 'content-types.d.ts')
+    await writeFile(target, generateTypes(loaded.set))
+    this.say(`  wrote  ${here(target)}`)
+    return { wrote: here(target) }
+  }
+}

package/src/commands/health.ts

@@ -0,0 +1,90 @@
+import {
+  bootstrapDatabase,
+  createDiagnosticsPort,
+  mediaStoreFor,
+  resolveEmailPort,
+} from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { siteConfig } from '../support/site.ts'
+
+/** The checks the Settings section's Health Check dashboard runs, for a monitor or a deploy to gate on. */
+export default class Health extends BaseCommand {
+  static override summary = "run the site's health checks"
+  static override description =
+    'The same checks as Settings › Health Check. Exits 20 when a check fails; a warning is reported, not counted.'
+  static override flags = {
+    group: Flags.string({ summary: 'only this group of checks', helpValue: '<name>' }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'bounded',
+    outputFields: [
+      {
+        name: 'groups',
+        type: 'array',
+        items: {
+          type: 'object',
+          fields: [
+            { name: 'name', type: 'string' },
+            { name: 'checks', type: 'array', items: { type: 'object' } },
+          ],
+        },
+      },
+      { name: 'failed', type: 'integer' },
+      { name: 'warnings', type: 'integer' },
+    ],
+    errors: ['not_found'],
+    outcomes: ['problems_found'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(Health)
+    const config = await siteConfig()
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const diagnostics = createDiagnosticsPort({
+        config,
+        db,
+        media: await mediaStoreFor(config),
+        email: resolveEmailPort(config),
+      })
+      const groups = diagnostics.groups()
+      const chosen = flags.group
+        ? groups.filter((group) => group.name.toLowerCase() === flags.group?.toLowerCase())
+        : groups
+      if (chosen.length === 0)
+        this.fail(
+          'not_found',
+          `There is no group "${flags.group}".`,
+          `The groups: ${groups.map((g) => g.name).join(', ')}.`,
+        )
+      let failed = 0
+      let warnings = 0
+      const report = []
+      for (const group of chosen) {
+        const results = (await diagnostics.run(group.name)) ?? []
+        const checks = group.checks.map((check) => {
+          const found = results.find((result) => result.id === check.id)?.results ?? []
+          for (const result of found) {
+            if (result.resultType === 'Error') failed += 1
+            if (result.resultType === 'Warning') warnings += 1
+          }
+          return {
+            name: check.name,
+            results: found.map((r) => ({ type: r.resultType, message: r.message })),
+          }
+        })
+        this.say(group.name)
+        for (const check of checks)
+          for (const result of check.results)
+            this.say(`  [${result.type.padEnd(7)}] ${check.name}: ${result.message}`)
+        report.push({ name: group.name, checks })
+      }
+      if (failed > 0) this.outcome = 'problems_found'
+      return { groups: report, failed, warnings }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/import/index.ts

@@ -0,0 +1,175 @@
+import { basename } from 'node:path'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import {
+  counted,
+  describeBundle,
+  describePlaced,
+  findingsOf,
+  here,
+  printTransferFindings,
+} from '../../support/describe.ts'
+import { backupTaken } from '../../support/flags.ts'
+import { confirm, passphraseForPeople, passphraseToOpen } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/**
+ * Replace this site with a whole-site file (story 105). It always says first
+ * what would be replaced, and changes nothing without `--replace` or
+ * `--replace-all`.
+ */
+export default class Import extends BaseCommand {
+  static override summary = 'replace this site with a whole-site file; says what first'
+  static override description = [
+    "Changes nothing without a mode. --replace recycles content and media the file lacks and keeps this site's people; --replace-all deletes them, and people the file lacks (typed confirmation, or --yes).",
+    'Domains, the secret key and settings always stay. Undone with `content revert <run>`.',
+  ].join('\n\n')
+  static override examples = [
+    '<%= config.bin %> import site.tgz',
+    '<%= config.bin %> import site.tgz --replace',
+  ]
+  static override args = {
+    file: Args.string({
+      required: true,
+      description: 'a whole-site file (crombolo export --site)',
+    }),
+  }
+  static override flags = {
+    replace: Flags.boolean({
+      summary: 'replace this site: what it loses is recycled, people kept',
+    }),
+    'replace-all': Flags.boolean({
+      summary: 'make it exactly the file: what it loses is deleted, people too',
+    }),
+    yes: Flags.boolean({ summary: "with --replace-all: don't ask" }),
+    'allow-missing-media': Flags.boolean({
+      summary: 'import media items whose files the file does not carry',
+    }),
+    'backup-taken': backupTaken,
+  }
+  static override audit = { category: 'content', action: 'Import', entityType: 'Bundle' } as const
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    confirmationBypassArg: '--yes',
+    outputFields: [
+      { name: 'bundle', type: 'object' },
+      { name: 'brings', type: 'object' },
+      { name: 'leaving', type: 'object' },
+      { name: 'filesRemoved', type: 'array', items: { type: 'string' } },
+      { name: 'runId', type: 'string', nullable: true },
+      { name: 'backup', type: 'string', nullable: true },
+    ],
+    errors: ['usage', 'confirmation_required', 'refused', 'auth', 'not_found'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(Import)
+    if (args.file === 'umbraco')
+      this.fail(
+        'usage',
+        'import umbraco needs report or apply.',
+        '`crombolo import umbraco --help` says more.',
+      )
+    const config = await siteConfig()
+    const replace: ops.ReplaceMode | undefined = flags['replace-all']
+      ? 'replace-all'
+      : flags.replace
+        ? 'replace'
+        : undefined
+    const dir = await ops.unpackBundle(args.file, config.siteDir)
+    const carriesPeople = ops.readBundle(dir, config.siteDir).set.manifest.people !== undefined
+    const passphrase = carriesPeople
+      ? await passphraseForPeople()
+      : await passphraseToOpen(dir, config)
+    const allowMissingBlobs = flags['allow-missing-media']
+
+    const { check, summary } = await ops.siteReplaceCheck(config, {
+      bundle: dir,
+      passphrase,
+      replace: replace ?? 'replace',
+      allowMissingBlobs,
+    })
+    describeBundle(this, check.bundle)
+    const c = check.check.counts
+    this.say(`  brings   ${c.create} new, ${c.update} changed, ${c.unchanged} unchanged`)
+    const fate = replace === 'replace-all' ? 'deleted' : 'recycled'
+    if (Object.keys(summary.leaving).length > 0)
+      this.say(`  ${fate.padEnd(8)} ${counted(summary.leaving)} not in the file`)
+    if (summary.filesRemoved.length > 0) {
+      this.say(
+        `  removes  ${summary.filesRemoved.length} file(s) not in the file, kept for a revert:`,
+      )
+      for (const path of summary.filesRemoved.slice(0, 20)) this.say(`    ${here(path)}`)
+      if (summary.filesRemoved.length > 20)
+        this.say(`    … and ${summary.filesRemoved.length - 20} more`)
+    }
+    if (replace === 'replace-all' && summary.people.members + summary.people.users > 0)
+      this.say(
+        `  deletes  ${summary.people.members} member(s) and ${summary.people.users} user(s) not in the file`,
+      )
+    this.say("  keeps    domains, the secret key and this environment's settings")
+    for (const problem of check.problems) this.warning(`  ${problem}`)
+    const result = {
+      bundle: check.bundle,
+      brings: c,
+      leaving: summary.leaving,
+      filesRemoved: summary.filesRemoved.map(here),
+      runId: null as string | null,
+      backup: null as string | null,
+    }
+
+    if (!replace)
+      this.fail(
+        'usage',
+        'Nothing was changed: a mode says how to replace this site.',
+        'Pass --replace (what it loses is recycled, people kept), or --replace-all to make it exactly the file (deleted, people too).',
+      )
+    if (replace === 'replace-all' && !flags.yes)
+      await confirm(
+        `  This deletes for good. Type the site's name (${config.siteName}) to go on:`,
+        {
+          bypass: '--yes',
+          answer: config.siteName,
+        },
+      )
+
+    const imported = await ops.contentImport(config, {
+      bundle: dir,
+      passphrase,
+      replace,
+      allowMissingBlobs,
+      label: `${replace} from ${basename(args.file)}`,
+      backupTaken: flags['backup-taken'],
+    })
+    for (const problem of imported.problems) this.warning(`  ${problem}`)
+    if (imported.backup.path) this.progress(`  backup   ${imported.backup.path}`)
+    if (!imported.runId) {
+      printTransferFindings(this, imported.check)
+      this.fail(
+        'refused',
+        'replace refused. Nothing was changed.',
+        undefined,
+        findingsOf(imported.check.outstanding),
+      )
+    }
+    const counts = imported.check.counts
+    this.say(`  run      ${imported.runId}`)
+    this.say(
+      `  applied  ${counts.create} created, ${counts.update} updated, ${counts.unchanged} unchanged`,
+    )
+    const placed = describePlaced(imported.blobs)
+    if (placed) this.say(`  media    ${placed}`)
+    if (imported.sections?.schema) this.say(`  schema   ${imported.sections.schema.action}`)
+    if (imported.published > 0) this.say(`  published ${imported.published} page(s)`)
+    for (const failure of imported.publishFailures)
+      this.warning(`  not published  ${failure.key}: ${failure.reason}`)
+    this.say(
+      replace === 'replace-all'
+        ? `\nDone. \`crombolo content revert ${imported.runId}\` puts the files and the pages it changed back; what was deleted is in the backup.`
+        : `\nDone. \`crombolo content revert ${imported.runId}\` puts it back.`,
+    )
+    return { ...result, runId: imported.runId, backup: imported.backup.path ?? null }
+  }
+}

package/src/commands/import/umbraco/apply.ts

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { writeDomainsFile, writeUdtAll } from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../../base.ts'
+import { here } from '../../../support/describe.ts'
+import { contentMode } from '../../../support/flags.ts'
+import { PASSPHRASE_ENV, passphraseToSeal } from '../../../support/prompt.ts'
+import {
+  deprecated,
+  loadImporter,
+  planUmbraco,
+  umbracoArgs,
+  umbracoFlags,
+} from '../../../support/umbraco.ts'
+import { scaffoldFiles } from '../../../templates.ts'
+
+export default class ImportUmbracoApply extends BaseCommand {
+  static override summary = 'write a crombolo site from an Umbraco backup'
+  static override description =
+    'Schema, view stubs, media and a content bundle that `bun start` imports on first boot. Deprecated: story 074 replaces it.'
+  static override args = umbracoArgs
+  static override flags = {
+    ...umbracoFlags,
+    out: Flags.string({
+      summary: 'the site directory to write',
+      helpValue: '<dir>',
+      required: true,
+    }),
+    postgres: Flags.boolean({ summary: 'configure Postgres' }),
+    force: Flags.boolean({ summary: 'write into a directory that is not empty' }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'wrote', type: 'integer' },
+      { name: 'out', type: 'string' },
+      { name: 'report', type: 'string' },
+      { name: 'sealed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused', 'conflict', 'auth'],
+    stability: 'deprecated',
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(ImportUmbracoApply)
+    deprecated(this, this.jsonEnabled())
+    const target = flags.out
+    const importer = await loadImporter()
+    const content = contentMode(this, flags)
+    const sealing = content === 'sealed' || flags['with-members'] || flags['with-users']
+    const plan = await planUmbraco(
+      importer,
+      args.backup,
+      flags,
+      content,
+      sealing ? await passphraseToSeal() : undefined,
+    )
+    const { report } = plan
+    if (!report.ready)
+      this.fail(
+        'refused',
+        'Nothing was written: something blocks the import.',
+        undefined,
+        report.findings
+          .filter((f) => f.class === 'blocking')
+          .map((f) => `${f.title}${f.detail ? `: ${f.detail}` : ''}`),
+      )
+    if (
+      existsSync(target) &&
+      (await Array.fromAsync(new Bun.Glob('*').scan({ cwd: target, onlyFiles: false, dot: true })))
+        .length > 0 &&
+      !flags.force
+    )
+      this.fail(
+        'conflict',
+        `${target} is not empty.`,
+        'Choose a new directory, or pass --force to write into it.',
+      )
+
+    const files = new Map<string, { text?: string; bytes?: Uint8Array; copyFrom?: string }>()
+    const scaffold = scaffoldFiles({
+      siteName: plan.siteName,
+      postgres: flags.postgres,
+      bundle: {
+        path: importer.IMPORT_BUNDLE,
+        // A media item whose file was not in the backup is reported, not refused.
+        flags: plan.missingMedia > 0 ? ['--allow-missing-blobs'] : [],
+      },
+    })
+    for (const file of scaffold) files.set(file.path, file)
+    // The importer's files win: the source site's media types replace the defaults.
+    for (const file of plan.files) files.set(file.path, file)
+    if (plan.dictionary.length > 0)
+      files.set(`${importer.IMPORT_DIR}/dictionary.udt`, { text: writeUdtAll(plan.dictionary) })
+    if (plan.domains.length > 0)
+      files.set(`${importer.IMPORT_DIR}/domains.toml`, { text: writeDomainsFile(plan.domains) })
+
+    for (const [path, file] of files) {
+      const destination = join(target, path)
+      await mkdir(join(destination, '..'), { recursive: true })
+      if (file.copyFrom !== undefined) await Bun.write(destination, Bun.file(file.copyFrom))
+      else await Bun.write(destination, file.bytes ?? file.text ?? '')
+    }
+
+    const reportFile = here(join(target, importer.IMPORT_DIR, 'report.md'))
+    for (const line of importer.reportSummary(report)) this.say(`  ${line}`)
+    this.say(`\n  wrote    ${files.size} files to ${here(target)}`)
+    this.say(`  report   ${reportFile}`)
+    this.say(`\nNext:\n  cd ${here(target)}\n  bun install\n  bun start`)
+    this.say(
+      `\n\`bun start\` imports ${importer.IMPORT_BUNDLE} on the first boot of an empty database.`,
+    )
+    if (sealing)
+      this.say(
+        `It is encrypted: \`bun start\` asks for the passphrase, or reads ${PASSPHRASE_ENV}.`,
+      )
+    if (content === 'omitted')
+      this.say(
+        'Pages and media were brought without what they hold. Run again with --include-content to bring it.',
+      )
+    if (plan.dictionary.length > 0)
+      this.say(`Then: crombolo dictionary import ${importer.IMPORT_DIR}/dictionary.udt`)
+    return { wrote: files.size, out: here(target), report: reportFile, sealed: sealing }
+  }
+}

package/src/commands/import/umbraco/report.ts

@@ -0,0 +1,56 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../../base.ts'
+import { here } from '../../../support/describe.ts'
+import {
+  deprecated,
+  loadImporter,
+  planUmbraco,
+  umbracoArgs,
+  umbracoFlags,
+} from '../../../support/umbraco.ts'
+
+export default class ImportUmbracoReport extends BaseCommand {
+  static override summary =
+    'read-only: what importing an Umbraco backup would bring, and what it would not'
+  static override description =
+    'Packages, Razor and custom code are reported, not brought. Exits 21 when something blocks the import. Deprecated: story 074 replaces it.'
+  static override args = umbracoArgs
+  static override flags = {
+    ...umbracoFlags,
+    out: Flags.string({ summary: 'also write report.md and report.json here', helpValue: '<dir>' }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    stdoutSchema: { type: 'object', description: "the importer's report" },
+    errors: ['not_found', 'refused'],
+    outcomes: ['blocked'],
+    stability: 'deprecated',
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(ImportUmbracoReport)
+    deprecated(this, this.jsonEnabled())
+    const importer = await loadImporter()
+    // A report writes no bundle, so what it would seal with is never kept.
+    const sealing = flags['with-members'] || flags['with-users']
+    const { report } = await planUmbraco(
+      importer,
+      args.backup,
+      flags,
+      flags['include-content'] ? 'open' : 'omitted',
+      sealing ? crypto.randomUUID() : undefined,
+    )
+    for (const line of importer.reportSummary(report)) this.say(`  ${line}`)
+    if (flags.out) {
+      await mkdir(flags.out, { recursive: true })
+      await writeFile(join(flags.out, 'report.md'), importer.reportMarkdown(report))
+      await writeFile(join(flags.out, 'report.json'), importer.reportJson(report))
+      this.say(`\n  wrote    ${here(join(flags.out, 'report.md'))}`)
+    }
+    if (!report.ready) this.outcome = 'blocked'
+    return JSON.parse(importer.reportJson(report)) as Record<string, unknown>
+  }
+}

package/src/commands/index/list.ts

@@ -0,0 +1,45 @@
+import { SEARCH_INDEXES, SearchIndex } from '@crombolo/data'
+import { bootstrapDatabase } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class IndexList extends BaseCommand {
+  static override summary = 'the search indexes: what each holds, and what is waiting to be indexed'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'bounded',
+    outputFields: [
+      { name: 'name', type: 'string' },
+      { name: 'documents', type: 'integer' },
+      { name: 'fields', type: 'integer' },
+      { name: 'pending', type: 'integer' },
+      { name: 'healthy', type: 'boolean', description: 'nothing waiting to be indexed' },
+    ],
+  } as const
+
+  async run() {
+    await this.parse(IndexList)
+    const { db } = await bootstrapDatabase(await siteConfig())
+    try {
+      const search = new SearchIndex(db)
+      const items = []
+      for (const index of SEARCH_INDEXES) {
+        const stats = await search.stats(index)
+        items.push({
+          name: index.name,
+          documents: stats.documentCount,
+          fields: stats.fieldCount,
+          pending: stats.pending,
+          healthy: stats.pending === 0,
+        })
+      }
+      for (const index of items)
+        this.say(
+          `  ${index.name.padEnd(14)} ${index.documents} item(s), ${index.fields} field(s)${index.pending > 0 ? `, ${index.pending} waiting` : ''}`,
+        )
+      return { items }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/index/rebuild.ts

@@ -0,0 +1,66 @@
+import { SEARCH_INDEXES, SearchIndex } from '@crombolo/data'
+import { bootstrapDatabase } from '@crombolo/server'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/**
+ * The index lives in the database, so rebuilding it here rebuilds it for every
+ * node: there is no copy per server to reach. Search keeps answering from the
+ * old entries while each item is indexed again.
+ */
+export default class IndexRebuild extends BaseCommand {
+  static override summary = 'index every item again, for every node: the index is in the database'
+  static override description =
+    'Search keeps answering while it runs. --queue-only queues everything and leaves the indexing to the running site.'
+  static override args = {
+    index: Args.string({
+      description: 'one index; both when not given',
+      options: SEARCH_INDEXES.map((index) => index.name),
+    }),
+  }
+  static override flags = {
+    'queue-only': Flags.boolean({ summary: 'queue everything, and let the site index it' }),
+  }
+  static override audit = {
+    category: 'system',
+    action: 'RebuildIndex',
+    entityType: 'Index',
+  } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'indexes', type: 'array', items: { type: 'string' } },
+      { name: 'indexed', type: 'integer', description: 'items indexed here; 0 with --queue-only' },
+      { name: 'queued', type: 'boolean' },
+    ],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(IndexRebuild)
+    const chosen = SEARCH_INDEXES.filter((index) => !args.index || index.name === args.index)
+    this.auditKey = args.index
+    const { db } = await bootstrapDatabase(await siteConfig())
+    try {
+      const search = new SearchIndex(db)
+      for (const index of chosen) await search.rebuild(index)
+      const names = chosen.map((index) => index.name)
+      if (flags['queue-only']) {
+        this.say(`  queued   ${names.join(', ')}: the running site indexes it`)
+        return { indexes: names, indexed: 0, queued: true }
+      }
+      let indexed = 0
+      for (;;) {
+        const batch = await search.indexQueued()
+        if (batch === 0) break
+        indexed += batch
+        this.progress(`  indexed  ${indexed}`)
+      }
+      this.say(`  rebuilt  ${names.join(', ')}: ${indexed} item(s) indexed`)
+      return { indexes: names, indexed, queued: false }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { cwd } from '../support/site.ts'
+import { findTemplate, listTemplates, scaffoldFiles } from '../templates.ts'
+
+export default class Init extends BaseCommand {
+  static override summary = 'scaffold a site in the current directory'
+  static override description =
+    'A --template brings schema, views and content; `--template list` prints the templates.'
+  static override examples = ['<%= config.bin %> init', '<%= config.bin %> init --template list']
+  static override flags = {
+    force: Flags.boolean({ summary: 'overwrite files that are already here' }),
+    name: Flags.string({ summary: "the site's name", helpValue: '<site name>' }),
+    postgres: Flags.boolean({ summary: 'configure Postgres rather than SQLite' }),
+    template: Flags.string({ summary: 'a starter template, or `list`', helpValue: '<id>' }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'bounded',
+    outputFields: [
+      { name: 'created', type: 'array', items: { type: 'string' } },
+      { name: 'existing', type: 'array', items: { type: 'string' } },
+      { name: 'templates', type: 'array', items: { type: 'object' } },
+    ],
+    errors: ['not_found'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(Init)
+    if (flags.template === 'list') {
+      const templates = listTemplates().map((t) => ({ id: t.id, description: t.description }))
+      for (const t of templates) this.say(`  ${t.id.padEnd(20)} ${t.description}`)
+      this.say('\n  (no --template scaffolds the files and no content)')
+      this.changedNothing = true
+      return { created: [], existing: [], templates }
+    }
+    const template = flags.template ? findTemplate(flags.template) : undefined
+    if (flags.template && !template)
+      this.fail(
+        'not_found',
+        `No template "${flags.template}".`,
+        '`crombolo init --template list` prints them.',
+      )
+
+    const created: string[] = []
+    const existing: string[] = []
+    for (const file of scaffoldFiles({
+      siteName: flags.name,
+      postgres: flags.postgres,
+      template,
+    })) {
+      const target = join(cwd(), file.path)
+      if (existsSync(target) && !flags.force) {
+        existing.push(file.path)
+        this.say(`  exists   ${file.path}`)
+        continue
+      }
+      await mkdir(join(target, '..'), { recursive: true })
+      if (file.copyFrom === undefined) await writeFile(target, file.text ?? '')
+      else await Bun.write(target, Bun.file(file.copyFrom))
+      created.push(file.path)
+      this.say(`  created  ${file.path}`)
+    }
+
+    this.say('\nNext:\n  bun install\n  bun start')
+    if (template?.bundle)
+      this.say(
+        `\n\`bun start\` imports ${template.bundle} on the first boot of an empty database,\n` +
+          'and says so. Nothing happens on later boots; it is one line in package.json.',
+      )
+    return { created, existing, templates: [] }
+  }
+}