@crombolo/cli 0.14.4 → 0.15.0

package/src/commands/media/fetch.ts

@@ -0,0 +1,62 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { mediaStoreFor, readRemoteMedia } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { discover, RemoteClient } from '../../remote/client.ts'
+import { fetchReferencedMedia } from '../../remote/transfer.ts'
+import { describeBytes } from '../../support/describe.ts'
+import { keychain } from '../../support/remote.ts'
+import { cwd, siteConfig } from '../../support/site.ts'
+
+export default class MediaFetch extends BaseCommand {
+  static override summary = "a lazily pulled site's media files, all of them now"
+  static override description =
+    'Exits 10 when a file could not be fetched; running it again fetches only what is missing.'
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'fetched', type: 'integer' },
+      { name: 'skipped', type: 'integer' },
+      { name: 'bytes', type: 'integer' },
+      { name: 'failed', type: 'array', items: { type: 'string' } },
+    ],
+    errors: ['not_found', 'auth', 'unavailable', 'io'],
+  } as const
+
+  async run() {
+    await this.parse(MediaFetch)
+    const source = readRemoteMedia(cwd())
+    const listed = join(cwd(), '.crombolo', 'remote-media-blobs.json')
+    if (!source || !existsSync(listed))
+      this.fail(
+        'not_found',
+        'This site was not pulled with --lazy-media: there is nothing to fetch.',
+      )
+    const client = new RemoteClient(await discover(source.api), keychain())
+    const blobs = JSON.parse(await Bun.file(listed).text()) as {
+      key: string
+      etag: string | null
+    }[]
+    const fetched = await fetchReferencedMedia(client, {
+      environment: source.environment,
+      blobs,
+      store: await mediaStoreFor(await siteConfig()),
+      siteDir: cwd(),
+      onProgress: (done, total) => {
+        if (done % 50 === 0 || done === total) this.progress(`  ${done}/${total}`)
+      },
+    })
+    this.say(
+      `  media    ${fetched.fetched} fetched (${describeBytes(fetched.bytes)}), ${fetched.skipped} already here`,
+    )
+    if (fetched.failed.length > 0)
+      this.fail(
+        'io',
+        `${fetched.failed.length} file(s) could not be fetched.`,
+        'Run it again to fetch them.',
+        fetched.failed,
+      )
+    return fetched
+  }
+}

package/src/commands/pull.ts

