@crombolo/server 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/server",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The crombolo HTTP server: routing, configuration, media stores and background jobs.",
   "license": "MIT",
   "author": "Crombolo",
@@ -30,17 +30,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/api-delivery": "0.17.0",
-    "@crombolo/api-management": "0.17.0",
-    "@crombolo/assistant": "0.17.0",
-    "@crombolo/auth": "0.17.0",
-    "@crombolo/backoffice-host": "0.17.0",
-    "@crombolo/contracts": "0.17.0",
-    "@crombolo/core": "0.17.0",
-    "@crombolo/data": "0.17.0",
-    "@crombolo/render": "0.17.0",
-    "@crombolo/schema": "0.17.0",
-    "@crombolo/transfer": "0.17.0",
+    "@crombolo/api-delivery": "0.18.0",
+    "@crombolo/api-management": "0.18.0",
+    "@crombolo/assistant": "0.18.0",
+    "@crombolo/auth": "0.18.0",
+    "@crombolo/backoffice-host": "0.18.0",
+    "@crombolo/contracts": "0.18.0",
+    "@crombolo/core": "0.18.0",
+    "@crombolo/data": "0.18.0",
+    "@crombolo/render": "0.18.0",
+    "@crombolo/schema": "0.18.0",
+    "@crombolo/transfer": "0.18.0",
     "@logtape/logtape": "^2.3.8"
   }
 }

package/src/components.ts

