@crombolo/cli 0.13.2 → 0.14.4

package/bin/crombolo.ts

@@ -6,6 +6,7 @@
  *   crombolo start                  boot the site; resets and prints the admin password
  *   crombolo start --keep-admin     boot without touching the admin password
  *   crombolo start --bundle <pkg>   apply a bundle's content, once, then serve
+ *   crombolo start --from <file>    in an empty folder: a working site from a whole-site file
  *   crombolo init                   scaffold a site in the current directory
  *   crombolo init --template <id>   …from a starter template, content included
  *   crombolo status                 what this environment is, without starting it
@@ -20,6 +21,7 @@
  *   crombolo components check       compile every component before a visitor does
  *   crombolo assets list            the stylesheets and scripts beside them
  *
+ *   crombolo export --site          write the whole site to one file, to move it to another machine or host
  *   crombolo content export         write a subtree as a private bundle package, to move to another environment
  *   crombolo content check          read-only: what installing a bundle's content here would do
  *   crombolo content import         apply a bundle's content, in one transaction, and record the run
@@ -29,6 +31,11 @@
  *   crombolo domains                the hostnames this site answers on
  *   crombolo domains set            write domains.toml and apply it
  *
+ *   crombolo import <file>          replace this site with a whole-site file; says what first
+ *   crombolo remote add|list|remove the remotes this site pulls from and pushes to (remotes.toml)
+ *   crombolo login|logout|whoami    sign in to a remote with a code you approve in its back office
+ *   crombolo pull [<remote>]        a copy of a remote environment: started here, or replacing this site
+ *   crombolo push [<remote>]        replace a remote environment with this site
  *   crombolo import umbraco report  read-only: what importing an Umbraco backup would and would not bring
  *   crombolo import umbraco apply   write a crombolo site from an Umbraco backup
  *
@@ -42,6 +49,7 @@
  */
 import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
+import { hostname } from 'node:os'
 import { basename, join, relative, resolve } from 'node:path'
 import { AuthStore, resetAdminPassword } from '@crombolo/auth'
 import { ObjectTypes } from '@crombolo/core'