@@ -0,0 +1,210 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { mediaStoreFor, writeRemoteMedia } from '@crombolo/server'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import * as ops from '../operations/commands.ts'
+import { fetchReferencedMedia, pullFile, referencedBlobs } from '../remote/transfer.ts'
+import {
+  counted,
+  describeBytes,
+  describeJob,
+  findingsOf,
+  printTransferFindings,
+} from '../support/describe.ts'
+import { backupTaken } from '../support/flags.ts'
+import { confirm } from '../support/prompt.ts'
+import { connectRemote, needEnvironment } from '../support/remote.ts'
+import { serveSite, startFromFile } from '../support/serve.ts'
+import { cwd, hasSite, siteConfig } from '../support/site.ts'
+
+export default class Pull extends BaseCommand {
+  static override summary = 'a copy of a remote environment: started here, or replacing this site'
+  static override description = [
+    'Sealed and anonymised unless --full. In an empty folder it starts a new site and serves it; in a site it replaces it, saying first what it loses (recycled, and asked about unless --yes).',
+    '--media-info-only fetches media files one at a time, only what changed since the last pull; --lazy-media fetches each the first time it is asked for; --no-media leaves them out.',
+  ].join('\n\n')
+  static override examples = ['<%= config.bin %> pull production --env staging --yes']
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override flags = {
+    env: Flags.string({ summary: 'the environment to pull', helpValue: '<id>' }),
+    full: Flags.boolean({ summary: 'a full copy, people included: needs the permission for it' }),
+    yes: Flags.boolean({ summary: 'replace this site without asking' }),
+    'no-media': Flags.boolean({ summary: 'leave the media files out' }),
+    'media-info-only': Flags.boolean({
+      summary: 'fetch media files one at a time, only what changed',
+    }),
+    'lazy-media': Flags.boolean({
+      summary: 'fetch each media file the first time it is asked for',
+    }),
+    timeout: Flags.integer({
+      summary: 'seconds to wait for the remote before giving up',
+      default: 1800,
+      min: 1,
+    }),
+    'backup-taken': backupTaken,
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    confirmationBypassArg: '--yes',
+    outputFields: [
+      { name: 'environment', type: 'string' },
+      { name: 'size', type: 'integer' },
+      { name: 'anonymised', type: 'boolean' },
+      { name: 'started', type: 'boolean' },
+      { name: 'runId', type: 'string' },
+      { name: 'media', type: 'object', nullable: true },
+      {
+        name: 'serving',
+        type: 'object',
+        description: 'in an empty folder: where the new site answers',
+      },
+    ],
+    errors: [
+      'usage',
+      'auth',
+      'not_found',
+      'refused',
+      'timeout',
+      'unavailable',
+      'confirmation_required',
+    ],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(Pull)
+    const { client, environment: env, discovery } = await connectRemote(args.remote, flags.env)
+    const environment = needEnvironment(env, discovery)
+    const media = flags['no-media']
+      ? ('omitted' as const)
+      : flags['media-info-only'] || flags['lazy-media']
+        ? ('referenced' as const)
+        : ('included' as const)
+    const incoming = join(cwd(), '.crombolo', 'transfer', 'incoming')
+    await mkdir(incoming, { recursive: true })
+    const out = join(incoming, `pull-${environment}-${Date.now().toString(36)}.tgz`)
+    const pulled = await pullFile(client, {
+      environment,
+      out,
+      full: flags.full,
+      media,
+      onProgress: (job) => this.progress(describeJob(job)),
+      timeoutMs: flags.timeout * 1000,
+    })
+    this.progress(`  pulled   ${describeBytes(pulled.size)}${flags.full ? '' : ', anonymised'}`)
+
+    const existing = hasSite()
+    let runId: string
+    if (!existing) {
+      const started = await startFromFile(this, out, {
+        postgres: false,
+        install: true,
+        allowMissingMedia: media !== 'included',
+        passphrase: pulled.passphrase,
+      })
+      runId = started.runId
+    } else {
+      const config = await siteConfig()
+      const { summary } = await ops.siteReplaceCheck(config, {
+        bundle: out,
+        passphrase: pulled.passphrase,
+        replace: 'replace',
+        allowMissingBlobs: media !== 'included',
+      })
+      if (Object.keys(summary.leaving).length > 0)
+        this.say(`  recycled ${counted(summary.leaving)} here, not in ${environment}`)
+      if (summary.filesRemoved.length > 0)
+        this.say(`  removes  ${summary.filesRemoved.length} file(s) here, kept for a revert`)
+      if (!flags.yes)
+        await confirm(`  Replace this site with ${environment}? [y/N]`, { bypass: '--yes' })
+      const result = await ops.contentImport(config, {
+        bundle: out,
+        passphrase: pulled.passphrase,
+        replace: 'replace',
+        allowMissingBlobs: media !== 'included',
+        label: `pull from ${environment}`,
+        backupTaken: flags['backup-taken'],
+      })
+      for (const problem of result.problems) this.warning(`  ${problem}`)
+      if (!result.runId) {
+        printTransferFindings(this, result.check)
+        this.fail(
+          'refused',
+          'pull refused. Nothing was changed.',
+          undefined,
+          findingsOf(result.check.outstanding),
+        )
+      }
+      runId = result.runId
+      this.say(`  replaced, run ${runId}: \`crombolo content revert ${runId}\` puts it back`)
+    }
+
+    let fetched: {
+      fetched: number
+      skipped: number
+      bytes: number
+      failed: string[]
+      lazy: boolean
+    } | null = null
+    if (media === 'referenced') {
+      const config = await siteConfig()
+      const blobs = await referencedBlobs(out)
+      if (flags['lazy-media']) {
+        writeRemoteMedia(cwd(), { api: discovery.api, environment })
+        await writeFile(
+          join(cwd(), '.crombolo', 'remote-media-blobs.json'),
+          `${JSON.stringify(
+            blobs.map((b) => ({ key: b.key, etag: b.etag })),
+            null,
+            2,
+          )}\n`,
+        )
+        this.say(
+          `  media    ${blobs.length} file(s) fetched from ${environment} as they are first asked for`,
+        )
+        fetched = { fetched: 0, skipped: 0, bytes: 0, failed: [], lazy: true }
+      } else {
+        const result = await fetchReferencedMedia(client, {
+          environment,
+          blobs,
+          store: await mediaStoreFor(config),
+          siteDir: cwd(),
+        })
+        this.say(
+          `  media    ${result.fetched} fetched (${describeBytes(result.bytes)}), ${result.skipped} already here`,
+        )
+        for (const key of result.failed)
+          this.warning(`  missing  ${key}: run the pull again to fetch it`)
+        fetched = { ...result, lazy: false }
+      }
+    }
+    const summary = {
+      environment,
+      size: pulled.size,
+      anonymised: !flags.full,
+      started: !existing,
+      runId,
+      media: fetched,
+    }
+    if (!existing) {
+      // A new site serves, as `start --from` does, so its one record is written before it does.
+      const serving = await serveSite(this, {
+        keepAdmin: true,
+        bundles: [],
+        backupTaken: false,
+        resolve: [],
+        'allow-missing-blobs': false,
+        publish: false,
+        'no-schema': false,
+        'no-files': false,
+        'replace-files': false,
+      })
+      if (this.jsonEnabled()) process.stdout.write(`${JSON.stringify({ ...summary, serving })}\n`)
+      return
+    }
+    return summary
+  }
+}

