@crombolo/cli 0.16.0 → 0.18.0

package/oclif.manifest.json

@@ -1152,6 +1152,10 @@
           {
             "name": "template",
             "type": "boolean"
+          },
+          {
+            "name": "email",
+            "type": "boolean"
           }
         ],
         "errors": [
@@ -8073,5 +8077,5 @@
       ]
     }
   },
-  "version": "0.16.0"
+  "version": "0.18.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/cli",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "The crombolo command line: scaffolding a site, schema, views, domains, content transfer and upgrades.",
   "license": "MIT",
   "author": "Crombolo",
@@ -36,13 +36,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/api-management": "0.16.0",
-    "@crombolo/auth": "0.16.0",
-    "@crombolo/core": "0.16.0",
-    "@crombolo/data": "0.16.0",
-    "@crombolo/schema": "0.16.0",
-    "@crombolo/server": "0.16.0",
-    "@crombolo/transfer": "0.16.0",
+    "@crombolo/api-management": "0.18.0",
+    "@crombolo/auth": "0.18.0",
+    "@crombolo/core": "0.18.0",
+    "@crombolo/data": "0.18.0",
+    "@crombolo/schema": "0.18.0",
+    "@crombolo/server": "0.18.0",
+    "@crombolo/transfer": "0.18.0",
     "@oclif/core": "^5.1.8"
   },
   "oclif": {

package/src/classify.ts

@@ -3,7 +3,7 @@
  * code and the envelope follow from one table.
  */
 import { MigrationStepError, UpgradeStateError } from '@crombolo/data'
-import { CommandError, PassphraseError } from '@crombolo/server'
+import { CommandError, PassphraseError, setting } from '@crombolo/server'
 import { CliError, ERROR_KINDS, type ErrorKind } from './errors.ts'
 import { RemoteError, TimedOut } from './remote/client.ts'
 
@@ -84,7 +84,7 @@ export function classify(error: unknown): CliError {
   if (typeof code === 'string' && SYSTEM_CODES[code])
     return new CliError(SYSTEM_CODES[code], (error as Error).message)
   return new CliError('internal', error instanceof Error ? error.message : String(error), {
-    details: process.env.CROMBOLO_DEBUG && error instanceof Error ? error.stack : undefined,
+    details: setting('CROMBOLO_DEBUG') && error instanceof Error ? error.stack : undefined,
   })
 }
 

package/src/commands/components/new.ts

@@ -2,10 +2,16 @@ import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { viewScaffold } from '@crombolo/schema'
-import { componentFileFor, componentScaffold, isSafeAlias } from '@crombolo/server'
+import {
+  componentFileFor,
+  componentScaffold,
+  EMAIL_FOLDER,
+  emailScaffold,
+  isSafeAlias,
+} from '@crombolo/server'
 import { Args } from '@oclif/core'
 import { BaseCommand } from '../../base.ts'
-import { declaredTypes } from '../../support/components.ts'
+import { declaredTypes, formsNamingEmailTemplate } from '../../support/components.ts'
 import { here } from '../../support/describe.ts'
 import { siteConfig } from '../../support/site.ts'
 
@@ -21,6 +27,7 @@ export default class ComponentsNew extends BaseCommand {
     outputFields: [
       { name: 'created', type: 'string' },
       { name: 'template', type: 'boolean' },
+      { name: 'email', type: 'boolean' },
     ],
     errors: ['usage', 'conflict'],
   } as const
@@ -33,17 +40,25 @@ export default class ComponentsNew extends BaseCommand {
     const file = componentFileFor(config.componentsDir, args.alias)
     if (existsSync(file)) this.fail('conflict', `${here(file)} already exists.`)
     // A content type that names this alias gets the page scaffold, which takes
-    // PageProps; anything else gets the plain one. Nothing turns on the folder.
+    // PageProps; one in emails/, or one a form's Send email names, gets the
+    // e-mail one, which takes EmailProps; anything else gets the plain one.
     const type = declaredTypes(config).find((candidate) =>
       candidate.components.includes(args.alias),
     )
-    if (!type)
+    const email =
+      !type &&
+      (args.alias.startsWith(EMAIL_FOLDER) ||
+        formsNamingEmailTemplate(config, args.alias).length > 0)
+    if (!type && !email)
       this.say(
         `  note     no content type declares the template "${args.alias}" — add it to one's templates, or \`crombolo types new\``,
       )
     await mkdir(join(file, '..'), { recursive: true })
-    await writeFile(file, type ? viewScaffold(type) : componentScaffold(args.alias))
+    await writeFile(
+      file,
+      type ? viewScaffold(type) : email ? emailScaffold(args.alias) : componentScaffold(args.alias),
+    )
     this.say(`  created  ${here(file)}`)
-    return { created: here(file), template: Boolean(type) }
+    return { created: here(file), template: Boolean(type), email }
   }
 }