@@ -105,15 +113,20 @@ import {
   describeDatabase,
   dictionaryToUdt,
   domainsFilePath,
+  forgetSignIn,
   formTypesFor,
   importDictionaryUdt,
   isSafeAlias,
   listAssets,
   listComponents,
+  listeningBodyLimit,
   loadConfig,
   mediaStoreFor,
+  osKeychain,
   placeBlobs,
   readDomainsFile,
+  readRemoteMedia,
+  readSignIn,
   resolveDomainNode,
   resolvePlaceholders,
   type ServerHandle,
@@ -126,6 +139,7 @@ import {
   writeDictionaryUdt,
   writeDomains,
   writeDomainsFile,
+  writeRemoteMedia,
   writeUdtAll,
 } from '@crombolo/server'
 import {
@@ -148,6 +162,23 @@ import {
   writeResolutions,
 } from '@crombolo/transfer'
 import * as ops from '../src/operations/commands.ts'
+import {
+  discover,
+  type Job,
+  problemOf,
+  RemoteClient,
+  RemoteError,
+  signIn,
+  TimedOut,
+} from '../src/remote/client.ts'
+import { addRemote, pickRemote, readRemotes, removeRemote } from '../src/remote/remotes-file.ts'
+import {
+  fetchReferencedMedia,
+  pullFile,
+  pushSite,
+  RefusedBeforeSending,
+  referencedBlobs,
+} from '../src/remote/transfer.ts'
 import { findTemplate, listTemplates, scaffoldFiles } from '../src/templates.ts'
 
 const cwd = process.cwd()
@@ -213,7 +244,95 @@ function stopOnSignal(
   for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => stop(signal))
 }
 
+/**
+ * `start --from <file>` (story 105): an empty folder in, a working site out —
+ * scaffolded as `init` scaffolds one, its packages installed, and the file
+ * imported as a replace so nothing of the scaffold's own starting point stays.
+ * The new administrator's password is printed here, once.
+ */
+async function startFromFile(from: string, known?: string): Promise<void> {
+  const file = resolve(cwd, from)
+  if (!existsSync(file)) {
+    console.error(`${from} does not exist.`)
+    process.exit(1)
+  }
+  if (existsSync(join(cwd, 'crombolo.config.ts'))) {
+    console.error(
+      'There is a site here already. `crombolo import <file> --replace` replaces it; start --from starts a new one in an empty folder.',
+    )
+    process.exit(1)
+  }
+  const dir = await ops.unpackBundle(file, cwd)
+  const manifest = ops.readBundle(dir, cwd).set.manifest
+  if (manifest.scope !== 'site') {
+    console.error(`${from} is not a whole-site file: write one with \`crombolo export --site\`.`)
+    process.exit(1)
+  }
+  // A pull already holds the passphrase it sealed the file with.
+  const sealed = manifest.people !== undefined || manifest.content === 'sealed'
+  const passphrase = known
+    ? known
+    : sealed
+      ? (process.env[PASSPHRASE_ENV] ??
+        (process.stdin.isTTY ? await readSecret('  Passphrase for its people: ') : undefined))
+      : undefined
+  if (sealed && !passphrase) {
+    console.error(`${from} is sealed: set ${PASSPHRASE_ENV} to its passphrase.`)
+    process.exit(1)
+  }
+
+  for (const scaffolded of scaffoldFiles({
+    siteName: flagValue('--name') ?? manifest.provenance.siteName,
+    postgres: flags.has('--postgres'),
+  })) {
+    const target = join(cwd, scaffolded.path)
+    if (existsSync(target)) continue
+    await mkdir(join(target, '..'), { recursive: true })
+    if (scaffolded.copyFrom === undefined) await writeFile(target, scaffolded.text ?? '')
+    else await Bun.write(target, Bun.file(scaffolded.copyFrom))
+  }
+  console.log(`  scaffolded a site for ${manifest.provenance.siteName || 'the file'}`)
+  if (!flags.has('--no-install')) {
+    const install = Bun.spawnSync(['bun', 'install'], { cwd, stdout: 'inherit', stderr: 'inherit' })
+    if (install.exitCode !== 0) {
+      console.error('`bun install` failed; run it, then `crombolo import <file> --replace`.')
+      process.exit(1)
+    }
+  }
+
+  const config = await siteConfig()
+  const { db, seededAdminPassword } = await bootstrapDatabase(config)
+  await db.close()
+  const result = await ops.contentImport(config, {
+    bundle: dir,
+    passphrase,
+    replace: 'replace',
+    allowMissingBlobs: flags.has('--allow-missing-media'),
+    backupTaken: true,
+    label: `start --from ${basename(file)}`,
+  })
+  for (const problem of result.problems) console.error(`  ${problem}`)
+  if (!result.runId) {
+    printTransferFindings(result.check)
+    console.error('\nThe file could not be imported; the scaffolded site is left as it is.')
+    process.exit(1)
+  }
+  console.log(`  imported ${result.check.counts.create} item(s), run ${result.runId}`)
+  const placed = describePlaced(result.blobs)
+  if (placed) console.log(`  media    ${placed}`)
+  if (seededAdminPassword)
+    banner([
+      'Sign in with (shown once)',
+      `  username  ${config.adminLogin}`,
+      `  password  ${seededAdminPassword}`,
+    ])
+  // The password above is the one to use: this first start leaves it alone.
+  flags.add('--keep-admin')
+}
+
 async function start(): Promise<void> {
+  const from = flagValue('--from')
+  if (from) await startFromFile(from)
   const config = await siteConfig()
   // Before the migration and the seed, so a clash with the container stack is
   // reported in a second rather than after the database work.
@@ -317,7 +436,7 @@ async function bootWithRetries(config: CromboloConfig) {
   }
   const listening = Bun.serve({
     port: config.port,
-    maxRequestBodySize: config.maxRequestBodyBytes,
+    maxRequestBodySize: listeningBodyLimit(config),
     fetch: holding,
     websocket: { message() {} },
   })
@@ -1145,10 +1264,12 @@ async function contentRevert(config: CromboloConfig): Promise<void> {
     // The files an install replaced come back from the run's own copies, not
     // from git: these files are editable in the backoffice, so a site need not
     // be a checkout at all.
-    const files = ops.restoreSectionFiles(config, runId)
+    const files = await ops.revertSections(db, config, runId)
     for (const file of files.restored) console.log(`  restored ${relative(cwd, file)}`)
     for (const file of files.removed)
       console.log(`  removed  ${relative(cwd, file)}  (created by that run)`)
+    if (files.schema) console.log(`  schema   ${files.schema}`)
+    if (files.dictionary) console.log('  restored the dictionary')
 
     for (const key of result.restored) console.log(`  restored ${key}`)
     for (const key of result.recycled) console.log(`  recycled ${key}  (created by that run)`)
@@ -1269,27 +1390,10 @@ async function contentImport(config: CromboloConfig): Promise<void> {
 
   if (!result.runId) {
     printTransferFindings(result.check)
-    // Sections are applied before the content is checked, because content
-    // naming a type the bundle brings cannot pass a check until that type
-    // exists. So a refusal here may still have written files, and saying
-    // otherwise would send somebody looking in the wrong place.
-    if (result.sections) {
-      console.error(
-        `\nimport refused, but this bundle's structure was already applied: ` +
-          `${result.sections.written.length} file(s) written${
-            result.sections.schema ? `, schema ${result.sections.schema.action}` : ''
-          }.`,
-      )
-      for (const file of result.sections.written) console.error(`    ${relative(cwd, file)}`)
-      if (result.sections.replaced.length > 0)
-        console.error(
-          `  the originals are under ${relative(cwd, join(config.siteDir, ops.RUN_BACKUP_DIR))}`,
-        )
-    } else {
-      console.error(
-        `\nimport refused: ${result.check.outstanding.length} finding(s) outstanding. Nothing was written.`,
-      )
-    }
+    // Staged, then applied in one transaction: a refusal leaves nothing behind.
+    console.error(
+      `\nimport refused: ${result.check.outstanding.length || result.problems.length} finding(s) outstanding. Nothing was written.`,
+    )
     process.exit(1)
   }
 
@@ -1612,6 +1716,62 @@ async function contentExport(config: CromboloConfig): Promise<void> {
   if (counts.length === 0) process.exit(1)
 }
 
+/** `crombolo export --site`: the whole site as one file (story 104). */
+async function exportCommand(): Promise<void> {
+  if (!flags.has('--site')) {
+    console.error(
+      'export needs --site: the whole site, as one file. For a part of it, use content export.',
+    )
+    process.exit(1)
+  }
+  const config = await siteConfig()
+  const withPeople = flags.has('--with-members') || flags.has('--with-users')
+  const anonymise = flags.has('--anonymise')
+  const out = resolve(
+    flagValue('--out') ??
+      `${packageNameFor(`${config.siteName}-site`)}-${new Date().toISOString().slice(0, 10)}.tgz`,
+  )
+  const result = await ops.siteExport(config, {
+    out,
+    media: !flags.has('--no-media'),
+    drafts: flags.has('--drafts'),
+    withMembers: flags.has('--with-members'),
+    withUsers: flags.has('--with-users'),
+    anonymise,
+    passphrase:
+      withPeople && !(anonymise && !flags.has('--with-members'))
+        ? await passphraseToSeal()
+        : undefined,
+    package: { name: flagValue('--name'), version: flagValue('--package-version') },
+  })
+  const counts = Object.entries(result.counts)
+  console.log(`  wrote    ${relative(cwd, result.out) || result.out}`)
+  console.log(`  package  ${result.package.name}@${result.package.version} (private)`)
+  console.log(
+    `  content  ${counts.length > 0 ? counts.map(([kind, n]) => `${n} ${kind}`).join(', ') : 'none'}, unencrypted`,
+  )
+  const sections = Object.entries(result.sections)
+  if (sections.length > 0)
+    console.log(`  files    ${sections.map(([section, n]) => `${n} ${section}`).join(', ')}`)
+  if (result.media.omitted)
+    console.log(
+      '  media    left out (--no-media): importing it brings the media items without their files',
+    )
+  else
+    console.log(`  media    ${result.media.carried} file(s), ${describeBytes(result.media.bytes)}`)
+  for (const key of result.media.missing)
+    console.error(`  missing  ${key} is not in this environment's media store`)
+  if (result.people.members + result.people.users > 0)
+    console.log(
+      `  people   ${result.people.members} member(s), ${result.people.users} user(s), encrypted`,
+    )
+  else console.log('  people   left out: pass --with-members or --with-users to bring them')
+  if (result.anonymised !== undefined)
+    console.log(
+      `  anonymised  ${result.anonymised} email address(es) replaced; no back-office users`,
+    )
+}
+
 /**
  * `schema-as-code.md` leaves the dictionary in the database, because
  * translators work in production where `schema/` is read-only — so this is how
@@ -1804,6 +1964,117 @@ async function applyDomains(config: CromboloConfig): Promise<void> {
   }
 }
 
+/**
+ * `crombolo import <file>`: 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`.
+ */
+async function importFile(file: string): Promise<void> {
+  const config = await siteConfig()
+  const replace: ops.ReplaceMode | undefined = flags.has('--replace-all')
+    ? 'replace-all'
+    : flags.has('--replace')
+      ? 'replace'
+      : undefined
+  const dir = await ops.unpackBundle(file, config.siteDir)
+  let carriesPeople = false
+  try {
+    carriesPeople = ops.readBundle(dir, config.siteDir).set.manifest.people !== undefined
+  } catch (error) {
+    console.error(`  ${error instanceof Error ? error.message : String(error)}`)
+    process.exit(1)
+  }
+  const passphrase = carriesPeople
+    ? (process.env[PASSPHRASE_ENV] ??
+      (process.stdin.isTTY ? await readSecret('  Passphrase for its people: ') : undefined))
+    : await passphraseToOpen(dir, config)
+  const allowMissingBlobs = flags.has('--allow-missing-media')
+
+  const { check, summary } = await ops.siteReplaceCheck(config, {
+    bundle: dir,
+    passphrase,
+    replace: replace ?? 'replace',
+    allowMissingBlobs,
+  })
+  describeBundle(check.bundle)
+  const c = check.check.counts
+  console.log(`  brings   ${c.create} new, ${c.update} changed, ${c.unchanged} unchanged`)
+  const leaving = Object.entries(summary.leaving)
+  const fate = replace === 'replace-all' ? 'deleted' : 'recycled'
+  if (leaving.length > 0)
+    console.log(
+      `  ${fate.padEnd(8)} ${leaving.map(([kind, n]) => `${n} ${kind}`).join(', ')} not in the file`,
+    )
+  if (summary.filesRemoved.length > 0) {
+    console.log(
+      `  removes  ${summary.filesRemoved.length} file(s) not in the file, kept for a revert:`,
+    )
+    for (const path of summary.filesRemoved.slice(0, 20)) console.log(`    ${relative(cwd, path)}`)
+    if (summary.filesRemoved.length > 20)
+      console.log(`    … and ${summary.filesRemoved.length - 20} more`)
+  }
+  if (replace === 'replace-all' && summary.people.members + summary.people.users > 0)
+    console.log(
+      `  deletes  ${summary.people.members} member(s) and ${summary.people.users} user(s) not in the file`,
+    )
+  console.log("  keeps    domains, the secret key and this environment's settings")
+  for (const problem of check.problems) console.error(`  ${problem}`)
+
+  if (!replace) {
+    console.error(
+      '\nNothing was changed. Pass --replace to replace this site (what it loses is recycled, people kept), or --replace-all to make it exactly the file (deleted, people too).',
+    )
+    process.exit(1)
+  }
+  if (replace === 'replace-all' && !flags.has('--yes')) {
+    if (!process.stdin.isTTY) {
+      console.error(
+        '\n--replace-all deletes what the file does not have: pass --yes to confirm it.',
+      )
+      process.exit(1)
+    }
+    const answer = prompt(
+      `  This deletes for good. Type the site's name (${config.siteName}) to go on:`,
+    )
+    if (answer?.trim() !== config.siteName) {
+      console.error('  Nothing was changed.')
+      process.exit(1)
+    }
+  }
+
+  const result = await ops.contentImport(config, {
+    bundle: dir,
+    passphrase,
+    replace,
+    allowMissingBlobs,
+    label: `${replace} from ${basename(file)}`,
+    backupTaken: flags.has('--backup-taken'),
+  })
+  for (const problem of result.problems) console.error(`  ${problem}`)
+  if (result.backup.path) console.log(`  backup   ${result.backup.path}`)
+  if (!result.runId) {
+    printTransferFindings(result.check)
+    console.error('\nreplace refused. Nothing was changed.')
+    process.exit(1)
+  }
+  const counts = result.check.counts
+  console.log(`  run      ${result.runId}`)
+  console.log(
+    `  applied  ${counts.create} created, ${counts.update} updated, ${counts.unchanged} unchanged`,
+  )
+  const placed = describePlaced(result.blobs)
+  if (placed) console.log(`  media    ${placed}`)
+  if (result.sections?.schema) console.log(`  schema   ${result.sections.schema.action}`)
+  if (result.published > 0) console.log(`  published ${result.published} page(s)`)
+  for (const failure of result.publishFailures)
+    console.error(`  not published  ${failure.key}: ${failure.reason}`)
+  console.log(
+    replace === 'replace-all'
+      ? `\nDone. \`crombolo content revert ${result.runId}\` puts the files and the pages it changed back; what was deleted is in the backup.`
+      : `\nDone. \`crombolo content revert ${result.runId}\` puts it back.`,
+  )
+}
+
 /**
  * `crombolo import umbraco`: a compatibility report for an Umbraco backup, and
  * then a crombolo site written from it.
@@ -1825,7 +2096,13 @@ async function importSite(): Promise<void> {
     else if (!arg.startsWith('--')) args.push(arg)
   }
   const [kind, sub, backup] = args
+  if (kind && kind !== 'umbraco') return importFile(kind)
   if (kind !== 'umbraco' || (sub !== 'report' && sub !== 'apply')) return help()
+  // Not into --json output, which a machine reads.
+  if (!flags.has('--json'))
+    console.error(
+      '  deprecated  `crombolo import umbraco` is going away: an Umbraco extension will write a crombolo file that `crombolo import <file>` reads (story 074)',
+    )
   if (!backup) {
     console.error(`import umbraco ${sub} needs the backup: a .bacpac, or Umbraco's SQLite file.`)
     process.exit(1)
@@ -2272,6 +2549,10 @@ function help(): void {
   start [--keep-admin]        boot the site in the current directory
         [--bundle <pkg>]      apply a bundle's content first, once per bundle, then serve;
                               takes the \`content import\` flags (--publish, --under, …)
+        [--from <file>]       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
+                              [--postgres] [--name <site name>] [--no-install]
   init [--force] [--name <site name>] [--postgres] [--template <id>]
                               scaffold a site here; --template list prints the
                               starter templates, which bring schema, views and content
@@ -2298,6 +2579,12 @@ function help(): void {
   assets list                 the stylesheets and scripts this site has
   assets new <stylesheet|script> <name>
                               write an empty one in the place the backoffice edits
+  export --site [--out <file.tgz>]
+                              the whole site in one file: schema, components, styles,
+                              scripts, dictionary, every page and media item and their
+                              files. Domains and people stay behind
+                              [--no-media] [--drafts] [--with-members] [--with-users]
+                              [--anonymise] replaces every personal value as it writes
   content export --root <path|uuid> --out <dir>
                               write a private bundle package: the subtree, its
                               dependencies and what the destination must already have
@@ -2351,6 +2638,36 @@ function help(): void {
   domains clear <path|uuid|/> unbind that page, in the file and in the database
   domains apply               apply domains.toml here, as a boot does
   domains undo                put back the file the last write replaced, and apply it
+  remote add <name> <url> [--env <id>]
+                              a remote this site pulls from and pushes to, kept in
+                              remotes.toml (URLs only; sign-ins are in your keychain)
+  remote list | remove <name>
+  login [<remote>]            sign in with a code you approve in the remote's back office
+  logout [<remote>] | whoami [<remote>]
+  pull [<remote>] [--env <id>] [--full] [--yes]
+                              a copy of the environment, sealed and anonymised unless
+                              --full: started here in an empty folder, or replacing this
+                              site (what it loses is recycled; --yes skips the question)
+                              [--no-media] [--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
+  push [<remote>] [--env <id>] [--force] [--auto-approve] [--media-info-only]
+                              replace the environment with this site; shows what it would
+                              replace first. A protected one needs --force and its name
+                              typed back (--auto-approve skips that); the remote may also
+                              hold it for someone else's approval
+                              exit 0 done, 1 refused or failed, 2 refused before sending,
+                              3 gave up waiting
+  media fetch                 a lazily pulled site's media files, all of them now
+  import <file> [--replace | --replace-all]
+                              replace this site with a whole-site file. Says first what
+                              would be replaced, and 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>\`
+                              [--allow-missing-media] [--backup-taken]
   import umbraco report <backup> [--site <dir>] [--media <dir>] [--out <dir>] [--json]
                               read-only: what importing an Umbraco backup would bring,
                               and what it would not — packages, Razor, custom code.
@@ -2441,6 +2758,331 @@ function commandAudit(): ops.CommandAudit | undefined {
   }
 }
 
+// ---------------------------------------------------------------- remotes (story 108)
+
+const keychain = () => osKeychain()
+
+/** Exit codes a pull or push states: 1 the remote refused or failed, 2 refused before sending, 3 gave up waiting. */
+function remoteExit(error: unknown): never {
+  if (error instanceof RefusedBeforeSending) {
+    console.error(`  ${error.message}`)
+    process.exit(2)
+  }
+  if (error instanceof TimedOut) {
+    console.error(`  ${error.message} The job carries on at the remote.`)
+    process.exit(3)
+  }
+  if (error instanceof RemoteError) {
+    console.error(`  ${error.message}`)
+    for (const item of error.problem.items ?? []) console.error(`    ${item}`)
+    process.exit(error.problem.code === 'sign-in-required' ? 2 : 1)
+  }
+  console.error(`  ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(1)
+}
+
+function openInBrowser(url: string): void {
+  if (flags.has('--no-browser')) return
+  const opener =
+    process.platform === 'darwin'
+      ? ['open']
+      : process.platform === 'win32'
+        ? ['cmd', '/c', 'start', '']
+        : ['xdg-open']
+  try {
+    Bun.spawn([...opener, url], { stdout: 'ignore', stderr: 'ignore' })
+  } catch {
+    // Printed above; opening it is a convenience.
+  }
+}
+
+/** The remote a command names, signed in or not, with the environment it goes to. */
+async function connectRemote(name: string | undefined) {
+  const entry = pickRemote(cwd, name)
+  if (!entry) {
+    const known = readRemotes(cwd)
+    console.error(
+      known.length === 0
+        ? '  No remotes yet: `crombolo remote add <name> <url>`.'
+        : `  Which remote? ${known.map((r) => r.name).join(', ')}`,
+    )
+    process.exit(2)
+  }
+  const discovery = await discover(entry.url).catch(remoteExit)
+  const client = new RemoteClient(discovery, keychain())
+  const environment =
+    flagValue('--env') ??
+    entry.environment ??
+    (discovery.environments.length === 1 ? discovery.environments[0]?.id : undefined)
+  return { entry, discovery, client, environment }
+}
+
+async function remoteCommand(): Promise<void> {
+  const [sub, name, url] = positional
+  if (sub === 'add') {
+    if (!name || !url) {
+      console.error("remote add needs a name and the site's URL.")
+      process.exit(2)
+    }
+    const discovery = await discover(url).catch(remoteExit)
+    addRemote(cwd, { name, url: new URL(url).origin, environment: flagValue('--env') })
+    console.log(`  added    ${name}  ${discovery.name} (${new URL(url).origin})`)
+    for (const env of discovery.environments)
+      console.log(`  env      ${env.id}${env.protected ? '  protected' : ''}`)
+    console.log(`\n\`crombolo login ${name}\` signs in.`)
+    return
+  }
+  if (sub === 'remove') {
+    if (!name || !removeRemote(cwd, name)) {
+      console.error(`  There is no remote "${name ?? ''}".`)
+      process.exit(2)
+    }
+    console.log(`  removed  ${name}`)
+    return
+  }
+  const remotes = readRemotes(cwd)
+  if (remotes.length === 0) console.log('  No remotes yet: `crombolo remote add <name> <url>`.')
+  for (const remote of remotes) {
+    const signed = (await readSignIn(keychain(), remote.url).catch(() => undefined)) !== undefined
+    console.log(
+      `  ${remote.name.padEnd(12)} ${remote.url}${remote.environment ? `  env ${remote.environment}` : ''}${signed ? '' : '  (not signed in)'}`,
+    )
+  }
+}
+
+async function loginCommand(): Promise<void> {
+  const { entry, discovery } = await connectRemote(positional[0])
+  await signIn(discovery, keychain(), {
+    clientName: `crombolo on ${hostname()}`,
+    onCode: (code, url) => {
+      console.log(`  Approve this sign-in at ${url}`)
+      console.log(`  and check it shows   ${code}`)
+      openInBrowser(url)
+    },
+  }).catch(remoteExit)
+  console.log(`  signed in to ${entry.name}`)
+}
+
+async function logoutCommand(): Promise<void> {
+  const { entry, discovery } = await connectRemote(positional[0])
+  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)
+  console.log(`  signed out of ${entry.name}`)
+}
+
+async function whoamiCommand(): Promise<void> {
+  const { entry, client, discovery } = await connectRemote(positional[0])
+  const response = await client
+    .call(`${new URL(discovery.api).origin}/umbraco/management/api/v1/user/current`)
+    .catch(remoteExit)
+  if (!response.ok) remoteExit(await problemOf(response))
+  const me = (await response.json()) as { name: string; email: string }
+  console.log(`  ${me.name} <${me.email}> on ${entry.name}`)
+  for (const env of await client.environments().catch(remoteExit)) {
+    const may = [env.may.pull && 'pull', env.may.pullFull && 'full pull', env.may.push && 'push']
+      .filter(Boolean)
+      .join(', ')
+    console.log(`  ${env.id.padEnd(12)} ${may || 'nothing'}${env.protected ? '  (protected)' : ''}`)
+  }
+}
+
+const describeJob = (job: Job) =>
+  `  ${job.kind.padEnd(5)} ${job.state}${job.stage ? `, ${job.stage}` : ''}${job.progress != null ? ` (${job.progress}%)` : ''}`
+
+async function pullCommand(): Promise<void> {
+  const { client, environment, discovery } = await connectRemote(positional[0])
+  if (!environment) {
+    console.error(
+      `  Which environment? ${discovery.environments.map((e) => e.id).join(', ')} (--env)`,
+    )
+    process.exit(2)
+  }
+  const media = flags.has('--no-media')
+    ? ('omitted' as const)
+    : flags.has('--media-info-only') || flags.has('--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.has('--full'),
+    media,
+    onProgress: (job) => console.log(describeJob(job)),
+  }).catch(remoteExit)
+  console.log(
+    `  pulled   ${describeBytes(pulled.size)}${flags.has('--full') ? '' : ', anonymised'}`,
+  )
+  if (media !== 'included') flags.add('--allow-missing-media')
+
+  const existing = existsSync(join(cwd, 'crombolo.config.ts'))
+  if (!existing) {
+    await startFromFile(out, pulled.passphrase)
+  } else {
+    const config = await siteConfig()
+    const { summary } = await ops.siteReplaceCheck(config, {
+      bundle: out,
+      passphrase: pulled.passphrase,
+      replace: 'replace',
+      allowMissingBlobs: media !== 'included',
+    })
+    const leaving = Object.entries(summary.leaving)
+    if (leaving.length > 0)
+      console.log(
+        `  recycled ${leaving.map(([kind, n]) => `${n} ${kind}`).join(', ')} here, not in ${environment}`,
+      )
+    if (summary.filesRemoved.length > 0)
+      console.log(`  removes  ${summary.filesRemoved.length} file(s) here, kept for a revert`)
+    if (!flags.has('--yes')) {
+      if (!process.stdin.isTTY) {
+        console.error(`\nThis replaces this site with ${environment}: pass --yes to go on.`)
+        process.exit(2)
+      }
+      const answer = prompt(`  Replace this site with ${environment}? [y/N]`)
+      if (!/^y(es)?$/i.test(answer?.trim() ?? '')) {
+        console.error('  Nothing was changed.')
+        process.exit(2)
+      }
+    }
+    const result = await ops.contentImport(config, {
+      bundle: out,
+      passphrase: pulled.passphrase,
+      replace: 'replace',
+      allowMissingBlobs: media !== 'included',
+      label: `pull from ${environment}`,
+      backupTaken: flags.has('--backup-taken'),
+    })
+    for (const problem of result.problems) console.error(`  ${problem}`)
+    if (!result.runId) {
+      printTransferFindings(result.check)
+      console.error('\npull refused. Nothing was changed.')
+      process.exit(1)
+    }
+    console.log(
+      `  replaced, run ${result.runId}: \`crombolo content revert ${result.runId}\` puts it back`,
+    )
+  }
+
+  if (media === 'referenced') {
+    const config = await siteConfig()
+    const blobs = await referencedBlobs(out)
+    if (flags.has('--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`,
+      )
+      console.log(
+        `  media    ${blobs.length} file(s) fetched from ${environment} as they are first asked for`,
+      )
+    } else {
+      const fetched = await fetchReferencedMedia(client, {
+        environment,
+        blobs,
+        store: await mediaStoreFor(config),
+        siteDir: cwd,
+      }).catch(remoteExit)
+      console.log(
+        `  media    ${fetched.fetched} fetched (${describeBytes(fetched.bytes)}), ${fetched.skipped} already here`,
+      )
+      for (const key of fetched.failed)
+        console.error(`  missing  ${key}: run the pull again to fetch it`)
+    }
+  }
+  if (!existing) await start()
+}
+
+async function pushCommand(): Promise<void> {
+  const { client, environment, discovery } = await connectRemote(positional[0])
+  if (!environment) {
+    console.error(
+      `  Which environment? ${discovery.environments.map((e) => e.id).join(', ')} (--env)`,
+    )
+    process.exit(2)
+  }
+  const config = await siteConfig()
+  const result = await pushSite(config, client, {
+    environment,
+    force: flags.has('--force'),
+    autoApprove: flags.has('--auto-approve'),
+    mediaInfoOnly: flags.has('--media-info-only'),
+    onCheck: (check) => {
+      const counts = Object.entries(check.sending.counts)
+      console.log(
+        `  sending  ${counts.map(([kind, n]) => `${n} ${kind}`).join(', ') || 'no content'}, ${check.sending.files} file(s)`,
+      )
+      if (check.fromRemote) {
+        const recycles = Object.entries(check.recycles)
+        if (recycles.length > 0)
+          console.log(
+            `  recycles ${recycles.map(([kind, n]) => `${n} ${kind}`).join(', ')} on ${environment}`,
+          )
+        if (check.removesFiles.length > 0)
+          console.log(`  removes  ${check.removesFiles.join(', ')} on ${environment}`)
+      }
+    },
+    confirm: async () => {
+      if (!process.stdin.isTTY) return false
+      const answer = prompt(`  This replaces ${environment}. Type its name to go on:`)
+      return answer?.trim() === environment
+    },
+    onProgress: (job) => console.log(describeJob(job)),
+    onApproval: (job) => {
+      console.log(`  waiting  for someone else to approve it: ${job.approvalUrl}`)
+      if (job.approvalUrl) openInBrowser(job.approvalUrl)
+    },
+  }).catch(remoteExit)
+  const { job } = result
+  if (job.state === 'done') {
+    console.log(`\n  pushed   ${environment} replaced, run ${job.runId ?? '—'}`)
+    return
+  }
+  console.error(`\n  ${job.problem?.title ?? `the push ended ${job.state}`}`)
+  for (const item of job.problem?.items ?? []) console.error(`    ${item}`)
+  process.exit(1)
+}
+
+async function mediaCommand(): Promise<void> {
+  if (positional[0] !== 'fetch') return help()
+  const source = readRemoteMedia(cwd)
+  const listed = join(cwd, '.crombolo', 'remote-media-blobs.json')
+  if (!source || !existsSync(listed)) {
+    console.error('  This site was not pulled with --lazy-media: there is nothing to fetch.')
+    process.exit(2)
+  }
+  const discovery = await discover(source.api).catch(remoteExit)
+  const client = new RemoteClient(discovery, keychain())
+  const config = await siteConfig()
+  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(config),
+    siteDir: cwd,
+    onProgress: (done, total) => {
+      if (done % 50 === 0 || done === total) console.log(`  ${done}/${total}`)
+    },
+  }).catch(remoteExit)
+  console.log(
+    `  media    ${fetched.fetched} fetched (${describeBytes(fetched.bytes)}), ${fetched.skipped} already here`,
+  )
+  for (const key of fetched.failed) console.error(`  missing  ${key}`)
+  if (fetched.failed.length > 0) process.exit(1)
+}
+
 async function dispatch(): Promise<void> {
   switch (command) {
     case 'start':
@@ -2490,6 +3132,30 @@ async function dispatch(): Promise<void> {
     case 'assets':
       await assets()
       break
+    case 'export':
+      await exportCommand()
+      break
+    case 'remote':
+      await remoteCommand()
+      break
+    case 'login':
+      await loginCommand()
+      break
+    case 'logout':
+      await logoutCommand()
+      break
+    case 'whoami':
+      await whoamiCommand()
+      break
+    case 'pull':
+      await pullCommand()
+      break
+    case 'push':
+      await pushCommand()
+      break
+    case 'media':
+      await mediaCommand()
+      break
     case 'import':
       await importSite()
       break