package/src/commands/push.ts

@@ -0,0 +1,108 @@
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { pushSite } from '../remote/transfer.ts'
+import { counted, describeJob } from '../support/describe.ts'
+import { confirm } from '../support/prompt.ts'
+import { connectRemote, needEnvironment, openInBrowser } from '../support/remote.ts'
+import { siteConfig } from '../support/site.ts'
+
+export default class Push extends BaseCommand {
+  static override summary = 'replace a remote environment with this site'
+  static override description = [
+    'Shows what it would replace first; --dry-run stops there.',
+    "A protected environment needs --force and its name typed back (--auto-approve skips that), and the remote may also hold it for someone else's approval.",
+  ].join('\n\n')
+  static override examples = [
+    '<%= config.bin %> push production --env staging --dry-run',
+    '<%= config.bin %> push production --env live --force --auto-approve',
+  ]
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override flags = {
+    env: Flags.string({ summary: 'the environment to replace', helpValue: '<id>' }),
+    force: Flags.boolean({ summary: 'go on to a protected environment' }),
+    'auto-approve': Flags.boolean({ summary: "with --force: don't ask for its name" }),
+    'media-info-only': Flags.boolean({
+      summary: 'send media files one at a time, only what the remote lacks',
+    }),
+    'dry-run': Flags.boolean({ summary: 'say what it would replace, and send nothing' }),
+    timeout: Flags.integer({
+      summary: 'seconds to wait for the remote before giving up',
+      default: 1800,
+      min: 1,
+    }),
+    'no-browser': Flags.boolean({ summary: "don't open an approval page" }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    confirmationBypassArg: '--auto-approve',
+    outputFields: [
+      { name: 'environment', type: 'string' },
+      { name: 'check', type: 'object' },
+      { name: 'job', type: 'object', nullable: true },
+    ],
+    errors: [
+      'usage',
+      'auth',
+      'not_found',
+      'refused',
+      'timeout',
+      'unavailable',
+      'confirmation_required',
+    ],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(Push)
+    const { client, environment: env, discovery } = await connectRemote(args.remote, flags.env)
+    const environment = needEnvironment(env, discovery)
+    if (flags['dry-run']) this.changedNothing = true
+    const { check, job } = await pushSite(await siteConfig(), client, {
+      environment,
+      force: flags.force,
+      autoApprove: flags['auto-approve'],
+      mediaInfoOnly: flags['media-info-only'],
+      dryRun: flags['dry-run'],
+      timeoutMs: flags.timeout * 1000,
+      onCheck: (c) => {
+        this.say(
+          `  sending  ${counted(c.sending.counts, 'no content')}, ${c.sending.files} file(s)`,
+        )
+        if (c.fromRemote) {
+          if (Object.keys(c.recycles).length > 0)
+            this.say(`  recycles ${counted(c.recycles)} on ${environment}`)
+          if (c.removesFiles.length > 0)
+            this.say(`  removes  ${c.removesFiles.join(', ')} on ${environment}`)
+        }
+      },
+      confirm: async () => {
+        await confirm(`  This replaces ${environment}. Type its name to go on:`, {
+          bypass: '--auto-approve',
+          answer: environment,
+          declined: 'Nothing was sent.',
+        })
+        return true
+      },
+      onProgress: (j) => this.progress(describeJob(j)),
+      onApproval: (j) => {
+        this.progress(`  waiting  for someone else to approve it: ${j.approvalUrl}`)
+        if (j.approvalUrl) openInBrowser(j.approvalUrl, flags['no-browser'])
+      },
+    })
+    if (!job) {
+      this.say('\n  Nothing was sent: that is what a push would replace.')
+      return { environment, check, job: null }
+    }
+    if (job.state !== 'done')
+      this.fail(
+        'refused',
+        job.problem?.title ?? `the push ended ${job.state}`,
+        undefined,
+        job.problem?.items,
+      )
+    this.say(`\n  pushed   ${environment} replaced, run ${job.runId ?? '—'}`)
+    return { environment, check, job }
+  }
+}

package/src/commands/remote/add.ts

@@ -0,0 +1,78 @@
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { discover } from '../../remote/client.ts'
+import { addRemote, readRemotes } from '../../remote/remotes-file.ts'
+import { cwd } from '../../support/site.ts'
+
+export default class RemoteAdd extends BaseCommand {
+  static override summary = 'a remote this site pulls from and pushes to, kept in remotes.toml'
+  static override description =
+    'URLs only: sign-ins are kept in your keychain. Adding the same remote again changes nothing; a different URL for a name already taken needs --force.'
+  static override examples = [
+    '<%= config.bin %> remote add production https://example.com --env production',
+  ]
+  static override args = {
+    name: Args.string({
+      required: true,
+      description: 'a name for it: lower case letters, digits and dashes',
+    }),
+    url: Args.string({ required: true, description: "the site's URL" }),
+  }
+  static override flags = {
+    env: Flags.string({ summary: 'the environment it goes to by default', helpValue: '<id>' }),
+    force: Flags.boolean({ summary: 'replace a remote of the same name' }),
+  }
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'name', type: 'string' },
+      { name: 'url', type: 'string' },
+      { name: 'site', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+      {
+        name: 'environments',
+        type: 'array',
+        items: {
+          type: 'object',
+          fields: [
+            { name: 'id', type: 'string' },
+            { name: 'protected', type: 'boolean' },
+          ],
+        },
+      },
+    ],
+    errors: ['usage', 'conflict', 'unavailable', 'not_found'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(RemoteAdd)
+    const origin = new URL(args.url).origin
+    const entry = { name: args.name, url: origin, environment: flags.env }
+    const existing = readRemotes(cwd()).find((remote) => remote.name === args.name)
+    const same = existing?.url === origin && existing.environment === flags.env
+    if (existing && !same && !flags.force)
+      this.fail(
+        'conflict',
+        `There is already a remote "${args.name}": ${existing.url}${existing.environment ? ` (env ${existing.environment})` : ''}.`,
+        'Pass --force to replace it, or choose another name.',
+      )
+    const discovery = await discover(args.url)
+    if (!same) {
+      try {
+        addRemote(cwd(), entry)
+      } catch (error) {
+        this.fail('usage', error instanceof Error ? error.message : String(error))
+      }
+    }
+    this.say(`  ${same ? 'exists ' : 'added  '}  ${args.name}  ${discovery.name} (${origin})`)
+    const environments = discovery.environments.map((env) => ({
+      id: env.id,
+      protected: env.protected === true,
+    }))
+    for (const env of environments)
+      this.say(`  env      ${env.id}${env.protected ? '  protected' : ''}`)
+    this.say(`\n\`crombolo login ${args.name}\` signs in.`)
+    return { name: args.name, url: origin, site: discovery.name, changed: !same, environments }
+  }
+}

