@crombolo/cli 0.14.4 → 0.16.0

package/src/commands/users/unlock.ts

@@ -0,0 +1,54 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import {
+  checkStatus,
+  describeUser,
+  OBSERVER,
+  OPERATOR,
+  openPeople,
+  userNamed,
+} from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersUnlock extends BaseCommand {
+  static override summary = "clear a user's lockout and failed sign-ins"
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = { category: 'user', action: 'Unlock', entityType: 'User' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'state', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersUnlock)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const snapshot = async () => {
+        const found = await people.users.get(OBSERVER, user.key)
+        return found.status === 'Success'
+          ? { state: found.value.state, failed: found.value.failedLoginAttempts }
+          : { state: 'unknown', failed: 0 }
+      }
+      const before = await snapshot()
+      checkStatus(await people.users.unlock(OPERATOR, [user.key]))
+      const after = await snapshot()
+      const state = after.state
+      const changed = before.state !== after.state || before.failed !== after.failed
+      this.say(`  unlocked  ${describeUser(user)}${changed ? '' : ' (no change)'}`)
+      return { id: user.key, email: user.email, state, changed }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/whoami.ts

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { problemOf } from '../remote/client.ts'
+import { connectRemote } from '../support/remote.ts'
+
+export default class Whoami extends BaseCommand {
+  static override summary = 'who you are signed in as at a remote, and what you may do there'
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'name', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'remote', type: 'string' },
+      { name: 'environments', type: 'array', items: { type: 'object' } },
+    ],
+    errors: ['not_found', 'auth', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(Whoami)
+    const { entry, client, discovery } = await connectRemote(args.remote, undefined)
+    const response = await client.call(
+      `${new URL(discovery.api).origin}/umbraco/management/api/v1/user/current`,
+    )
+    if (!response.ok) throw await problemOf(response)
+    const me = (await response.json()) as { name: string; email: string }
+    this.say(`  ${me.name} <${me.email}> on ${entry.name}`)
+    const environments = await client.environments()
+    for (const env of environments) {
+      const may = [env.may.pull && 'pull', env.may.pullFull && 'full pull', env.may.push && 'push']
+        .filter(Boolean)
+        .join(', ')
+      this.say(`  ${env.id.padEnd(12)} ${may || 'nothing'}${env.protected ? '  (protected)' : ''}`)
+    }
+    return { name: me.name, email: me.email, remote: entry.name, environments }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,90 @@
+/**
+ * How a command fails, and what it exits with (story 150). Every failure is a
+ * kind with one exit code, so a script can branch on `$?` and a machine can read
+ * the envelope; an outcome is a finding the command was asked to look for, which
+ * exits non-zero with no envelope.
+ */
+
+/** Each kind's exit code. The table in `docs/operations.md` § Exit codes is this one. */
+export const ERROR_KINDS = {
+  internal: { exitCode: 1, description: 'Something unexpected went wrong.' },
+  usage: {
+    exitCode: 2,
+    description: 'The arguments are wrong: an unknown command or flag, or one missing.',
+  },
+  timeout: {
+    exitCode: 3,
+    description: 'Gave up waiting. A remote job carries on at the remote.',
+    retryable: true,
+  },
+  auth: {
+    exitCode: 4,
+    description: 'Not signed in, the sign-in has lapsed, or a passphrase is missing or wrong.',
+  },
+  not_found: {
+    exitCode: 5,
+    description: 'No such remote, environment, page, run, bundle, file or account.',
+  },
+  conflict: {
+    exitCode: 6,
+    description: 'Someone else is changing it, or it exists with a different value.',
+    retryable: true,
+  },
+  confirmation_required: {
+    exitCode: 7,
+    description: 'It would have asked first, and there is no terminal to ask on.',
+  },
+  refused: {
+    exitCode: 8,
+    description:
+      'The site or the remote said no: findings outstanding, a permission, a protected environment.',
+  },
+  unavailable: {
+    exitCode: 9,
+    description: 'The database or the remote could not be reached.',
+    retryable: true,
+  },
+  io: { exitCode: 10, description: 'A file could not be read or written.' },
+  interrupted: { exitCode: 130, description: 'Stopped by a signal.' },
+} as const satisfies Record<string, { exitCode: number; description: string; retryable?: boolean }>
+
+export type ErrorKind = keyof typeof ERROR_KINDS
+
+/** Findings a command was asked to look for. Their details are the command's normal output. */
+export const OUTCOMES = {
+  problems_found: {
+    code: 20,
+    description: 'The check found problems: `status`, `types check`, `components check`.',
+  },
+  blocked: {
+    code: 21,
+    description:
+      'Something must be resolved by a person first: `content check`, `upgrade check`, `import umbraco report`.',
+  },
+} as const
+
+export type OutcomeName = keyof typeof OUTCOMES
+
+/** A failure with a kind, a sentence, and what to do about it. */
+export class CliError extends Error {
+  readonly hint?: string
+  readonly details?: unknown
+  constructor(
+    readonly kind: ErrorKind,
+    message: string,
+    options: { hint?: string; details?: unknown } = {},
+  ) {
+    super(message)
+    this.hint = options.hint
+    this.details = options.details
+  }
+}
+
+/** The command finished, and found what it reports: exit with the outcome's code, no envelope. */
+export class Outcome extends Error {
+  constructor(readonly outcome: OutcomeName) {
+    super(outcome)
+  }
+}
+
+export const exitCodeOf = (kind: ErrorKind): number => ERROR_KINDS[kind].exitCode

package/src/load.ts

@@ -0,0 +1,59 @@
+/**
+ * The CLI's commands, with the optional plugins found beside it (story 158).
+ *
+ * oclif loads a plugin only when the CLI's own `package.json` depends on it,
+ * and warns when one is missing; an optional plugin is neither. So each name in
+ * `oclif.optionalPlugins` is looked for here — in the site's `node_modules`,
+ * then beside the CLI, as a global install puts it — loaded when it is found,
+ * and passed over in silence when it is not.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { Config, Plugin } from '@oclif/core'
+import { CLI_DIR } from './manifest.ts'
+
+/** The directory a package is installed in, looked for from each of `from` upward. */
+export function findInstalled(name: string, from: readonly string[]): string | undefined {
+  for (const start of from) {
+    let dir = start
+    for (;;) {
+      const candidate = join(dir, 'node_modules', name)
+      if (existsSync(join(candidate, 'package.json'))) return candidate
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  }
+  return undefined
+}
+
+export function optionalPlugins(): string[] {
+  const pjson = JSON.parse(readFileSync(join(CLI_DIR, 'package.json'), 'utf8')) as {
+    oclif?: { optionalPlugins?: string[] }
+  }
+  return pjson.oclif?.optionalPlugins ?? []
+}
+
+export interface LoadedCli {
+  config: Config
+  /** The optional plugins that are not installed. */
+  missing: string[]
+}
+
+export async function loadCli(cwd: string = process.cwd()): Promise<LoadedCli> {
+  const root = new Plugin({ root: CLI_DIR, isRoot: true, type: 'core' })
+  await root.load()
+  const plugins = new Map<string, Plugin>([[root.name, root]])
+  const missing: string[] = []
+  for (const name of optionalPlugins()) {
+    const dir = findInstalled(name, [cwd, CLI_DIR])
+    if (!dir) {
+      missing.push(name)
+      continue
+    }
+    const plugin = new Plugin({ root: dir, name, type: 'core' })
+    await plugin.load()
+    plugins.set(plugin.name, plugin)
+  }
+  return { config: await Config.load({ root: CLI_DIR, plugins }), missing }
+}

package/src/main.ts

@@ -0,0 +1,41 @@
+/**
+ * Runs the CLI. A failure inside a command is reported by the command
+ * (`BaseCommand.catch`); one before any command runs — an unknown command —
+ * is reported here the same way, so every failure has a kind and an exit code.
+ */
+import { Errors, flush, run } from '@oclif/core'
+import { wantsJson } from './base.ts'
+import { CliError, exitCodeOf } from './errors.ts'
+import { loadCli } from './load.ts'
+
+/** The topic each optional plugin brings, and how to add it. */
+const PLUGIN_TOPICS: Record<string, { topic: string; what: string }> = {
+  '@crombolo/cloud': { topic: 'cloud', what: 'Crombolo Cloud' },
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  try {
+    const { config, missing } = await loadCli()
+    const absent = missing
+      .map((name) => ({ name, ...PLUGIN_TOPICS[name] }))
+      .find((plugin) => plugin.topic && argv[0] === plugin.topic)
+    if (absent)
+      throw new CliError(
+        'usage',
+        `\`crombolo ${absent.topic}\` comes with the ${absent.what} plugin, which is not installed.`,
+        {
+          hint: `Add it to the site: bun add -d ${absent.name}`,
+        },
+      )
+    await run(argv, config)
+    await flush()
+  } catch (error) {
+    if (error instanceof Errors.ExitError) process.exit(error.oclif.exit ?? 0)
+    const { classify, reportFailure } = await import('./classify.ts')
+    const failure = classify(error)
+    if (failure.kind === 'usage' && !failure.hint)
+      Object.assign(failure, { hint: '`crombolo --help` lists the commands.' })
+    reportFailure(failure, wantsJson(argv))
+    process.exit(exitCodeOf(failure.kind))
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,30 @@
+/**
+ * The CLI's `oclif.manifest.json`: every command's args, flags and clispec
+ * `spec`, cached so a start reads one file rather than importing every command.
+ */
+import { join } from 'node:path'
+import { Config, type Interfaces } from '@oclif/core'
+
+export const CLI_DIR = join(import.meta.dir, '..')
+export const MANIFEST_FILE = join(CLI_DIR, 'oclif.manifest.json')
+
+export async function buildManifest(): Promise<Interfaces.Manifest> {
+  const config = await Config.load(CLI_DIR)
+  const commands = Object.fromEntries(
+    config.commands
+      .map((command) => [command.id, command] as const)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  )
+  // Through JSON, as oclif reads it back: each command's `load` is dropped.
+  return JSON.parse(JSON.stringify({ commands, version: config.version })) as Interfaces.Manifest
+}
+
+/** The manifest's shape for any loaded config: the CLI's commands and its plugins'. */
+export function manifestOf(config: Config): Interfaces.Manifest {
+  const commands = Object.fromEntries(
+    config.commands
+      .map((command) => [command.id, command] as const)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  )
+  return JSON.parse(JSON.stringify({ commands, version: config.version })) as Interfaces.Manifest
+}

package/src/plugin.ts

@@ -0,0 +1,38 @@
+/**
+ * `@crombolo/cli/plugin`: what a plugin's commands are built from (story 158),
+ * so that they behave like the CLI's own — the global flags, the JSON envelope,
+ * the exit codes, an entry in `crombolo schema` — and sign in where `crombolo
+ * login` does. Covered by semver like the main entry. It loads none of the
+ * CLI's commands, and none of the site packages until a command fails.
+ *
+ *   import { Args, BaseCommand, Flags } from '@crombolo/cli/plugin'
+ *
+ *   export default class CloudStatus extends BaseCommand {
+ *     static override summary = 'what the platform says about this site'
+ *     static override spec = { effects: 'read_only', cardinality: 'single', outputFields: [...] } as const
+ *     async run() { … return result }
+ *   }
+ */
+export { Args, Flags } from '@oclif/core'
+export type { AuditSpec, CommandSpec, OutputField } from './base.ts'
+export { BaseCommand } from './base.ts'
+export {
+  CliError,
+  ERROR_KINDS,
+  type ErrorKind,
+  exitCodeOf,
+  OUTCOMES,
+  type OutcomeName,
+} from './errors.ts'
+export {
+  type Discovery,
+  discover,
+  type Job,
+  problemOf,
+  RemoteClient,
+  RemoteError,
+  signIn,
+  TimedOut,
+} from './remote/client.ts'
+export { keychain, openInBrowser } from './support/remote.ts'
+export type { Io } from './support/site.ts'

package/src/reference.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+import type { Interfaces } from '@oclif/core'
+import { clispecDocument } from './clispec.ts'
+
+const escapeHtml = (text: string): string =>
+  text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+
+const code = (text: string) => `<code>${escapeHtml(text)}</code>`
+
+interface Arg {
+  name: string
+  type: string
+  short?: string
+  required?: boolean
+  default?: unknown
+  enum?: unknown[]
+  description?: string
+}
+
+function usage(name: string, args: Arg[]): string {
+  const words = args.map((arg) => {
+    if (!arg.name.startsWith('--')) return arg.required ? `<${arg.name}>` : `[<${arg.name}>]`
+    const flag = arg.type === 'boolean' ? arg.name : `${arg.name} <${arg.name.slice(2)}>`
+    return arg.required ? flag : `[${flag}]`
+  })
+  return ['crombolo', name, ...words].join(' ')
+}
+
+/** A summary written for `--help` — "apply schema/ to the database" — as a sentence. */
+const sentence = (text: string): string => {
+  const trimmed = text.trim()
+  if (!trimmed) return ''
+  const capital = `${trimmed.charAt(0).toUpperCase()}${trimmed.slice(1)}`
+  return /[.!?]$/.test(capital) ? capital : `${capital}.`
+}
+
+function argRow(arg: Arg): string {
+  const name = [arg.short, arg.name].filter(Boolean).join(', ')
+  const notes = [
+    arg.description ? escapeHtml(sentence(arg.description)) : '',
+    arg.enum ? `One of ${arg.enum.map((v) => code(String(v))).join(', ')}.` : '',
+    arg.default !== undefined ? `Default ${code(String(arg.default))}.` : '',
+    arg.required ? 'Required.' : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+  return `<tr><td>${code(name)}</td><td>${notes}</td></tr>`
+}
+
+const EFFECTS: Record<string, string> = {
+  read_only: 'Changes nothing.',
+  idempotent: 'Safe to run again: a second run changes nothing more.',
+  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({
+    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>',
+  ]
+  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>`,
+        )
+    }
+  }
+  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>",
+  )
+  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(
+    `<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')
+}

package/src/remote/client.ts

@@ -6,7 +6,12 @@
  */
 import { createHash } from 'node:crypto'
 import { createWriteStream } from 'node:fs'
-import { freshAccessToken, type Keychain, readSignIn, saveSignIn } from '@crombolo/server'
+import {
+  freshAccessToken,
+  type Keychain,
+  readSignIn,
+  saveSignIn,
+} from '@crombolo/server/remote-credentials'
 
 export const PROTOCOL_VERSION = '1'
 
@@ -55,19 +60,28 @@ export async function discover(url: string, http: typeof fetch = fetch): Promise
   try {
     response = await http(`${origin}/.well-known/crombolo-remote`)
   } catch (error) {
-    throw new Error(
-      `${origin} could not be reached: ${error instanceof Error ? error.message : error}`,
-    )
+    throw new RemoteError({
+      status: 0,
+      code: 'unreachable',
+      title: `${origin} could not be reached: ${error instanceof Error ? error.message : error}`,
+    })
   }
-  if (response.status === 404) throw new Error(`${origin} is not a crombolo remote.`)
-  if (!response.ok)
-    throw new Error(`${origin} answered ${response.status} for its discovery document.`)
+  const notARemote = () =>
+    new RemoteError({
+      status: 404,
+      code: 'not-a-remote',
+      title: `${origin} is not a crombolo remote.`,
+    })
+  if (response.status === 404) throw notARemote()
+  if (!response.ok) throw await problemOf(response)
   const body = (await response.json()) as Discovery
-  if (body.protocol !== 'crombolo-remote') throw new Error(`${origin} is not a crombolo remote.`)
+  if (body.protocol !== 'crombolo-remote') throw notARemote()
   if (!body.versions?.includes(PROTOCOL_VERSION))
-    throw new Error(
-      `${origin} speaks protocol ${body.versions?.join(', ') || 'none'}; this crombolo speaks ${PROTOCOL_VERSION}.`,
-    )
+    throw new RemoteError({
+      status: 0,
+      code: 'protocol-version',
+      title: `${origin} speaks protocol ${body.versions?.join(', ') || 'none'}; this crombolo speaks ${PROTOCOL_VERSION}.`,
+    })
   return body
 }
 

package/src/remote/remotes-file.ts

@@ -6,8 +6,9 @@
  *   url = "https://example.com"
  *   environment = "production"
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { writeFileAtomic } from '@crombolo/server/atomic-write'
 
 export const REMOTES_FILE = 'remotes.toml'
 
@@ -50,7 +51,7 @@ export function writeRemotes(siteDir: string, remotes: readonly RemoteEntry[]):
     lines.push('', `[remotes.${remote.name}]`, `url = ${quote(remote.url)}`)
     if (remote.environment) lines.push(`environment = ${quote(remote.environment)}`)
   }
-  writeFileSync(join(siteDir, REMOTES_FILE), `${lines.join('\n')}\n`)
+  writeFileAtomic(join(siteDir, REMOTES_FILE), `${lines.join('\n')}\n`)
 }
 
 /** Adds or replaces one, refusing a name that would not survive as a TOML key. */

package/src/remote/transfer.ts

@@ -8,7 +8,7 @@
  * uploads it as a job — which the remote may hold for approval.
  */
 import { randomBytes } from 'node:crypto'
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import {
@@ -18,8 +18,10 @@ import {
   extractTarball,
   type MediaStore,
   mediaStoreFor,
+  writeFileAtomic,
 } from '@crombolo/server'
 import { type BundleBlob, loadBundle } from '@crombolo/transfer'
+import { CliError, type ErrorKind } from '../errors.ts'
 import { type Job, problemOf, type RemoteClient, RemoteError, sha256File } from './client.ts'
 
 export type MediaMode = 'included' | 'omitted' | 'referenced'
@@ -27,8 +29,12 @@ export type MediaMode = 'included' | 'omitted' | 'referenced'
 /** A passphrase for one transfer: never shown, never stored. */
 export const transferPassphrase = () => randomBytes(24).toString('base64url')
 
-/** Refused before anything was sent: the CLI's own guard, exit code 2. */
-export class RefusedBeforeSending extends Error {}
+/** Refused before anything was sent: the CLI's own guard. */
+export class RefusedBeforeSending extends CliError {
+  constructor(kind: ErrorKind, message: string, hint?: string) {
+    super(kind, message, { hint })
+  }
+}
 
 export interface PullResult {
   job: Job
@@ -54,15 +60,18 @@ export async function pullFile(
   const env = environments.find((e) => e.id === options.environment)
   if (!env)
     throw new RefusedBeforeSending(
+      'not_found',
       `${client.discovery.name} has no environment "${options.environment}": it has ${environments.map((e) => e.id).join(', ')}.`,
     )
-  if (!env.may.pull) throw new RefusedBeforeSending(`You may not pull from ${env.name}.`)
+  if (!env.may.pull) throw new RefusedBeforeSending('refused', `You may not pull from ${env.name}.`)
   if (options.full && !env.may.pullFull)
     throw new RefusedBeforeSending(
+      'refused',
       `You may not pull a full copy of ${env.name}; pull without --full for an anonymised one.`,
     )
   if (options.media === 'referenced' && !client.discovery.capabilities.includes('media-fetch'))
     throw new RefusedBeforeSending(
+      'refused',
       `${client.discovery.name} does not serve media by reference; pull without --media-info-only.`,
     )
   const passphrase = transferPassphrase()
@@ -163,8 +172,7 @@ export async function fetchReferencedMedia(
     }
     await Promise.all(Array.from({ length: 6 }, worker))
   }
-  mkdirSync(join(options.siteDir, '.crombolo'), { recursive: true })
-  writeFileSync(join(options.siteDir, FETCHED_FILE), `${JSON.stringify(fetched, null, 2)}\n`)
+  writeFileAtomic(join(options.siteDir, FETCHED_FILE), `${JSON.stringify(fetched, null, 2)}\n`)
   return result
 }
 
@@ -192,7 +200,8 @@ export interface PushCheck {
 
 export interface PushResult {
   check: PushCheck
-  job: Job
+  /** Absent for a dry run, which stops after the check. */
+  job?: Job
 }
 
 /**
@@ -209,6 +218,8 @@ export async function pushSite(
     force?: boolean
     autoApprove?: boolean
     mediaInfoOnly?: boolean
+    /** Export and check, then stop: nothing is uploaded. */
+    dryRun?: boolean
     confirm?(check: PushCheck): Promise<boolean>
     onCheck?(check: PushCheck): void
     onProgress?(job: Job): void
@@ -222,15 +233,19 @@ export async function pushSite(
   const env = environments.find((e) => e.id === options.environment)
   if (!env)
     throw new RefusedBeforeSending(
+      'not_found',
       `${client.discovery.name} has no environment "${options.environment}".`,
     )
-  if (!env.may.push) throw new RefusedBeforeSending(`You may not push to ${env.name}.`)
-  if (env.protected && !options.force)
+  if (!env.may.push) throw new RefusedBeforeSending('refused', `You may not push to ${env.name}.`)
+  if (env.protected && !options.force && !options.dryRun)
     throw new RefusedBeforeSending(
-      `${env.name} is protected: pushing replaces what people rely on. Pass --force to go on.`,
+      'confirmation_required',
+      `${env.name} is protected: pushing replaces what people rely on.`,
+      'Pass --force to go on.',
     )
   if (options.mediaInfoOnly && !client.discovery.capabilities.includes('media-fetch'))
     throw new RefusedBeforeSending(
+      'refused',
       `${client.discovery.name} does not take media by reference; push without --media-info-only.`,
     )
 
@@ -280,9 +295,10 @@ export async function pushSite(
           sending,
         }
     options.onCheck?.(check)
+    if (options.dryRun) return { check }
     if (env.protected && !options.autoApprove) {
       const yes = (await options.confirm?.(check)) ?? false
-      if (!yes) throw new RefusedBeforeSending('Nothing was sent.')
+      if (!yes) throw new RefusedBeforeSending('refused', 'Nothing was sent.')
     }
 
     if (options.mediaInfoOnly && manifest.blobs.length > 0) {

package/src/support/components.ts

@@ -0,0 +1,7 @@
+/** The content types 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 : []