@crombolo/cli 0.14.4 → 0.15.0

package/src/commands/generate.ts

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

package/src/commands/import/index.ts

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

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

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

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

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

package/src/commands/init.ts

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

package/src/commands/login.ts

@@ -0,0 +1,38 @@
+import { hostname } from 'node:os'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { signIn } from '../remote/client.ts'
+import { connectRemote, keychain, openInBrowser } from '../support/remote.ts'
+
+export default class Login extends BaseCommand {
+  static override summary = 'sign in to a remote with a code you approve in its back office'
+  static override description =
+    'The sign-in is kept in your keychain. It waits for the approval, printing where to give it; no terminal is needed.'
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override flags = {
+    'no-browser': Flags.boolean({ summary: "don't open the approval page" }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [{ name: 'remote', type: 'string' }],
+    errors: ['not_found', 'auth', 'timeout', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(Login)
+    const { entry, discovery } = await connectRemote(args.remote, undefined)
+    await signIn(discovery, keychain(), {
+      clientName: `crombolo on ${hostname()}`,
+      onCode: (code, url) => {
+        this.progress(`  Approve this sign-in at ${url}`)
+        this.progress(`  and check it shows   ${code}`)
+        openInBrowser(url, flags['no-browser'])
+      },
+    })
+    this.say(`  signed in to ${entry.name}`)
+    return { remote: entry.name }
+  }
+}

package/src/commands/logout.ts

@@ -0,0 +1,36 @@
+import { forgetSignIn, readSignIn } from '@crombolo/server'
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { connectRemote, keychain } from '../support/remote.ts'
+
+export default class Logout extends BaseCommand {
+  static override summary = 'sign out of a remote, here and at the remote'
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'remote', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(Logout)
+    const { entry, discovery } = await connectRemote(args.remote, undefined)
+    const signedIn = await readSignIn(keychain(), discovery.api)
+    // Ended at the remote too, best effort: the device leaves "Signed-in devices".
+    if (signedIn)
+      await fetch(signedIn.tokenUrl.replace(/\/token$/, '/revoke'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ token: signedIn.accessToken }).toString(),
+      }).catch(() => undefined)
+    await forgetSignIn(keychain(), discovery.api)
+    this.say(`  signed out of ${entry.name}`)
+    return { remote: entry.name, changed: signedIn !== undefined }
+  }
+}

package/src/commands/maintenance/pause.ts

@@ -0,0 +1,29 @@
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** The cluster-wide pause on editing that a restore or a swap needs: a database flag every node reads. */
+export default class MaintenancePause extends BaseCommand {
+  static override summary = "refuse every editor's save, on every node, until resumed"
+  static override description = 'Readers are unaffected and no node drains.'
+  static override flags = {
+    reason: Flags.string({ summary: 'what editors are told', helpValue: '<text>' }),
+  }
+  static override audit = { category: 'system', action: 'PauseEditing' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'paused', type: 'boolean' },
+      { name: 'reason', type: 'string', nullable: true },
+    ],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(MaintenancePause)
+    const paused = await ops.pauseEditing(await siteConfig(), { reason: flags.reason })
+    this.say(`Editing paused${paused.reason ? `: ${paused.reason}` : ''}.`)
+    return { paused: true, reason: paused.reason ?? null }
+  }
+}

package/src/commands/maintenance/resume.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class MaintenanceResume extends BaseCommand {
+  static override summary = 'let editors save again'
+  static override audit = { category: 'system', action: 'ResumeEditing' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [{ name: 'paused', type: 'boolean' }],
+  } as const
+
+  async run() {
+    await this.parse(MaintenanceResume)
+    await ops.resumeEditing(await siteConfig())
+    this.say('Editing resumed.')
+    return { paused: false }
+  }
+}

package/src/commands/maintenance/status.ts

@@ -0,0 +1,34 @@
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class MaintenanceStatus extends BaseCommand {
+  static override summary = 'whether editing is paused, by whom and why'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      {
+        name: 'paused',
+        type: 'object',
+        nullable: true,
+        fields: [
+          { name: 'at', type: 'string' },
+          { name: 'by', type: 'string', nullable: true },
+          { name: 'reason', type: 'string', nullable: true },
+        ],
+      },
+    ],
+  } as const
+
+  async run() {
+    await this.parse(MaintenanceStatus)
+    const paused = await ops.editingPaused(await siteConfig())
+    this.say(
+      paused
+        ? `Editing paused since ${paused.at}${paused.by ? ` by ${paused.by}` : ''}${paused.reason ? `: ${paused.reason}` : ''}.`
+        : 'Editing is not paused.',
+    )
+    return { paused: paused ?? null }
+  }
+}