package/src/commands/remote/job.ts

@@ -0,0 +1,53 @@
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeJob } from '../../support/describe.ts'
+import { connectRemote } from '../../support/remote.ts'
+
+export default class RemoteJob extends BaseCommand {
+  static override summary = 'watch a pull or push job again, after a wait gave up'
+  static override description =
+    "Exits 0 when the job is done, and with the job's own failure otherwise."
+  static override args = {
+    id: Args.string({ required: true, description: 'the job id the wait printed' }),
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override flags = {
+    timeout: Flags.integer({ summary: 'seconds to wait before giving up', default: 1800, min: 1 }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'kind', type: 'string' },
+      { name: 'state', type: 'string' },
+      { name: 'environment', type: 'string' },
+      { name: 'runId', type: 'string', nullable: true },
+    ],
+    errors: ['timeout', 'not_found', 'auth', 'refused', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(RemoteJob)
+    const { client } = await connectRemote(args.remote, undefined)
+    const job = await client.settle(args.id, {
+      onProgress: (j) => this.progress(describeJob(j)),
+      timeoutMs: flags.timeout * 1000,
+    })
+    if (job.state !== 'done')
+      this.fail(
+        'refused',
+        job.problem?.title ?? `The ${job.kind} ended ${job.state}.`,
+        undefined,
+        job.problem?.items,
+      )
+    this.say(`  ${job.kind} ${job.state}${job.runId ? `, run ${job.runId}` : ''}`)
+    return {
+      id: job.id,
+      kind: job.kind,
+      state: job.state,
+      environment: job.environment,
+      runId: job.runId ?? null,
+    }
+  }
+}

package/src/commands/remote/list.ts

@@ -0,0 +1,41 @@
+import { readSignIn } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { readRemotes } from '../../remote/remotes-file.ts'
+import { keychain } from '../../support/remote.ts'
+import { cwd } from '../../support/site.ts'
+
+export default class RemoteList extends BaseCommand {
+  static override summary = 'the remotes in remotes.toml, and whether you are signed in to each'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'bounded',
+    // One item of `items`, as clispec reads a collection.
+    outputFields: [
+      { name: 'name', type: 'string' },
+      { name: 'url', type: 'string' },
+      { name: 'environment', type: 'string', nullable: true },
+      { name: 'signedIn', type: 'boolean' },
+    ],
+  } as const
+
+  async run() {
+    await this.parse(RemoteList)
+    const remotes = readRemotes(cwd())
+    if (remotes.length === 0) this.say('  No remotes yet: `crombolo remote add <name> <url>`.')
+    const items = []
+    for (const remote of remotes) {
+      const signedIn =
+        (await readSignIn(keychain(), remote.url).catch(() => undefined)) !== undefined
+      this.say(
+        `  ${remote.name.padEnd(12)} ${remote.url}${remote.environment ? `  env ${remote.environment}` : ''}${signedIn ? '' : '  (not signed in)'}`,
+      )
+      items.push({
+        name: remote.name,
+        url: remote.url,
+        environment: remote.environment ?? null,
+        signedIn,
+      })
+    }
+    return { items }
+  }
+}