package/src/operations/commands.ts

@@ -67,6 +67,7 @@ import {
   replaceSummary,
   type SiteExportOptions,
   type SiteExportResult,
+  setting,
   syncOptionsFor,
   type TransferInput,
   useSchemaStore,
@@ -723,7 +724,7 @@ export interface CommandAudit {
  * Never fails the command: what it records has already happened.
  */
 export async function recordCommand(config: CromboloConfig, entry: CommandAudit): Promise<void> {
-  let actor = Bun.env.CROMBOLO_ACTOR
+  let actor = setting('CROMBOLO_ACTOR')
   try {
     actor ??= userInfo().username
   } catch {

package/src/reference.ts

@@ -1,7 +1,7 @@
 /**
- * The command line reference as HTML, for the product site's developer pages:
- * built from the CLI manifest's data, through the same clispec description
- * `crombolo schema` prints, so the page cannot say anything the CLI does not.
+ * The command line reference as HTML, for the product site's docs: built from
+ * the CLI manifest's data, through the same clispec description
+ * `crombolo schema` prints, so the pages cannot say anything the CLI does not.
  */
 import type { Interfaces } from '@oclif/core'
 import { clispecDocument } from './clispec.ts'
@@ -25,6 +25,73 @@ interface Arg {
   description?: string
 }
 
+/** One page of the reference: the topics, by the first word of a command, it covers. */
+export interface CliPageSpec {
+  slug: string
+  title: string
+  summary: string
+  topics: readonly string[]
+}
+
+/** Where each topic is documented. A new topic has to be placed here, or the reference test fails. */
+export const CLI_PAGES: readonly CliPageSpec[] = [
+  {
+    slug: 'sites',
+    title: 'Sites',
+    summary: 'Create a site, start it, check on it, and describe the command line to a script.',
+    topics: ['init', 'start', 'status', 'health', 'generate', 'export', 'schema'],
+  },
+  {
+    slug: 'types',
+    title: 'Content types',
+    summary: 'Check, apply and change the content model kept in schema/.',
+    topics: ['types'],
+  },
+  {
+    slug: 'components',
+    title: 'Components and assets',
+    summary:
+      'Create and check the templates under components/, and the styles and scripts beside them.',
+    topics: ['components', 'assets'],
+  },
+  {
+    slug: 'content',
+    title: 'Content and media',
+    summary: 'Pages, media, the dictionary, domains and the recycle bin.',
+    topics: ['content', 'media', 'dictionary', 'domains', 'recycle-bin'],
+  },
+  {
+    slug: 'remotes',
+    title: 'Remotes, pull and push',
+    summary: 'Sign in to another environment, and move content and schema between them.',
+    topics: ['login', 'logout', 'whoami', 'remote', 'pull', 'push', 'bundle'],
+  },
+  {
+    slug: 'import',
+    title: 'Importing from Umbraco',
+    summary: 'Bring an Umbraco site’s content types, content and media across.',
+    topics: ['import'],
+  },
+  {
+    slug: 'users',
+    title: 'Users and access',
+    summary: 'Back office users, the administrator’s password and API clients.',
+    topics: ['users', 'admin', 'api-client'],
+  },
+  {
+    slug: 'operations',
+    title: 'Operations',
+    summary: 'Caches, the search index, maintenance pauses and upgrades.',
+    topics: ['cache', 'index', 'maintenance', 'upgrade'],
+  },
+]
+
+export interface CliReferencePage extends CliPageSpec {
+  html: string
+  /** The commands on the page, as typed: `content publish`. */
+  commands: string[]
+}
+
 function usage(name: string, args: Arg[]): string {
   const words = args.map((arg) => {
     if (!arg.name.startsWith('--')) return arg.required ? `<${arg.name}>` : `[<${arg.name}>]`
@@ -61,58 +128,128 @@ const EFFECTS: Record<string, string> = {
   non_idempotent: 'Each run acts again.',
 }
 
-/** The reference, grouped by the first word of each command. */
-export function cliReferenceHtml(manifest: Interfaces.Manifest): string {
-  const document = clispecDocument({
+const documentOf = (manifest: Interfaces.Manifest) =>
+  clispecDocument({
     bin: 'crombolo',
     version: manifest.version,
     commands: Object.values(manifest.commands),
   })
-  const groups = new Map<string, typeof document.commands>()
-  for (const command of document.commands) {
-    const group = String(command.name).split(' ')[0] as string
-    groups.set(group, [...(groups.get(group) ?? []), command])
-  }
-  const parts: string[] = [
-    '<p>Every command, generated from the CLI itself. Each takes ' +
-      `${code('--help')} for this page's entry, and ${code('-o json')} for a result a script can read. ` +
-      `${code('crombolo schema')} prints the same description for a machine, as a ` +
-      '<a href="https://clispec.dev">clispec</a> document.</p>',
+
+type Command = ReturnType<typeof documentOf>['commands'][number]
+
+const topicOf = (command: Command) => String(command.name).split(' ')[0] as string
+
+/** The anchor a command has on its page: `content publish` → `content-publish`. */
+export const commandAnchor = (name: string): string => name.replaceAll(' ', '-')
+
+function commandHtml(command: Command): string {
+  const name = String(command.name)
+  const args = ((command.args as Arg[] | undefined) ?? []).slice()
+  const parts = [
+    `<h2 id="${escapeHtml(commandAnchor(name))}">${code(`crombolo ${name}`)}</h2>`,
+    `<p>${escapeHtml(sentence(String(command.description)))} ${EFFECTS[String(command.effects)] ?? ''}</p>`,
+    `<pre><code>${escapeHtml(usage(name, args))}</code></pre>`,
   ]
-  for (const [group, commands] of groups) {
-    parts.push(`<h2 id="${escapeHtml(group)}">${escapeHtml(group)}</h2>`)
-    for (const command of commands) {
-      const name = String(command.name)
-      const args = ((command.args as Arg[] | undefined) ?? []).slice()
-      parts.push(
-        `<h3 id="${escapeHtml(name.replaceAll(' ', '-'))}">${code(`crombolo ${name}`)}</h3>`,
-      )
-      parts.push(
-        `<p>${escapeHtml(sentence(String(command.description)))} ${EFFECTS[String(command.effects)] ?? ''}</p>`,
-      )
-      parts.push(`<pre><code>${escapeHtml(usage(name, args))}</code></pre>`)
-      if (args.length > 0)
-        parts.push(
-          `<table><thead><tr><th>Argument</th><th>What it is</th></tr></thead><tbody>${args.map(argRow).join('')}</tbody></table>`,
+  if (args.length > 0)
+    parts.push(
+      `<table><thead><tr><th>Argument</th><th>What it is</th></tr></thead><tbody>${args.map(argRow).join('')}</tbody></table>`,
+    )
+  return parts.join('\n')
+}
+
+/** The topics no page in `CLI_PAGES` covers. */
+export function unplacedTopics(manifest: Interfaces.Manifest): string[] {
+  const placed = new Set(CLI_PAGES.flatMap((page) => page.topics))
+  return [...new Set(documentOf(manifest).commands.map(topicOf))].filter((t) => !placed.has(t))
+}
+
+/**
+ * One page per entry in `CLI_PAGES`, in its order. A topic no page names — a
+ * plugin's, say — gets a page of its own after them, so nothing is dropped.
+ */
+export function cliReferencePages(manifest: Interfaces.Manifest): CliReferencePage[] {
+  const commands = documentOf(manifest).commands
+  const specs = [
+    ...CLI_PAGES,
+    ...unplacedTopics(manifest).map((topic) => ({
+      slug: topic,
+      title: topic,
+      summary: `The ${topic} commands.`,
+      topics: [topic],
+    })),
+  ]
+  return specs
+    .map((spec) => {
+      const on = spec.topics.flatMap((topic) => commands.filter((c) => topicOf(c) === topic))
+      return {
+        ...spec,
+        commands: on.map((c) => String(c.name)),
+        html: on.map(commandHtml).join('\n'),
+      }
+    })
+    .filter((page) => page.commands.length > 0)
+}
+
+/** The front page of the reference: what every command shares, then each page and its commands. */
+export function cliIndexHtml(pages: readonly CliReferencePage[], base: string): string {
+  const parts = [
+    `<p>Every command, generated from the CLI itself. Each takes ${code('--help')} for its entry ` +
+      `here, and ${code('-o json')} for a result a script can read. ${code('crombolo schema')} prints ` +
+      'the same description for a machine, as a <a href="https://clispec.dev">clispec</a> document. ' +
+      'A command that fails exits with a code saying why: see the <a href="/docs/reference/exit-codes/">exit codes</a>.</p>',
+  ]
+  for (const page of pages) {
+    const url = `${base}${page.slug}/`
+    parts.push(
+      `<h2 id="${escapeHtml(page.slug)}"><a href="${url}">${escapeHtml(page.title)}</a></h2>`,
+    )
+    parts.push(`<p>${escapeHtml(page.summary)}</p>`)
+    parts.push(
+      `<ul>${page.commands
+        .map(
+          (name) =>
+            `<li><a href="${url}#${commandAnchor(name)}">${code(`crombolo ${name}`)}</a></li>`,
         )
-    }
+        .join('')}</ul>`,
+    )
   }
-  parts.push('<h2 id="exit-codes">Exit codes</h2>')
-  parts.push(
-    `<p>A failure exits with its kind's code; with ${code('-o json')}, or whenever stderr is not a terminal, ` +
-      "the last line of stderr is a JSON envelope naming the kind. A check that finds what it looks for exits with an outcome's code, and its findings are its output.</p>",
-  )
+  return parts.join('\n')
+}
+
+/** The exit codes and the error envelope, from the CLI's own list. */
+export function exitCodesHtml(manifest: Interfaces.Manifest): string {
+  const document = documentOf(manifest)
   const rows = [
     ...document.errors.map((e) => [String(e.exit_code), e.kind, e.description] as const),
     ...document.outcomes.map((o) => [String(o.code), o.name, o.description] as const),
   ].sort((a, b) => Number(a[0]) - Number(b[0]))
-  parts.push(
+  return [
+    '<h2 id="codes">The codes</h2>',
+    `<p>A command that succeeds exits with ${code('0')}. A failure exits with its kind's code, and a ` +
+      "check that finds what it looks for exits with an outcome's code, its findings being its output.</p>",
     `<table><thead><tr><th>Code</th><th>Kind</th><th>When</th></tr></thead><tbody>${rows
       .map(
         ([codeNumber, kind, description]) =>
           `<tr><td>${codeNumber}</td><td>${code(kind)}</td><td>${escapeHtml(description).replaceAll(/`([^`]+)`/g, '<code>$1</code>')}</td></tr>`,
       )
       .join('')}</tbody></table>`,
-  )
-  return parts.join('\n')
+    '<h2 id="envelope">The error envelope</h2>',
+    `<p>With ${code('-o json')}, or whenever stderr is not a terminal, the last line of stderr is a JSON ` +
+      'object naming the kind, so a script can tell a missing page from a refused one without reading the message.</p>',
+    `<pre><code>${escapeHtml(
+      JSON.stringify(
+        {
+          error: {
+            kind: 'not_found',
+            message: 'There is no page at /about/team.',
+            hint: "Check the page's path or key.",
+            exit_code: 5,
+          },
+        },
+        null,
+        2,
+      ),
+    )}</code></pre>`,
+    `<p>${code('hint')}, ${code('details')} and ${code('retryable')} appear only when there is something to say.</p>`,
+  ].join('\n')
 }

package/src/support/components.ts

@@ -1,7 +1,17 @@
-/** The content types a site declares, which say which components are templates. */
+/** The content types and forms a site declares, which say which components are templates. */
 import { existsSync } from 'node:fs'
 import type { CromboloConfig } from '@crombolo/server'
 import { loadTypes } from './types.ts'
 
 export const declaredTypes = (config: CromboloConfig) =>
   existsSync(config.schemaDir) ? loadTypes(config).set.contentTypes : []
+
+/** The forms whose Send email workflow names `alias` as its e-mail template. */
+export const formsNamingEmailTemplate = (config: CromboloConfig, alias: string) =>
+  existsSync(config.schemaDir)
+    ? (loadTypes(config).set.forms ?? []).filter((form) =>
+        form.workflows.some(
+          (workflow) => workflow.type === 'sendEmail' && workflow.settings.template === alias,
+        ),
+      )
+    : []

package/src/support/prompt.ts

@@ -4,7 +4,7 @@
  * confirmation refuses at once, naming the flag that answers it, and never
  * reads stdin.
  */
-import type { CromboloConfig } from '@crombolo/server'
+import { type CromboloConfig, setting } from '@crombolo/server'
 import { CliError } from '../errors.ts'
 import * as ops from '../operations/commands.ts'
 
@@ -83,7 +83,7 @@ export async function passphraseToOpen(
   target: string,
   config: CromboloConfig,
 ): Promise<string | undefined> {
-  const given = process.env[PASSPHRASE_ENV]
+  const given = setting(PASSPHRASE_ENV)
   if (given) return given
   let sealed = false
   try {
@@ -100,14 +100,14 @@ export async function passphraseToOpen(
 /** The passphrase for the people a file carries: the environment's, asked for, or none. */
 export async function passphraseForPeople(): Promise<string | undefined> {
   return (
-    process.env[PASSPHRASE_ENV] ??
+    setting(PASSPHRASE_ENV) ??
     (interactive() ? await readSecret('  Passphrase for its people: ') : undefined)
   )
 }
 
 /** A new passphrase to seal an export with: the environment's, or asked for twice. */
 export async function passphraseToSeal(): Promise<string> {
-  const given = process.env[PASSPHRASE_ENV]
+  const given = setting(PASSPHRASE_ENV)
   if (given) {
     if (given.length < MIN_PASSPHRASE)
       throw new CliError('usage', `${PASSPHRASE_ENV} is shorter than ${MIN_PASSPHRASE} characters.`)

package/src/support/publish.ts

@@ -14,7 +14,7 @@ import {
   describeRefFailure,
   resolveNodeRef,
 } from '@crombolo/data'
-import { bootstrapDatabase } from '@crombolo/server'
+import { bootstrapDatabase, createContentNotifier, resolveEmailPort } from '@crombolo/server'
 import { Args, Flags } from '@oclif/core'
 import { CliError } from '../errors.ts'
 import { many } from './flags.ts'
@@ -124,12 +124,19 @@ export async function publishPages(
         )
     }
 
+    // The people who asked to hear of a publish here hear of this one too (story 045).
+    const notifier = createContentNotifier(db, { canSend: Boolean(resolveEmailPort(config)) })
     for (const node of targets) {
       const result = publishing
         ? await docs.publish(node.key, cultures.length > 0 ? cultures : null)
         : await docs.unpublish(node.key, cultures.length > 0 ? cultures : null)
       items.push({ key: node.key, name: node.text ?? node.key, changed: Boolean(result) })
       if (!result) continue
+      if (publishing)
+        await notifier.raise(
+          { actions: ['Umb.Document.Publish'], key: node.key, keyKind: 'document' },
+          { key: null, name: 'The command line' },
+        )
       io.say(`  ${publishing ? 'published' : 'unpublished'} ${node.text ?? node.key}`)
     }
     io.say(

package/src/support/serve.ts

@@ -23,6 +23,7 @@ import {
   mediaStoreFor,
   placeBlobs,
   type ServerHandle,
+  setting,
 } from '@crombolo/server'
 import { importBundle } from '@crombolo/transfer'
 import { CliError } from '../errors.ts'
@@ -199,7 +200,7 @@ export async function serveSite(io: Io, options: StartOptions): Promise<Started>
  * platform's restart policy and alerts take over. docs/operations.md.
  */
 async function bootWithRetries(io: Io, config: CromboloConfig, options: StartOptions) {
-  const attempts = Math.max(1, Number(Bun.env.CROMBOLO_BOOT_ATTEMPTS ?? 10) || 10)
+  const attempts = Math.max(1, Number(setting('CROMBOLO_BOOT_ATTEMPTS') ?? 10) || 10)
   const delays = bootRetryDelays(attempts)
   let failure: BootFailure | undefined
   let progress = { attempt: 1, attempts, retryInSeconds: undefined as number | undefined }

package/src/templates.ts

@@ -17,7 +17,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { siteMediaTypeFiles } from '@crombolo/schema'
-import { VERSION } from '@crombolo/server'
+import { setting, VERSION } from '@crombolo/server'
 
 /**
  * `templates/`, beside `src/` and `bin/` in the published package.
@@ -25,7 +25,7 @@ import { VERSION } from '@crombolo/server'
  * without writing into the package that other runs read.
  */
 export const TEMPLATES_DIR =
-  process.env.CROMBOLO_TEMPLATES_DIR || join(import.meta.dir, '..', 'templates')
+  setting('CROMBOLO_TEMPLATES_DIR') || join(import.meta.dir, '..', 'templates')
 
 /**
  * A bundle whose server half a template wires into the site it scaffolds: the

package/templates/basic/bundle/package.json

@@ -6,7 +6,7 @@
     "content"
   ],
   "peerDependencies": {
-    "@crombolo/crombolo": ">=0.16.0"
+    "@crombolo/crombolo": ">=0.18.0"
   },
   "crombolo": {
     "id": "basic",

package/templates/demo/harbourstone/bundle/package.json

@@ -6,7 +6,7 @@
     "content"
   ],
   "peerDependencies": {
-    "@crombolo/crombolo": ">=0.16.0"
+    "@crombolo/crombolo": ">=0.18.0"
   },
   "crombolo": {
     "id": "demo-harbourstone",

package/templates/starter/bundle/package.json

@@ -6,7 +6,7 @@
     "content"
   ],
   "peerDependencies": {
-    "@crombolo/crombolo": ">=0.16.0"
+    "@crombolo/crombolo": ">=0.18.0"
   },
   "crombolo": {
     "id": "starter",