@@ -230,10 +230,13 @@ export default function ${name}({ form, fields, site }: EmailProps) {
 `
 }
 
+/** The folder e-mail templates live in, as an alias prefix. */
+export const EMAIL_FOLDER = 'emails/'
+
 /**
- * The components the forms designer offers as e-mail designs: those written
- * over `EmailProps`, and any a form already names, so a picker never loses the
- * one that is set. A layout takes `EmailLayoutProps`, so it is not offered.
+ * The components the forms designer offers as e-mail designs: those in
+ * `components/emails/`, and any a form already names, so a picker never loses
+ * the one that is set. A layout there takes `EmailLayoutProps`, so it is not offered.
  */
 export function listEmailTemplates(
   root: string,
@@ -242,7 +245,11 @@ export function listEmailTemplates(
   const components = listComponents(root)
   const found = new Set<string>()
   for (const component of components)
-    if (/\bEmailProps\b/.test(readFileSync(component.path, 'utf8'))) found.add(component.alias)
+    if (
+      component.alias.startsWith(EMAIL_FOLDER) &&
+      !/\bEmailLayoutProps\b/.test(readFileSync(component.path, 'utf8'))
+    )
+      found.add(component.alias)
   const present = new Set(components.map((component) => component.alias))
   for (const alias of named) if (present.has(alias)) found.add(alias)
   const items = [...found].sort().map((alias) => ({ alias, name: readableName(alias) }))

package/src/config.ts

@@ -14,6 +14,7 @@ import type { GitConfig } from './git-routes.ts'
 import { checkIdentityProviders, type IdentityProvider } from './identity-providers.ts'
 import type { MediaStore } from './media-store.ts'
 import type { SchemaStore } from './schema-store.ts'
+import { setting } from './settings.ts'
 
 /**
  * Runtime settings for a site. Umbraco's equivalents live in appsettings.json;
@@ -497,11 +498,11 @@ export function loadConfig(
   cwd = process.cwd(),
 ): CromboloConfig {
   const fromEnv: CromboloConfig = {
-    port: Number(Bun.env.PORT ?? DEFAULTS.port),
-    maxRequestBodyBytes: Bun.env.CROMBOLO_MAX_REQUEST_BODY_MB
-      ? Number(Bun.env.CROMBOLO_MAX_REQUEST_BODY_MB) * 1024 * 1024
+    port: Number(setting('PORT') ?? DEFAULTS.port),
+    maxRequestBodyBytes: setting('CROMBOLO_MAX_REQUEST_BODY_MB')
+      ? Number(setting('CROMBOLO_MAX_REQUEST_BODY_MB')) * 1024 * 1024
       : DEFAULTS.maxRequestBodyBytes,
-    backOfficePath: Bun.env.CROMBOLO_BACKOFFICE_PATH ?? DEFAULTS.backOfficePath,
+    backOfficePath: setting('CROMBOLO_BACKOFFICE_PATH') ?? DEFAULTS.backOfficePath,
     defaultUiLanguage: DEFAULTS.defaultUiLanguage,
     keepUserLoggedIn: DEFAULTS.keepUserLoggedIn,
     allowLocalLogin: DEFAULTS.allowLocalLogin,
@@ -509,135 +510,135 @@ export function loadConfig(
     versionCheckPeriod: DEFAULTS.versionCheckPeriod,
     umbracoCssPath: DEFAULTS.umbracoCssPath,
     signalRSkipNegotiation: DEFAULTS.signalRSkipNegotiation,
-    development: Bun.env.NODE_ENV !== 'production',
-    sqliteFile: Bun.env.CROMBOLO_SQLITE_FILE ?? DEFAULTS.sqliteFile,
-    adminLogin: Bun.env.CROMBOLO_ADMIN_LOGIN ?? DEFAULTS.adminLogin,
-    adminPassword: Bun.env.CROMBOLO_ADMIN_PASSWORD,
+    development: setting('NODE_ENV') !== 'production',
+    sqliteFile: setting('CROMBOLO_SQLITE_FILE') ?? DEFAULTS.sqliteFile,
+    adminLogin: setting('CROMBOLO_ADMIN_LOGIN') ?? DEFAULTS.adminLogin,
+    adminPassword: setting('CROMBOLO_ADMIN_PASSWORD'),
     apiClient:
-      Bun.env.CROMBOLO_API_CLIENT_ID || Bun.env.CROMBOLO_API_CLIENT_SECRET
+      setting('CROMBOLO_API_CLIENT_ID') || setting('CROMBOLO_API_CLIENT_SECRET')
         ? {
-            id: Bun.env.CROMBOLO_API_CLIENT_ID ?? '',
-            secret: Bun.env.CROMBOLO_API_CLIENT_SECRET ?? '',
+            id: setting('CROMBOLO_API_CLIENT_ID') ?? '',
+            secret: setting('CROMBOLO_API_CLIENT_SECRET') ?? '',
           }
         : undefined,
-    localAdmin: Bun.env.CROMBOLO_LOCAL_ADMIN === 'true',
-    setupCode: Bun.env.CROMBOLO_SETUP_CODE,
-    secretKey: Bun.env.CROMBOLO_SECRET_KEY,
-    secureCookies: Bun.env.CROMBOLO_INSECURE_COOKIES !== 'true',
-    siteName: Bun.env.CROMBOLO_SITE_NAME ?? DEFAULTS.siteName,
+    localAdmin: setting('CROMBOLO_LOCAL_ADMIN') === 'true',
+    setupCode: setting('CROMBOLO_SETUP_CODE'),
+    secretKey: setting('CROMBOLO_SECRET_KEY'),
+    secureCookies: setting('CROMBOLO_INSECURE_COOKIES') !== 'true',
+    siteName: setting('CROMBOLO_SITE_NAME') ?? DEFAULTS.siteName,
     siteDir: cwd,
-    componentsDir: Bun.env.CROMBOLO_COMPONENTS_DIR ?? DEFAULTS.componentsDir,
-    componentsCacheDir: Bun.env.CROMBOLO_COMPONENTS_CACHE_DIR ?? DEFAULTS.componentsCacheDir,
+    componentsDir: setting('CROMBOLO_COMPONENTS_DIR') ?? DEFAULTS.componentsDir,
+    componentsCacheDir: setting('CROMBOLO_COMPONENTS_CACHE_DIR') ?? DEFAULTS.componentsCacheDir,
     componentsSnapshot: {
-      ...(Bun.env.CROMBOLO_COMPONENTS_GATE_MS
-        ? { gateTtlMs: Number(Bun.env.CROMBOLO_COMPONENTS_GATE_MS) }
+      ...(setting('CROMBOLO_COMPONENTS_GATE_MS')
+        ? { gateTtlMs: Number(setting('CROMBOLO_COMPONENTS_GATE_MS')) }
         : {}),
-      ...(Bun.env.CROMBOLO_COMPONENTS_GENERATION_LIMIT
-        ? { maxGenerations: Number(Bun.env.CROMBOLO_COMPONENTS_GENERATION_LIMIT) }
+      ...(setting('CROMBOLO_COMPONENTS_GENERATION_LIMIT')
+        ? { maxGenerations: Number(setting('CROMBOLO_COMPONENTS_GENERATION_LIMIT')) }
         : {}),
-      ...(Bun.env.CROMBOLO_COMPONENTS_KEEP
-        ? { keep: Number(Bun.env.CROMBOLO_COMPONENTS_KEEP) }
+      ...(setting('CROMBOLO_COMPONENTS_KEEP')
+        ? { keep: Number(setting('CROMBOLO_COMPONENTS_KEEP')) }
         : {}),
-      ...(Bun.env.CROMBOLO_COMPONENTS_SWAP_MS
-        ? { minSwapIntervalMs: Number(Bun.env.CROMBOLO_COMPONENTS_SWAP_MS) }
+      ...(setting('CROMBOLO_COMPONENTS_SWAP_MS')
+        ? { minSwapIntervalMs: Number(setting('CROMBOLO_COMPONENTS_SWAP_MS')) }
         : {}),
     },
-    renderTimeoutMs: Number(Bun.env.CROMBOLO_RENDER_TIMEOUT_MS ?? DEFAULTS.renderTimeoutMs),
-    schemaDir: Bun.env.CROMBOLO_SCHEMA_DIR ?? DEFAULTS.schemaDir,
-    schemaRevision: Bun.env.CROMBOLO_SCHEMA_REVISION ?? DEFAULTS.schemaRevision,
-    nodeId: Bun.env.CROMBOLO_NODE_ID ?? `${hostname()}:${process.pid}`,
-    role: roleFromEnvironment(Bun.env.CROMBOLO_ROLE),
+    renderTimeoutMs: Number(setting('CROMBOLO_RENDER_TIMEOUT_MS') ?? DEFAULTS.renderTimeoutMs),
+    schemaDir: setting('CROMBOLO_SCHEMA_DIR') ?? DEFAULTS.schemaDir,
+    schemaRevision: setting('CROMBOLO_SCHEMA_REVISION') ?? DEFAULTS.schemaRevision,
+    nodeId: setting('CROMBOLO_NODE_ID') ?? `${hostname()}:${process.pid}`,
+    role: roleFromEnvironment(setting('CROMBOLO_ROLE')),
     git: undefined,
     schemaStore: undefined,
-    schemaCacheDir: Bun.env.CROMBOLO_SCHEMA_CACHE_DIR ?? join(tmpdir(), 'crombolo-schema'),
+    schemaCacheDir: setting('CROMBOLO_SCHEMA_CACHE_DIR') ?? join(tmpdir(), 'crombolo-schema'),
     // Resolved again below, once it is known whether a store was configured.
     schemaWritable:
-      Bun.env.CROMBOLO_SCHEMA_WRITABLE !== undefined
-        ? Bun.env.CROMBOLO_SCHEMA_WRITABLE === 'true'
-        : Bun.env.NODE_ENV !== 'production',
-    syncSchemaAtBoot: Bun.env.CROMBOLO_SYNC_SCHEMA_AT_BOOT !== 'false',
-    dialect: Bun.env.CROMBOLO_DB === 'postgres' ? 'postgres' : 'sqlite',
-    pgDump: Bun.env.CROMBOLO_PG_DUMP,
+      setting('CROMBOLO_SCHEMA_WRITABLE') !== undefined
+        ? setting('CROMBOLO_SCHEMA_WRITABLE') === 'true'
+        : setting('NODE_ENV') !== 'production',
+    syncSchemaAtBoot: setting('CROMBOLO_SYNC_SCHEMA_AT_BOOT') !== 'false',
+    dialect: setting('CROMBOLO_DB') === 'postgres' ? 'postgres' : 'sqlite',
+    pgDump: setting('CROMBOLO_PG_DUMP'),
     upgradePolicy:
-      Bun.env.CROMBOLO_UPGRADE_POLICY === 'pending-allowed' ||
-      (Bun.env.CROMBOLO_UPGRADE_POLICY === undefined && Bun.env.NODE_ENV !== 'production')
+      setting('CROMBOLO_UPGRADE_POLICY') === 'pending-allowed' ||
+      (setting('CROMBOLO_UPGRADE_POLICY') === undefined && setting('NODE_ENV') !== 'production')
         ? 'pending-allowed'
         : 'strict',
     versionCleanup: {
-      enabled: Bun.env.CROMBOLO_VERSION_CLEANUP === 'true',
+      enabled: setting('CROMBOLO_VERSION_CLEANUP') === 'true',
       keepAllVersionsNewerThanDays: Number(
-        Bun.env.CROMBOLO_VERSION_CLEANUP_KEEP_ALL_DAYS ?? DEFAULTS.keepAllVersionsNewerThanDays,
+        setting('CROMBOLO_VERSION_CLEANUP_KEEP_ALL_DAYS') ?? DEFAULTS.keepAllVersionsNewerThanDays,
       ),
       keepLatestVersionPerDayForDays: Number(
-        Bun.env.CROMBOLO_VERSION_CLEANUP_KEEP_LATEST_DAYS ??
+        setting('CROMBOLO_VERSION_CLEANUP_KEEP_LATEST_DAYS') ??
           DEFAULTS.keepLatestVersionPerDayForDays,
       ),
     },
     auditRetentionDays: nonNegative(
-      Bun.env.CROMBOLO_AUDIT_RETENTION_DAYS,
+      setting('CROMBOLO_AUDIT_RETENTION_DAYS'),
       DEFAULTS.auditRetentionDays,
     ),
-    mediaDir: Bun.env.CROMBOLO_MEDIA_DIR ?? DEFAULTS.mediaDir,
+    mediaDir: setting('CROMBOLO_MEDIA_DIR') ?? DEFAULTS.mediaDir,
     mediaStore: undefined,
-    logsDir: Bun.env.CROMBOLO_LOGS_DIR ?? DEFAULTS.logsDir,
-    logLevel: parseLogLevel(Bun.env.CROMBOLO_LOG_LEVEL),
-    logToConsole: Bun.env.CROMBOLO_LOG_TO_CONSOLE !== 'false',
+    logsDir: setting('CROMBOLO_LOGS_DIR') ?? DEFAULTS.logsDir,
+    logLevel: parseLogLevel(setting('CROMBOLO_LOG_LEVEL')),
+    logToConsole: setting('CROMBOLO_LOG_TO_CONSOLE') !== 'false',
     diagnostics: {
-      traceRequests: Bun.env.CROMBOLO_TRACE_REQUESTS === 'true',
-      heapIntervalSeconds: Math.max(0, Number(Bun.env.CROMBOLO_HEAP_INTERVAL_SECONDS ?? 0) || 0),
+      traceRequests: setting('CROMBOLO_TRACE_REQUESTS') === 'true',
+      heapIntervalSeconds: Math.max(0, Number(setting('CROMBOLO_HEAP_INTERVAL_SECONDS') ?? 0) || 0),
     },
-    stylesheetsDir: Bun.env.CROMBOLO_CSS_DIR ?? DEFAULTS.stylesheetsDir,
-    scriptsDir: Bun.env.CROMBOLO_SCRIPTS_DIR ?? DEFAULTS.scriptsDir,
-    usernameIsEmail: Bun.env.CROMBOLO_USERNAME_IS_EMAIL !== 'false',
-    applicationUrl: Bun.env.CROMBOLO_APPLICATION_URL ?? '',
+    stylesheetsDir: setting('CROMBOLO_CSS_DIR') ?? DEFAULTS.stylesheetsDir,
+    scriptsDir: setting('CROMBOLO_SCRIPTS_DIR') ?? DEFAULTS.scriptsDir,
+    usernameIsEmail: setting('CROMBOLO_USERNAME_IS_EMAIL') !== 'false',
+    applicationUrl: setting('CROMBOLO_APPLICATION_URL') ?? '',
     sendUserLink: undefined,
     email: undefined,
-    allowMemberRegistration: Bun.env.CROMBOLO_ALLOW_MEMBER_REGISTRATION === 'true',
+    allowMemberRegistration: setting('CROMBOLO_ALLOW_MEMBER_REGISTRATION') === 'true',
     memberRegistrationType:
-      Bun.env.CROMBOLO_MEMBER_REGISTRATION_TYPE ?? DEFAULTS.memberRegistrationType,
-    memberRegistrationGroups: (Bun.env.CROMBOLO_MEMBER_REGISTRATION_GROUPS ?? '')
+      setting('CROMBOLO_MEMBER_REGISTRATION_TYPE') ?? DEFAULTS.memberRegistrationType,
+    memberRegistrationGroups: (setting('CROMBOLO_MEMBER_REGISTRATION_GROUPS') ?? '')
       .split(',')
       .map((name) => name.trim())
       .filter(Boolean),
     memberSessionMinutes: Number(
-      Bun.env.CROMBOLO_MEMBER_SESSION_MINUTES ?? DEFAULTS.memberSessionMinutes,
+      setting('CROMBOLO_MEMBER_SESSION_MINUTES') ?? DEFAULTS.memberSessionMinutes,
     ),
     maxFailedPasswordAttempts: Number(
-      Bun.env.CROMBOLO_MAX_FAILED_PASSWORD_ATTEMPTS ?? DEFAULTS.maxFailedPasswordAttempts,
+      setting('CROMBOLO_MAX_FAILED_PASSWORD_ATTEMPTS') ?? DEFAULTS.maxFailedPasswordAttempts,
     ),
     // No environment variable: a provider is a preset, which is code.
     memberIdentityProviders: [],
     backofficeIdentityProviders: [],
     remote: {
-      enabled: Bun.env.CROMBOLO_REMOTE_ENABLED === 'true',
-      environment: Bun.env.CROMBOLO_REMOTE_ENVIRONMENT || 'production',
-      protected: Bun.env.CROMBOLO_REMOTE_PROTECTED !== 'false',
-      approvals: Bun.env.CROMBOLO_REMOTE_APPROVALS === 'true',
-      maxUploadBytes: Number(Bun.env.CROMBOLO_REMOTE_MAX_UPLOAD_GB ?? 50) * 1024 ** 3,
+      enabled: setting('CROMBOLO_REMOTE_ENABLED') === 'true',
+      environment: setting('CROMBOLO_REMOTE_ENVIRONMENT') || 'production',
+      protected: setting('CROMBOLO_REMOTE_PROTECTED') !== 'false',
+      approvals: setting('CROMBOLO_REMOTE_APPROVALS') === 'true',
+      maxUploadBytes: Number(setting('CROMBOLO_REMOTE_MAX_UPLOAD_GB') ?? 50) * 1024 ** 3,
     },
     redirects: [],
-    trackRedirects: Bun.env.CROMBOLO_TRACK_REDIRECTS !== 'false',
-    applyBundleContentOnInstall: Bun.env.CROMBOLO_APPLY_BUNDLE_CONTENT !== 'false',
+    trackRedirects: setting('CROMBOLO_TRACK_REDIRECTS') !== 'false',
+    applyBundleContentOnInstall: setting('CROMBOLO_APPLY_BUNDLE_CONTENT') !== 'false',
     // Resolved again below, once it is known whether a store was configured.
-    runtimeInstalls: Bun.env.CROMBOLO_RUNTIME_INSTALLS !== 'false',
+    runtimeInstalls: setting('CROMBOLO_RUNTIME_INSTALLS') !== 'false',
     seo: stripUndefined({
-      sitemap: envFlag(Bun.env.CROMBOLO_SITEMAP),
-      indexable: envFlag(Bun.env.CROMBOLO_INDEXABLE),
+      sitemap: envFlag(setting('CROMBOLO_SITEMAP')),
+      indexable: envFlag(setting('CROMBOLO_INDEXABLE')),
     }),
     deliveryApi: stripUndefined({
-      enabled: envFlag(Bun.env.CROMBOLO_DELIVERY_API),
-      apiKey: Bun.env.CROMBOLO_DELIVERY_API_KEY || undefined,
-      publicAccess: envFlag(Bun.env.CROMBOLO_DELIVERY_API_PUBLIC),
+      enabled: envFlag(setting('CROMBOLO_DELIVERY_API')),
+      apiKey: setting('CROMBOLO_DELIVERY_API_KEY') || undefined,
+      publicAccess: envFlag(setting('CROMBOLO_DELIVERY_API_PUBLIC')),
       media:
-        envFlag(Bun.env.CROMBOLO_DELIVERY_API_MEDIA) === undefined
+        envFlag(setting('CROMBOLO_DELIVERY_API_MEDIA')) === undefined
           ? undefined
-          : { enabled: envFlag(Bun.env.CROMBOLO_DELIVERY_API_MEDIA) },
+          : { enabled: envFlag(setting('CROMBOLO_DELIVERY_API_MEDIA')) },
     }),
     // No environment variable: a bundle is an import, which is code.
     bundles: [],
-    marketplaceUrl: Bun.env.CROMBOLO_MARKETPLACE_URL ?? DEFAULTS.marketplaceUrl,
-    packageKeyword: Bun.env.CROMBOLO_PACKAGE_KEYWORD ?? DEFAULTS.packageKeyword,
-    npmRegistry: Bun.env.CROMBOLO_NPM_REGISTRY ?? DEFAULTS.npmRegistry,
+    marketplaceUrl: setting('CROMBOLO_MARKETPLACE_URL') ?? DEFAULTS.marketplaceUrl,
+    packageKeyword: setting('CROMBOLO_PACKAGE_KEYWORD') ?? DEFAULTS.packageKeyword,
+    npmRegistry: setting('CROMBOLO_NPM_REGISTRY') ?? DEFAULTS.npmRegistry,
     // No environment variable: enabling it takes a provider, which is code.
     assistant: undefined,
   }
@@ -661,7 +662,7 @@ export function loadConfig(
   // it — that is the point of configuring one. An explicit setting still wins.
   if (
     merged.schemaStore &&
-    Bun.env.CROMBOLO_SCHEMA_WRITABLE === undefined &&
+    setting('CROMBOLO_SCHEMA_WRITABLE') === undefined &&
     overrides.schemaWritable === undefined
   ) {
     merged.schemaWritable = true
@@ -670,7 +671,7 @@ export function loadConfig(
   // them would not either. An explicit setting still wins.
   if (
     merged.schemaStore &&
-    Bun.env.CROMBOLO_RUNTIME_INSTALLS === undefined &&
+    setting('CROMBOLO_RUNTIME_INSTALLS') === undefined &&
     overrides.runtimeInstalls === undefined
   ) {
     merged.runtimeInstalls = false
@@ -727,7 +728,7 @@ function stripUndefined<T extends object>(value: T): Partial<T> {
  */
 export function describeDatabase(
   config: Pick<CromboloConfig, 'dialect' | 'sqliteFile'>,
-  url: string | undefined = Bun.env.CROMBOLO_POSTGRES_URL ?? Bun.env.DATABASE_URL,
+  url: string | undefined = setting('CROMBOLO_POSTGRES_URL') ?? setting('DATABASE_URL'),
 ): string {
   if (config.dialect !== 'postgres') return config.sqliteFile
   if (!url) return 'postgres'
@@ -739,4 +740,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.17.0'
+export const VERSION = '0.18.0'

package/src/email-ses.ts

@@ -30,6 +30,7 @@ import {
   postToProvider,
   validateMessage,
 } from './email.ts'
+import { setting } from './settings.ts'
 
 export interface SesOptions extends EmailAdapterOptions {
   region: string
@@ -228,13 +229,13 @@ export function rawMime(
 
 export function sesEmail(options: SesOptions): EmailPort {
   if (!options.region) throw new Error('An SES e-mail adapter needs a region.')
-  const accessKeyId = options.accessKeyId ?? Bun.env.AWS_ACCESS_KEY_ID ?? ''
-  const secretAccessKey = options.secretAccessKey ?? Bun.env.AWS_SECRET_ACCESS_KEY ?? ''
+  const accessKeyId = options.accessKeyId ?? setting('AWS_ACCESS_KEY_ID') ?? ''
+  const secretAccessKey = options.secretAccessKey ?? setting('AWS_SECRET_ACCESS_KEY') ?? ''
   if (!accessKeyId || !secretAccessKey)
     throw new Error(
       'An SES e-mail adapter needs credentials: pass accessKeyId and secretAccessKey, or set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Instance roles are not resolved.',
     )
-  const sessionToken = options.sessionToken ?? Bun.env.AWS_SESSION_TOKEN ?? undefined
+  const sessionToken = options.sessionToken ?? setting('AWS_SESSION_TOKEN') ?? undefined
   const call = options.fetch ?? fetch
   const base = options.endpoint ?? `https://email.${options.region}.amazonaws.com`
   assertSecureEndpoint(base, 'SES')

package/src/index.ts

@@ -78,6 +78,7 @@ export * from './secrets.ts'
 export * from './seo.ts'
 export * from './server.ts'
 export * from './server-events.ts'
+export * from './settings.ts'
 export * from './setup.ts'
 export * from './site-file.ts'
 export * from './site-replace.ts'

package/src/settings.ts

@@ -0,0 +1,921 @@
+/**
+ * Every environment variable crombolo reads, declared once. `loadConfig` reads
+ * through `setting`, and the configuration reference is generated from the list.
+ */
+
+export type SettingKind = 'string' | 'number' | 'boolean' | 'list' | 'enum'
+
+export interface Setting {
+  env: string
+  kind: SettingKind
+  /** As a reader would see it; omitted when there is none. */
+  default?: string
+  /** The accepted values, for an enum. */
+  values?: readonly string[]
+  section: string
+  /** One or two plain sentences for a site owner. */
+  description: string
+  /** Never echoed. */
+  secret?: boolean
+  /** Who reads it; the server when unset. */
+  appliesTo?: 'server' | 'cli' | 'both'
+}
+
+const SECTIONS = [
+  'Server',
+  'Database',
+  'Sign-in and secrets',
+  'Back office and bundles',
+  'Schema',
+  'Components',
+  'Media',
+  'E-mail',
+  'Members',
+  'Public site',
+  'Remote',
+  'Logging',
+  'Command line',
+  'AWS credentials',
+] as const
+
+/** Section headings, in display order. */
+export const SETTING_SECTIONS: readonly string[] = SECTIONS
+
+type Section = (typeof SECTIONS)[number]
+
+const DECLARED = [
+  // Server
+  {
+    env: 'NODE_ENV',
+    kind: 'string',
+    section: 'Server',
+    description:
+      '`production` turns off the development conveniences: generated admin passwords, writable schema files, e-mail to the console and relaxed upgrade checks.',
+  },
+  {
+    env: 'PORT',
+    kind: 'number',
+    default: '8080',
+    section: 'Server',
+    description: 'The HTTP port. The application URL defaults to localhost on this port.',
+  },
+  {
+    env: 'CROMBOLO_SITE_NAME',
+    kind: 'string',
+    default: 'Crombolo',
+    section: 'Server',
+    description: "The site's name, shown in the back office and used when a page is shared.",
+  },
+  {
+    env: 'CROMBOLO_APPLICATION_URL',
+    kind: 'string',
+    default: 'http://localhost:<port>',
+    section: 'Server',
+    description: "The site's public address, which invitation and password-reset links point at.",
+  },
+  {
+    env: 'CROMBOLO_ROLE',
+    kind: 'enum',
+    values: ['all', 'api', 'web'],
+    default: 'all',
+    section: 'Server',
+    description:
+      'What this process serves: everything, the back office and its API, or the public site alone. Splitting needs Postgres; a misspelt role stops the server.',
+  },
+  {
+    env: 'CROMBOLO_NODE_ID',
+    kind: 'string',
+    default: 'host:pid',
+    section: 'Server',
+    description:
+      "This node's name, stamped on schema syncs, content changes and the upgrade history.",
+  },
+  {
+    env: 'CROMBOLO_MAX_REQUEST_BODY_MB',
+    kind: 'number',
+    default: '32',
+    section: 'Server',
+    description: 'The largest request body the server reads, media uploads included.',
+  },
+  {
+    env: 'CROMBOLO_INSECURE_COOKIES',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Server',
+    description:
+      'Drops the secure cookie requirements, for a plain-http host that is not localhost.',
+  },
+
+  // Database
+  {
+    env: 'CROMBOLO_DB',
+    kind: 'enum',
+    values: ['sqlite', 'postgres'],
+    default: 'sqlite',
+    section: 'Database',
+    description: 'Which database engine the site runs on.',
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_SQLITE_FILE',
+    kind: 'string',
+    default: 'crombolo.sqlite',
+    section: 'Database',
+    description: 'The SQLite file, relative to the site, or `:memory:`.',
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_POSTGRES_URL',
+    kind: 'string',
+    section: 'Database',
+    description: 'The Postgres connection string. Required when the database is Postgres.',
+    secret: true,
+    appliesTo: 'both',
+  },
+  {
+    env: 'DATABASE_URL',
+    kind: 'string',
+    section: 'Database',
+    description: 'Used as the Postgres connection string when `CROMBOLO_POSTGRES_URL` is unset.',
+    secret: true,
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_LOCK_TIMEOUT_SECONDS',
+    kind: 'number',
+    default: '15',
+    section: 'Database',
+    description: 'How long a content write waits for another before it gives up and answers 503.',
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_PG_DUMP',
+    kind: 'string',
+    section: 'Database',
+    description:
+      'A shell command that backs up Postgres before a repair, an upgrade or a purge. It is given `CROMBOLO_BACKUP_STAMP` and `CROMBOLO_BACKUP_REASON`; without it those commands need `--backup-taken`.',
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_UPGRADE_POLICY',
+    kind: 'enum',
+    values: ['strict', 'pending-allowed'],
+    default: 'strict in production, else pending-allowed',
+    section: 'Database',
+    description: 'Whether findings that need a person stop an upgrade.',
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_VERSION_CLEANUP',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Database',
+    description: 'Runs the hourly clean-up of old content versions.',
+  },
+  {
+    env: 'CROMBOLO_VERSION_CLEANUP_KEEP_ALL_DAYS',
+    kind: 'number',
+    default: '7',
+    section: 'Database',
+    description:
+      "The clean-up keeps every version newer than this many days. A content type's own policy wins.",
+  },
+  {
+    env: 'CROMBOLO_VERSION_CLEANUP_KEEP_LATEST_DAYS',
+    kind: 'number',
+    default: '90',
+    section: 'Database',
+    description: "After that, it keeps each day's latest version for this many days.",
+  },
+  {
+    env: 'CROMBOLO_AUDIT_RETENTION_DAYS',
+    kind: 'number',
+    default: '365',
+    section: 'Database',
+    description: 'How many days the audit log keeps an entry. `0` keeps them all.',
+  },
+
+  // Sign-in and secrets
+  {
+    env: 'CROMBOLO_ADMIN_LOGIN',
+    kind: 'string',
+    default: 'admin@crombolo.local',
+    section: 'Sign-in and secrets',
+    description: 'The login of the first administrator.',
+  },
+  {
+    env: 'CROMBOLO_ADMIN_PASSWORD',
+    kind: 'string',
+    default: 'generated in development',
+    section: 'Sign-in and secrets',
+    description:
+      "The first administrator's password, used only when the database is created. Unset in production, the site is set up in the browser.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_SETUP_CODE',
+    kind: 'string',
+    section: 'Sign-in and secrets',
+    description:
+      'Guards "Set up your new site" in production: 16 or more characters, chosen by you. Remove it once the site is set up.',
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_API_CLIENT_ID',
+    kind: 'string',
+    section: 'Sign-in and secrets',
+    description:
+      'An API client an unattended install creates in the administrators group; it starts `crombolo-back-office-`. With it, no password administrator is created unless `CROMBOLO_ADMIN_PASSWORD` is set.',
+    appliesTo: 'both',
+  },
+  {
+    env: 'CROMBOLO_API_CLIENT_SECRET',
+    kind: 'string',
+    section: 'Sign-in and secrets',
+    description:
+      "That client's secret, set together with the id. It is used once, when the client is created.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_LOCAL_ADMIN',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Sign-in and secrets',
+    description:
+      'Creates the password administrator even when an API client is set. Honoured only on localhost.',
+  },
+  {
+    env: 'CROMBOLO_SECRET_KEY',
+    kind: 'string',
+    section: 'Sign-in and secrets',
+    description:
+      "Seals secrets kept in the database, such as a webhook's headers and two-factor keys; 32 or more characters. Features that need it are not offered without it.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_USERNAME_IS_EMAIL',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Sign-in and secrets',
+    description: "A back office user's login is their e-mail address.",
+  },
+
+  // Back office and bundles
+  {
+    env: 'CROMBOLO_BACKOFFICE_PATH',
+    kind: 'string',
+    default: '/crombolo',
+    section: 'Back office and bundles',
+    description: 'Where the back office is served.',
+  },
+  {
+    env: 'CROMBOLO_CSS_DIR',
+    kind: 'string',
+    default: 'css',
+    section: 'Back office and bundles',
+    description: 'The stylesheets the Settings section edits, served at `/css/`.',
+  },
+  {
+    env: 'CROMBOLO_SCRIPTS_DIR',
+    kind: 'string',
+    default: 'scripts',
+    section: 'Back office and bundles',
+    description: 'The scripts the Settings section edits, served at `/scripts/`.',
+  },
+  {
+    env: 'CROMBOLO_APPLY_BUNDLE_CONTENT',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Back office and bundles',
+    description:
+      'Installing a bundle from the Marketplace also applies the schema, components and content it carries.',
+  },
+  {
+    env: 'CROMBOLO_RUNTIME_INSTALLS',
+    kind: 'boolean',
+    default: 'true, false with a schema store',
+    section: 'Back office and bundles',
+    description:
+      'The Packages section installs and removes packages on the running site. Off, they are added to `package.json` and deployed.',
+  },
+  {
+    env: 'CROMBOLO_MARKETPLACE_URL',
+    kind: 'string',
+    default: 'https://www.npmjs.com/search?q=keywords%3Acrombolo-bundle',
+    section: 'Back office and bundles',
+    description: 'Where the Marketplace sends someone browsing for bundles.',
+  },
+  {
+    env: 'CROMBOLO_PACKAGE_KEYWORD',
+    kind: 'string',
+    default: 'crombolo-bundle',
+    section: 'Back office and bundles',
+    description: 'The npm keyword a bundle publishes under to be found by the Marketplace.',
+  },
+  {
+    env: 'CROMBOLO_NPM_REGISTRY',
+    kind: 'string',
+    default: 'https://registry.npmjs.org',
+    section: 'Back office and bundles',
+    description: 'The registry the Marketplace searches, such as a mirror.',
+  },
+
+  // Schema
+  {
+    env: 'CROMBOLO_SCHEMA_DIR',
+    kind: 'string',
+    default: 'schema',
+    section: 'Schema',
+    description: 'Where the schema files live. Nothing is synced when the folder is absent.',
+  },
+  {
+    env: 'CROMBOLO_SCHEMA_REVISION',
+    kind: 'string',
+    default: '0',
+    section: 'Schema',
+    description: 'Set by a deploy, to order deploys of the same schema version.',
+  },
+  {
+    env: 'CROMBOLO_SCHEMA_CACHE_DIR',
+    kind: 'string',
+    default: '<temp>/crombolo-schema',
+    section: 'Schema',
+    description: 'Where a schema kept in cloud storage is copied to when the server starts.',
+  },
+  {
+    env: 'CROMBOLO_SCHEMA_WRITABLE',
+    kind: 'boolean',
+    default: 'true unless production or with a schema store',
+    section: 'Schema',
+    description: 'Whether the back office may change the schema files.',
+  },
+  {
+    env: 'CROMBOLO_SYNC_SCHEMA_AT_BOOT',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Schema',
+    description:
+      'Syncs the schema files when the server starts. Turn it off when a deploy runs `crombolo types sync` itself.',
+  },
+
+  // Components
+  {
+    env: 'CROMBOLO_COMPONENTS_DIR',
+    kind: 'string',
+    default: 'components',
+    section: 'Components',
+    description: "Where the site's page views and components live.",
+  },
+  {
+    env: 'CROMBOLO_COMPONENTS_CACHE_DIR',
+    kind: 'string',
+    default: '.crombolo/components',
+    section: 'Components',
+    description:
+      'Where components are copied so that an edit is picked up without a restart. Inside the site, and cleared when the server starts.',
+  },
+  {
+    env: 'CROMBOLO_COMPONENTS_GATE_MS',
+    kind: 'number',
+    default: '5000, 500 in development',
+    section: 'Components',
+    description: 'How often a node looks for changed components, in milliseconds.',
+  },
+  {
+    env: 'CROMBOLO_COMPONENTS_SWAP_MS',
+    kind: 'number',
+    default: '10000, 0 in development',
+    section: 'Components',
+    description:
+      'The least time between two changes being picked up, in milliseconds. A save made in the back office is never held back by it.',
+  },
+  {
+    env: 'CROMBOLO_COMPONENTS_GENERATION_LIMIT',
+    kind: 'number',
+    default: '250',
+    section: 'Components',
+    description:
+      'How many changes a node picks up before it stops taking more and keeps serving the last.',
+  },
+  {
+    env: 'CROMBOLO_COMPONENTS_KEEP',
+    kind: 'number',
+    default: '3, all in development',
+    section: 'Components',
+    description: 'How many earlier copies are kept on disk, for an instant return to one.',
+  },
+  {
+    env: 'CROMBOLO_RENDER_TIMEOUT_MS',
+    kind: 'number',
+    default: '10000',
+    section: 'Components',
+    description:
+      'How long a page may take to render, layouts included, before it fails, in milliseconds. `0` for no limit.',
+  },
+
+  // Media
+  {
+    env: 'CROMBOLO_MEDIA_DIR',
+    kind: 'string',
+    default: 'media',
+    section: 'Media',
+    description: 'Where uploaded files live on this disk, served at `/media/`.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_STORE',
+    kind: 'enum',
+    values: ['filesystem', 's3', 'azure'],
+    default: 'filesystem',
+    section: 'Media',
+    description: 'Where media files are kept. An unrecognised value falls back to the file system.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_PUBLIC_URL',
+    kind: 'string',
+    section: 'Media',
+    description:
+      'A CDN in front of the media folder: browsers are sent there instead of being served by this server.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_BUCKET',
+    kind: 'string',
+    section: 'Media',
+    description: 'S3: the bucket.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_REGION',
+    kind: 'string',
+    section: 'Media',
+    description: "S3: the bucket's region.",
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_ENDPOINT',
+    kind: 'string',
+    section: 'Media',
+    description: 'S3: the endpoint, for an S3-compatible store such as R2, Spaces or MinIO.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_ACCESS_KEY_ID',
+    kind: 'string',
+    section: 'Media',
+    description: "S3: the access key. Unset, the client's usual credentials are used.",
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_SECRET_ACCESS_KEY',
+    kind: 'string',
+    section: 'Media',
+    description: "S3: the access key's secret.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_SESSION_TOKEN',
+    kind: 'string',
+    section: 'Media',
+    description: 'S3: a session token, for temporary credentials.',
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_PREFIX',
+    kind: 'string',
+    section: 'Media',
+    description: 'S3: a folder inside the bucket to keep media under.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_PUBLIC_URL',
+    kind: 'string',
+    section: 'Media',
+    description: 'S3: a public address for the bucket, such as a CDN, that browsers are sent to.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_S3_PRESIGN_SECONDS',
+    kind: 'number',
+    section: 'Media',
+    description:
+      'S3: sends browsers to a signed bucket address that lasts this many seconds. Use this or a public address, not both.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_ACCOUNT',
+    kind: 'string',
+    section: 'Media',
+    description: 'Azure: the storage account.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_CONTAINER',
+    kind: 'string',
+    default: 'media',
+    section: 'Media',
+    description: 'Azure: the blob container.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_KEY',
+    kind: 'string',
+    section: 'Media',
+    description: "Azure: the account's key.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_SAS',
+    kind: 'string',
+    section: 'Media',
+    description: 'Azure: a shared access signature, instead of the key.',
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_ENDPOINT',
+    kind: 'string',
+    section: 'Media',
+    description: 'Azure: the blob endpoint, for a sovereign cloud or a local emulator.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_PREFIX',
+    kind: 'string',
+    section: 'Media',
+    description: 'Azure: a folder inside the container to keep media under.',
+  },
+  {
+    env: 'CROMBOLO_MEDIA_AZURE_PUBLIC_URL',
+    kind: 'string',
+    section: 'Media',
+    description:
+      'Azure: a public address for the container, such as a CDN, that browsers are sent to.',
+  },
+
+  // E-mail
+  {
+    env: 'CROMBOLO_EMAIL_PROVIDER',
+    kind: 'enum',
+    values: ['none', 'resend', 'postmark', 'ses', 'custom'],
+    default: 'none',
+    section: 'E-mail',
+    description:
+      'How e-mail is sent. Without one, invitations, password resets and form e-mails are unavailable; development prints messages to the console.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_FROM',
+    kind: 'string',
+    section: 'E-mail',
+    description: 'The sender address. Every provider needs it, and verifies its domain.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_FROM_NAME',
+    kind: 'string',
+    section: 'E-mail',
+    description: 'The name shown beside the sender address.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_API_KEY',
+    kind: 'string',
+    section: 'E-mail',
+    description:
+      "The provider's key: Resend's API key, Postmark's server token, or a bearer token for a custom endpoint.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_EMAIL_URL',
+    kind: 'string',
+    default: "the provider's own API",
+    section: 'E-mail',
+    description:
+      'The address messages are sent to. Required for a custom endpoint, an override for the others. Must be HTTPS unless it is on this machine.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_POSTMARK_STREAM',
+    kind: 'string',
+    default: 'outbound',
+    section: 'E-mail',
+    description: 'Postmark: the message stream to send on.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_SES_REGION',
+    kind: 'string',
+    default: 'AWS_REGION',
+    section: 'E-mail',
+    description: 'SES: the region to send from.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_SES_ACCESS_KEY_ID',
+    kind: 'string',
+    default: 'AWS_ACCESS_KEY_ID',
+    section: 'E-mail',
+    description: 'SES: the access key, when it differs from the standard AWS one.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_SES_SECRET_ACCESS_KEY',
+    kind: 'string',
+    default: 'AWS_SECRET_ACCESS_KEY',
+    section: 'E-mail',
+    description: "SES: that access key's secret.",
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_EMAIL_SES_CONFIGURATION_SET',
+    kind: 'string',
+    section: 'E-mail',
+    description: 'SES: the configuration set that governs sending.',
+  },
+  {
+    env: 'CROMBOLO_EMAIL_SES_ENDPOINT',
+    kind: 'string',
+    default: 'the regional SES address',
+    section: 'E-mail',
+    description: 'SES: a private endpoint to send through instead.',
+  },
+
+  // Members
+  {
+    env: 'CROMBOLO_ALLOW_MEMBER_REGISTRATION',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Members',
+    description: 'Lets visitors register as members of the site.',
+  },
+  {
+    env: 'CROMBOLO_MEMBER_REGISTRATION_TYPE',
+    kind: 'string',
+    default: 'Member',
+    section: 'Members',
+    description: 'The member type a registration creates, by alias.',
+  },
+  {
+    env: 'CROMBOLO_MEMBER_REGISTRATION_GROUPS',
+    kind: 'list',
+    section: 'Members',
+    description: 'The member groups a registration joins, separated by commas.',
+  },
+  {
+    env: 'CROMBOLO_MEMBER_SESSION_MINUTES',
+    kind: 'number',
+    default: '20160',
+    section: 'Members',
+    description: "How long a member's sign-in lasts, in minutes. The default is 14 days.",
+  },
+  {
+    env: 'CROMBOLO_MAX_FAILED_PASSWORD_ATTEMPTS',
+    kind: 'number',
+    default: '5',
+    section: 'Members',
+    description: 'Failed member sign-ins before the member is locked out. `0` never locks out.',
+  },
+
+  // Public site
+  {
+    env: 'CROMBOLO_INDEXABLE',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Public site',
+    description:
+      'Off keeps search engines out entirely, for a staging site: robots are refused, there is no sitemap and every page asks not to be indexed.',
+  },
+  {
+    env: 'CROMBOLO_SITEMAP',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Public site',
+    description: 'Serves `/sitemap.xml`.',
+  },
+  {
+    env: 'CROMBOLO_TRACK_REDIRECTS',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Public site',
+    description: 'Renaming or moving a page records a redirect from the address it had.',
+  },
+  {
+    env: 'CROMBOLO_DELIVERY_API',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Public site',
+    description: 'Turns on the Delivery API, which serves content as JSON.',
+  },
+  {
+    env: 'CROMBOLO_DELIVERY_API_KEY',
+    kind: 'string',
+    section: 'Public site',
+    description:
+      'The key that unlocks a private Delivery API, and previews of unpublished content.',
+    secret: true,
+  },
+  {
+    env: 'CROMBOLO_DELIVERY_API_PUBLIC',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Public site',
+    description: 'Off, every Delivery API request needs the key.',
+  },
+  {
+    env: 'CROMBOLO_DELIVERY_API_MEDIA',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Public site',
+    description: 'The Delivery API serves media as well as content.',
+  },
+
+  // Remote
+  {
+    env: 'CROMBOLO_REMOTE_ENABLED',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Remote',
+    description: 'Lets `crombolo pull` and `crombolo push` reach this site.',
+  },
+  {
+    env: 'CROMBOLO_REMOTE_ENVIRONMENT',
+    kind: 'string',
+    default: 'production',
+    section: 'Remote',
+    description:
+      'The name this site goes by for pull and push: lower case letters, digits and dashes.',
+  },
+  {
+    env: 'CROMBOLO_REMOTE_PROTECTED',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Remote',
+    description: 'A push here needs the protected-push permission.',
+  },
+  {
+    env: 'CROMBOLO_REMOTE_APPROVALS',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Remote',
+    description:
+      'A push to a protected site waits for someone else to approve it. Needs `CROMBOLO_SECRET_KEY`.',
+  },
+  {
+    env: 'CROMBOLO_REMOTE_MAX_UPLOAD_GB',
+    kind: 'number',
+    default: '50',
+    section: 'Remote',
+    description:
+      'The largest push or media file a client may upload, in gigabytes. Every other request keeps the usual body limit.',
+  },
+
+  // Logging
+  {
+    env: 'CROMBOLO_LOGS_DIR',
+    kind: 'string',
+    default: 'logs',
+    section: 'Logging',
+    description: 'Where log files are written, a file a day, read by the back office log viewer.',
+  },
+  {
+    env: 'CROMBOLO_LOG_LEVEL',
+    kind: 'enum',
+    values: ['trace', 'debug', 'info', 'warning', 'error', 'fatal'],
+    default: 'info',
+    section: 'Logging',
+    description: 'The least severe level logged.',
+  },
+  {
+    env: 'CROMBOLO_LOG_TO_CONSOLE',
+    kind: 'boolean',
+    default: 'true',
+    section: 'Logging',
+    description: 'Log events are also printed to the console.',
+  },
+  {
+    env: 'CROMBOLO_TRACE_REQUESTS',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Logging',
+    description: 'Prints a line on the console as each request arrives and as it is answered.',
+  },
+  {
+    env: 'CROMBOLO_HEAP_INTERVAL_SECONDS',
+    kind: 'number',
+    default: '0',
+    section: 'Logging',
+    description:
+      'Every this many seconds, prints the memory in use and the requests in flight. `0` is off.',
+  },
+
+  // Command line
+  {
+    env: 'CROMBOLO_BOOT_ATTEMPTS',
+    kind: 'number',
+    default: '10',
+    section: 'Command line',
+    description:
+      'How many times `crombolo start` tries to start the site, waiting longer each time, before it exits.',
+    appliesTo: 'cli',
+  },
+  {
+    env: 'CROMBOLO_ACTOR',
+    kind: 'string',
+    default: 'the account running the command',
+    section: 'Command line',
+    description: 'Who the audit log records for a command, for a pipeline acting for someone.',
+    appliesTo: 'cli',
+  },
+  {
+    env: 'CROMBOLO_BUNDLE_PASSPHRASE',
+    kind: 'string',
+    section: 'Command line',
+    description: 'The passphrase for an encrypted content file, instead of being asked for it.',
+    secret: true,
+    appliesTo: 'cli',
+  },
+  {
+    env: 'CROMBOLO_DEBUG',
+    kind: 'boolean',
+    default: 'false',
+    section: 'Command line',
+    description: 'Adds the stack trace to an unexpected error.',
+    appliesTo: 'cli',
+  },
+  {
+    env: 'CROMBOLO_TEMPLATES_DIR',
+    kind: 'string',
+    default: 'the templates the command line ships',
+    section: 'Command line',
+    description: 'Where `crombolo init` finds its site templates, for trying a changed one.',
+    appliesTo: 'cli',
+  },
+
+  // AWS credentials
+  {
+    env: 'AWS_REGION',
+    kind: 'string',
+    section: 'AWS credentials',
+    description: 'The AWS region, for SES e-mail and the Bedrock assistant when they set none.',
+  },
+  {
+    env: 'AWS_PROFILE',
+    kind: 'string',
+    section: 'AWS credentials',
+    description: 'The AWS profile the Bedrock assistant signs in with.',
+  },
+  {
+    env: 'AWS_ACCESS_KEY_ID',
+    kind: 'string',
+    section: 'AWS credentials',
+    description: 'A static AWS access key, for SES e-mail and the Bedrock assistant.',
+  },
+  {
+    env: 'AWS_SECRET_ACCESS_KEY',
+    kind: 'string',
+    section: 'AWS credentials',
+    description: "That access key's secret.",
+    secret: true,
+  },
+  {
+    env: 'AWS_SESSION_TOKEN',
+    kind: 'string',
+    section: 'AWS credentials',
+    description: 'A session token, for temporary AWS credentials.',
+    secret: true,
+  },
+] as const satisfies readonly (Setting & { section: Section })[]
+
+export const SETTINGS: readonly Setting[] = DECLARED
+
+/** The name of a declared setting. */
+export type SettingName = (typeof DECLARED)[number]['env']
+
+const NAMES: ReadonlySet<string> = new Set(SETTINGS.map((entry) => entry.env))
+
+/** The raw environment value of a declared setting; unset is undefined. */
+export function setting(name: SettingName): string | undefined {
+  if (!NAMES.has(name)) throw new Error(`${name} is not a declared setting.`)
+  return Bun.env[name]
+}
+
+function cell(text: string): string {
+  return text.replaceAll('|', '\\|').replaceAll('\n', ' ')
+}
+
+function shownDefault(entry: Setting): string {
+  if (entry.default === undefined) return '—'
+  return /\s/.test(entry.default) ? cell(entry.default) : `\`${cell(entry.default)}\``
+}
+
+function shownKind(entry: Setting): string {
+  if (entry.kind === 'enum') return (entry.values ?? []).map((value) => `\`${value}\``).join(', ')
+  if (entry.kind === 'boolean') return '`true` / `false`'
+  return entry.kind
+}
+
+function shownDescription(entry: Setting): string {
+  const notes: string[] = []
+  if (entry.appliesTo === 'cli') notes.push('Read by the command line.')
+  if (entry.appliesTo === 'both') notes.push('Read by the server and the command line.')
+  if (entry.secret) notes.push('Kept secret: never printed.')
+  return cell([entry.description, ...notes].join(' '))
+}
+
+/** The settings reference: a table per section, in display order. */
+export function settingsMarkdown(): string {
+  const parts: string[] = []
+  for (const section of SETTING_SECTIONS) {
+    const entries = SETTINGS.filter((entry) => entry.section === section)
+    if (entries.length === 0) continue
+    parts.push(`### ${section}`, '')
+    parts.push('| Setting | Takes | Default | Description |', '| --- | --- | --- | --- |')
+    for (const entry of entries)
+      parts.push(
+        `| \`${entry.env}\` | ${shownKind(entry)} | ${shownDefault(entry)} | ${shownDescription(entry)} |`,
+      )
+    parts.push('')
+  }
+  return parts.join('\n').trimEnd()
+}