package/src/commands/remote/remove.ts

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { removeRemote } from '../../remote/remotes-file.ts'
+import { cwd } from '../../support/site.ts'
+
+export default class RemoteRemove extends BaseCommand {
+  static override summary = 'forget a remote; removing one that is not there changes nothing'
+  static override args = { name: Args.string({ required: true, description: "the remote's name" }) }
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'name', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(RemoteRemove)
+    const changed = removeRemote(cwd(), args.name)
+    this.say(
+      changed ? `  removed  ${args.name}` : `  There is no remote "${args.name}"; nothing changed.`,
+    )
+    return { name: args.name, changed }
+  }
+}

package/src/commands/schema.ts

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../base.ts'
+import { clispecDocument } from '../clispec.ts'
+
+export default class Schema extends BaseCommand {
+  static override summary = 'this CLI described for machines, as a clispec v0.3 document'
+  static override description = [
+    'Every command, its arguments, what it changes, what it prints and how it fails (https://clispec.dev). Name a command to narrow it. It reads no site, no network and no sign-in.',
+    'Until the next release, `schema check`, `schema sync` and the rest still run the `types` commands they were renamed to.',
+  ].join('\n\n')
+  static override examples = ['<%= config.bin %> schema', '<%= config.bin %> schema content import']
+  static override strict = false
+  static override usage = 'schema [COMMAND...]'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    stdoutSchema: { $ref: 'https://clispec.dev/schema/v0.3.json' },
+    errors: ['not_found'],
+  } as const
+
+  async run() {
+    const { argv } = await this.parse(Schema)
+    const path = argv.filter(
+      (arg): arg is string => typeof arg === 'string' && !arg.startsWith('-'),
+    )
+    const document = clispecDocument(this.config, path)
+    if (document.commands.length === 0)
+      this.fail('not_found', `There is no command "${path.join(' ')}".`)
+    // The document is the output in either mode: JSON is what it is.
+    if (!this.jsonEnabled()) process.stdout.write(`${JSON.stringify(document, null, 2)}\n`)
+    return document
+  }
+}

package/src/commands/start.ts

@@ -0,0 +1,64 @@
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { backupTaken, many, transferFlags } from '../support/flags.ts'
+import { serveSite, startFromFile } from '../support/serve.ts'
+
+export default class Start extends BaseCommand {
+  static override summary = 'boot the site in the current directory'
+  static override description = [
+    "In development it resets and prints the administrator's password on every start; --keep-admin leaves it alone.",
+    "--bundle applies a bundle's content first, once per bundle, taking the `content import` flags.",
+    "--from, in an empty folder: scaffold a site, install it, import a whole-site file (`crombolo export --site`) and serve it; the new administrator's password is printed once.",
+    'It serves until stopped. With -o json it prints one object saying where it answers.',
+  ].join('\n\n')
+  static override examples = [
+    '<%= config.bin %> start',
+    '<%= config.bin %> start --bundle ./bundles/demo --publish',
+    '<%= config.bin %> start --from site-2026-10-01.tgz',
+  ]
+  static override flags = {
+    'keep-admin': Flags.boolean({ summary: "don't touch the administrator's password" }),
+    bundle: many("apply a bundle's content first; repeatable", '<pkg>'),
+    from: Flags.string({
+      summary: 'in an empty folder: a site from a whole-site file',
+      helpValue: '<file>',
+    }),
+    postgres: Flags.boolean({ summary: 'with --from: configure Postgres' }),
+    name: Flags.string({ summary: "with --from: the site's name", helpValue: '<site name>' }),
+    'no-install': Flags.boolean({ summary: 'with --from: skip `bun install`' }),
+    'allow-missing-media': Flags.boolean({
+      summary: 'with --from: import media items whose files the file does not carry',
+    }),
+    label: Flags.string({ summary: "a label for a bundle's import run", helpValue: '<text>' }),
+    'backup-taken': backupTaken,
+    ...transferFlags,
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    outputKind: 'stream',
+    errors: ['not_found', 'conflict', 'refused', 'unavailable', 'auth'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(Start)
+    let keepAdmin = flags['keep-admin']
+    if (flags.from) {
+      await startFromFile(this, flags.from, {
+        name: flags.name,
+        postgres: flags.postgres,
+        install: !flags['no-install'],
+        allowMissingMedia: flags['allow-missing-media'],
+      })
+      // The password printed above is the one to use: this first start leaves it alone.
+      keepAdmin = true
+    }
+    const started = await serveSite(this, {
+      ...flags,
+      keepAdmin,
+      bundles: flags.bundle,
+      backupTaken: flags['backup-taken'],
+    })
+    // A stream: one record when it is up, then it serves until it is stopped.
+    if (this.jsonEnabled()) process.stdout.write(`${JSON.stringify(started)}\n`)
+  }
+}