@crombolo/cli 0.14.4 → 0.15.0

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 : []

package/src/support/describe.ts

@@ -0,0 +1,179 @@
+/** How the CLI says what happened: the lines shared between commands. */
+import { relative } from 'node:path'
+import type { Finding } from '@crombolo/data'
+import type { SyncReport } from '@crombolo/schema'
+import { propertyHandle, resolutionsFor, type TransferCheck } from '@crombolo/transfer'
+import type * as ops from '../operations/commands.ts'
+import type { Job } from '../remote/client.ts'
+import { cwd, type Io } from './site.ts'
+
+export function banner(io: Io, lines: string[]): void {
+  const width = Math.max(...lines.map((line) => line.length))
+  io.say(`┌─${'─'.repeat(width)}─┐`)
+  for (const line of lines) io.say(`│ ${line.padEnd(width)} │`)
+  io.say(`└─${'─'.repeat(width)}─┘`)
+}
+
+export const here = (path: string): string => relative(cwd(), path) || '.'
+
+/** Bytes as somebody reads them, since a bundle of media is measured in them. */
+export function describeBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  const units = ['KB', 'MB', 'GB']
+  let value = bytes / 1024
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`
+}
+
+export const counted = (counts: Record<string, number>, none = 'nothing'): string => {
+  const entries = Object.entries(counts)
+  return entries.length > 0 ? entries.map(([kind, n]) => `${n} ${kind}`).join(', ') : none
+}
+
+/**
+ * Puts the media files a bundle carries into this environment's store.
+ *
+ * After the content, because the run is what decides whether any of this
+ * happened: a refused import leaves the store alone.
+ */
+export function describePlaced(
+  placed: { placed: number; bytes: number } | null,
+): string | undefined {
+  if (!placed) return undefined
+  return `${placed.placed} media file(s) placed, ${describeBytes(placed.bytes)}`
+}
+
+export function describeSync(report: SyncReport): string {
+  switch (report.action) {
+    case 'applied':
+    case 'would-apply': {
+      const verb = report.action === 'applied' ? 'applied' : 'would apply'
+      const c = report.created
+      const parts = [
+        `${c.types} type(s)`,
+        `${c.properties} propert${c.properties === 1 ? 'y' : 'ies'}`,
+        `${c.dataTypes} data type(s)`,
+        `${c.languages} language(s)`,
+      ]
+      const extra = [
+        report.retired.length > 0 ? `retired ${report.retired.join(', ')}` : '',
+        report.retiredTypes.length > 0 ? `retired types ${report.retiredTypes.join(', ')}` : '',
+        report.revived.length > 0 ? `revived ${report.revived.join(', ')}` : '',
+        report.assignedKeys.length > 0 ? `${report.assignedKeys.length} key(s) assigned` : '',
+      ].filter(Boolean)
+      return `${verb} ${report.state?.version ?? ''}: created ${parts.join(', ')}${extra.length > 0 ? `; ${extra.join('; ')}` : ''}`
+    }
+    case 'skipped-same':
+      return 'up to date'
+    case 'skipped-older':
+      return `compatibility mode: ${report.reason ?? ''}`
+    case 'refused':
+      return `refused: ${report.reason ?? `${report.problems.length} problem(s)`}`
+  }
+}
+
+export const describeProblem = (p: SyncReport['problems'][number]): string =>
+  `${p.file}${p.path ? ` (${p.path})` : ''}: ${p.message}`
+
+export function printProblems(io: Io, problems: SyncReport['problems']): void {
+  for (const p of problems) io.warning(`  ${describeProblem(p)}`)
+}
+
+export function describeBundle(io: Io, bundle: ops.BundleSummary): void {
+  io.say(
+    `  bundle   ${bundle.id} from ${bundle.from || 'elsewhere'} ` +
+      `(schema ${bundle.schemaVersion}+${bundle.schemaRevision}, ` +
+      `${bundle.snapshot} snapshot, ${bundle.nodes} node(s))`,
+  )
+  if (bundle.blobsCarried > 0)
+    io.say(
+      `  blobs    ${bundle.blobsCarried} media file(s) carried, ${describeBytes(bundle.blobBytes)}`,
+    )
+}
+
+/** What the carried sections would do, or did. */
+export function printSections(io: Io, plan: ops.SectionPlan | undefined): void {
+  if (!plan) return
+  io.say(`  carries  ${plan.sections.join(', ')}`)
+  const counts = new Map<string, number>()
+  for (const file of plan.files) counts.set(file.action, (counts.get(file.action) ?? 0) + 1)
+  const summary = [...counts].map(([action, n]) => `${n} ${action}`).join(', ')
+  if (summary) io.say(`  files    ${summary}`)
+  for (const file of plan.files)
+    if (file.action === 'overwrite') io.say(`    overwrites ${here(file.target)}`)
+  if (plan.dictionaryItems > 0) io.say(`  dict     ${plan.dictionaryItems} file(s)`)
+  if (plan.schema) {
+    io.say(`  schema   ${plan.schema.classification}`)
+    for (const finding of plan.schema.findings) io.say(`    ${finding}`)
+  }
+}
+
+export function printTransferFindings(io: Io, check: TransferCheck): void {
+  const byKind = { blocking: 0, person: 0, auto: 0 }
+  for (const f of check.findings) byKind[f.kind] += 1
+  const c = check.counts
+  io.say(
+    `  plan     ${c.create} new, ${c.update} updated, ${c.unchanged} unchanged, ${c.skip} skipped`,
+  )
+  io.say(
+    `  findings ${byKind.blocking} blocking, ${byKind.person} need a person, ${byKind.auto} automatic`,
+  )
+  for (const f of check.findings) {
+    io.say(`  [${f.kind.padEnd(8)}] ${f.message}`)
+    // The handle is the CLI's to name; the dashboard offers the same answers as choices.
+    if (f.code === 'local-edit' && f.propertyAlias)
+      io.say(
+        `             answer it as ${f.subjectKey}/${propertyHandle(f.propertyAlias, f.culture)}`,
+      )
+    for (const suggestion of resolutionsFor(f.code)) io.say(`             → ${suggestion}`)
+    if (f.link) io.say(`             ${f.link}`)
+  }
+}
+
+/** The findings a check reports, as data: what the envelope's `details` carry. */
+export const findingsOf = (
+  findings: readonly { kind: string; message: string; code?: string; link?: string | null }[],
+) =>
+  findings.map((f) => ({
+    kind: f.kind,
+    ...(f.code ? { code: f.code } : {}),
+    message: f.message,
+    ...(f.link ? { link: f.link } : {}),
+  }))
+
+export function printFindings(
+  io: Io,
+  report: { classification: string; findings: Finding[] },
+): void {
+  const byKind = { blocking: 0, person: 0, auto: 0 }
+  for (const f of report.findings) byKind[f.kind] += 1
+  io.say(
+    `change: ${report.classification}; findings: ${byKind.blocking} blocking, ${byKind.person} need a person, ${byKind.auto} automatic`,
+  )
+  for (const f of report.findings) {
+    const where = f.link ? `  ${f.link}` : ''
+    io.say(`  [${f.kind.padEnd(8)}] ${f.message}${where}`)
+  }
+}
+
+export const describeJob = (job: Job): string =>
+  `  ${job.kind.padEnd(5)} ${job.state}${job.stage ? `, ${job.stage}` : ''}${job.progress != null ? ` (${job.progress}%)` : ''}`
+
+export function describeContentMode(
+  io: Io,
+  content: 'omitted' | 'sealed' | 'open',
+  people?: { members: number; users: number },
+): void {
+  if (content === 'omitted')
+    io.say(
+      '  content  not included: pages are placed and named, and no value is written. Pass --include-content to bring the values and media files',
+    )
+  else if (content === 'sealed') io.say('  content  encrypted: importing needs the passphrase')
+  else io.say('  content  unencrypted')
+  if (people && people.members + people.users > 0)
+    io.say(`  people   ${people.members} member(s), ${people.users} user(s), encrypted`)
+}

package/src/support/domains.ts

@@ -0,0 +1,89 @@
+/**
+ * Which hostnames reach which page. `domains.toml` is the truth and the
+ * database follows it, so `set` and `clear` write the file and then apply it —
+ * one command, rather than an edit here and a deploy to make it real.
+ */
+import {
+  bootstrapDatabase,
+  type CromboloConfig,
+  type DomainDeclaration,
+  domainsFilePath,
+  readDomainsFile,
+  resolveDomainNode,
+  syncDomainsFile,
+  withoutNode,
+  writeDomains,
+} from '@crombolo/server'
+import { CliError } from '../errors.ts'
+import { here } from './describe.ts'
+import type { Io } from './site.ts'
+
+/** The file's declarations, saying what is wrong with it as it goes. */
+export function readDeclarations(io: Io, config: CromboloConfig) {
+  const read = readDomainsFile(config.siteDir)
+  for (const problem of read?.problems ?? [])
+    io.warning(`  ${domainsFilePath(config.siteDir)}: ${problem}`)
+  return { read, declarations: read?.declarations ?? [] }
+}
+
+/** Applies the file as a boot would, and reports what it did. */
+export async function applyDomains(io: Io, config: CromboloConfig) {
+  const { db } = await bootstrapDatabase(config)
+  try {
+    const report = await syncDomainsFile(db, config.siteDir)
+    for (const applied of report.applied)
+      io.say(
+        `  applied  ${applied.node.padEnd(24)} ${applied.host}${applied.culture ? `  ${applied.culture}` : ''}`,
+      )
+    if (report.removed > 0) io.say(`  removed  ${report.removed} binding(s)`)
+    if (report.problems.length > 0)
+      throw new CliError('refused', `${report.problems.length} domain(s) could not be applied.`, {
+        details: report.problems,
+      })
+    return {
+      applied: report.applied.map((a) => ({
+        node: a.node,
+        host: a.host,
+        culture: a.culture ?? null,
+      })),
+      removed: report.removed,
+    }
+  } finally {
+    await db.close()
+  }
+}
+
+/**
+ * Stating a node's hostnames says what they are, as the backoffice's dialog
+ * does: whatever that page had is replaced, so running this twice is the same
+ * as running it once. Which entries belong to that page is decided by
+ * resolving them, not by matching the text — `/` and `/Home` can be the same
+ * page, and clearing one while the other stayed would do nothing at all.
+ */
+export async function rewriteDomains(
+  io: Io,
+  config: CromboloConfig,
+  ref: string,
+  add: DomainDeclaration[],
+) {
+  const { declarations } = readDeclarations(io, config)
+  const { db } = await bootstrapDatabase(config)
+  let kept: DomainDeclaration[] = []
+  try {
+    const target = await resolveDomainNode(db, ref)
+    if (!target.ok) throw new CliError('not_found', target.message)
+    kept = await withoutNode(db, declarations, target.node)
+  } finally {
+    await db.close()
+  }
+  const written = await writeDomains(config.siteDir, [...kept, ...add])
+  io.say(
+    `  wrote    ${here(written.file)}${written.backup ? '  (previous kept; `crombolo domains undo` puts it back)' : ''}`,
+  )
+  return { wrote: here(written.file), ...(await applyDomains(io, config)) }
+}
+
+export const appliedFields = [
+  { name: 'applied', type: 'array', items: { type: 'object' } },
+  { name: 'removed', type: 'integer' },
+] as const

package/src/support/flags.ts

@@ -0,0 +1,157 @@
+/** Flags more than one command takes, and what they come to. */
+
+import {
+  isResolution,
+  type NodeResolutions,
+  parseResolveFlags,
+  RESOLUTIONS,
+  type Resolution,
+} from '@crombolo/transfer'
+import { Flags } from '@oclif/core'
+import { CliError } from '../errors.ts'
+import type * as ops from '../operations/commands.ts'
+import type { Io } from './site.ts'
+
+export const backupTaken = Flags.boolean({
+  summary: 'a backup was taken another way: Postgres needs this, or CROMBOLO_PG_DUMP',
+})
+
+export const dryRun = Flags.boolean({ summary: 'say what it would do, and change nothing' })
+
+/** A repeatable value flag that takes one value each time, so it never swallows an argument. */
+export const many = (summary: string, helpValue?: string) =>
+  Flags.string({ summary, helpValue, multiple: true, multipleNonGreedy: true, default: [] })
+
+/** The flags `content check` and `content import` share: resolutions, placement, files. */
+export const transferFlags = {
+  under: Flags.string({ summary: 'place the bundle under this page', helpValue: '<path|uuid>' }),
+  resolve: many(
+    'answer a finding: <key>=take-bundle|keep-local|skip, or <key>/<property>[@<culture>]=take-bundle|keep-local',
+    '<answer>',
+  ),
+  'resolve-all': Flags.string({
+    summary: 'answer every finding the same way',
+    options: [...RESOLUTIONS],
+  }),
+  'allow-missing-blobs': Flags.boolean({
+    summary: 'import media items whose files the bundle does not carry',
+  }),
+  publish: Flags.boolean({ summary: 'publish what it imports' }),
+  'no-schema': Flags.boolean({ summary: 'decline the schema the bundle carries' }),
+  'no-files': Flags.boolean({ summary: 'decline the views, styles and scripts it carries' }),
+  'replace-files': Flags.boolean({
+    summary: 'allow replacing files this site has; the originals are kept for a revert',
+  }),
+}
+
+export interface TransferFlagValues {
+  under?: string
+  resolve: string[]
+  'resolve-all'?: string
+  'allow-missing-blobs': boolean
+  publish: boolean
+  'no-schema': boolean
+  'no-files': boolean
+  'replace-files': boolean
+}
+
+export function parseResolutions(values: readonly string[]): Record<string, NodeResolutions> {
+  const parsed = parseResolveFlags([...values])
+  if (parsed.problems.length > 0)
+    throw new CliError('usage', 'A --resolve answer could not be read.', {
+      details: parsed.problems,
+    })
+  return parsed.byNode
+}
+
+export function transferInput(bundle: string, flags: TransferFlagValues): ops.TransferInput {
+  const all = flags['resolve-all']
+  if (all !== undefined && !isResolution(all))
+    throw new CliError('usage', `"${all}" is not one of ${RESOLUTIONS.join(', ')}.`)
+  return {
+    bundle,
+    under: flags.under,
+    resolutions: parseResolutions(flags.resolve),
+    resolveAll: all as Resolution | undefined,
+    allowMissingBlobs: flags['allow-missing-blobs'],
+    publish: flags.publish,
+    // What a bundle carries is applied by default — that is the point of it
+    // carrying anything — so these decline a half, for someone who wants the
+    // content without the structure that came with it.
+    withoutSchema: flags['no-schema'],
+    withoutFiles: flags['no-files'],
+    replaceFiles: flags['replace-files'],
+  }
+}
+
+/** Property values and media files in an export: left out, sealed, or — asked twice — open. */
+export const contentFlags = {
+  'include-content': Flags.boolean({
+    summary: 'bring property values and media files, encrypted under a passphrase',
+  }),
+  'allow-content-unencrypted': Flags.boolean({
+    summary: 'with --include-content: write them readable',
+  }),
+}
+
+export function contentMode(
+  io: Io,
+  flags: {
+    'include-content': boolean
+    'allow-content-unencrypted': boolean
+    'with-blobs'?: boolean
+  },
+): 'omitted' | 'sealed' | 'open' {
+  const include = flags['include-content']
+  const open = flags['allow-content-unencrypted']
+  if (open && !include)
+    throw new CliError('usage', '--allow-content-unencrypted goes with --include-content.')
+  if (flags['with-blobs'] && !include)
+    throw new CliError(
+      'usage',
+      'Media files are content: --with-blobs goes with --include-content.',
+    )
+  if (open)
+    io.warning(
+      '  warning  property values and media files are written unencrypted: anyone with the files can read any personal information in them',
+    )
+  return !include ? 'omitted' : open ? 'open' : 'sealed'
+}
+
+/** Offset pagination for a list: `--limit` and `--offset`, and what was left out. */
+export const pageFlags = (limit: number) => ({
+  limit: Flags.integer({ summary: 'how many to list', default: limit, min: 1 }),
+  offset: Flags.integer({ summary: 'how many to skip first', default: 0, min: 0 }),
+  fields: Flags.string({
+    summary: 'only these fields of each item, comma-separated',
+    helpValue: '<a,b>',
+  }),
+})
+
+export const pagination = { style: 'offset', offsetArg: '--offset', limitArg: '--limit' } as const
+
+/** One page of a list, in the envelope clispec asks for, narrowed to `--fields` when given. */
+export function page<T extends object>(
+  items: readonly T[],
+  total: number,
+  flags: { offset: number; fields?: string },
+): { items: Partial<T>[]; total: number; offset: number; truncated: boolean } {
+  const wanted = flags.fields
+    ?.split(',')
+    .map((field) => field.trim())
+    .filter(Boolean)
+  const narrowed = wanted
+    ? items.map(
+        (item) =>
+          Object.fromEntries(
+            Object.entries(item).filter(([key]) => wanted.includes(key)),
+          ) as Partial<T>,
+      )
+    : [...items]
+  return {
+    items: narrowed,
+    total,
+    offset: flags.offset,
+    truncated: flags.offset + items.length < total,
+  }
+}

package/src/support/prompt.ts

@@ -0,0 +1,126 @@
+/**
+ * Asking a person: a confirmation, a typed name, a passphrase. Every question
+ * goes to stderr, so stdout stays the result; with no terminal to ask on, a
+ * confirmation refuses at once, naming the flag that answers it, and never
+ * reads stdin.
+ */
+import type { CromboloConfig } from '@crombolo/server'
+import { CliError } from '../errors.ts'
+import * as ops from '../operations/commands.ts'
+
+/** Where a script gives a bundle's passphrase, rather than typing it. */
+export const PASSPHRASE_ENV = 'CROMBOLO_BUNDLE_PASSPHRASE'
+export const MIN_PASSPHRASE = 12
+
+export const interactive = (): boolean => process.stdin.isTTY === true
+
+async function readLine(question: string): Promise<string> {
+  process.stderr.write(`${question} `)
+  for await (const line of console) return line
+  return ''
+}
+
+/**
+ * Asks before something that cannot be taken back. `answer` is what must be
+ * typed (a name, or `y`); off a terminal it throws `confirmation_required`, and
+ * a person who answers anything else gets `refused`.
+ */
+export async function confirm(
+  question: string,
+  options: { bypass: string; answer?: string; declined?: string },
+): Promise<void> {
+  if (!interactive())
+    throw new CliError('confirmation_required', question.replace(/[?:]\s*$/, '.'), {
+      hint: `Pass ${options.bypass} to go on without being asked.`,
+    })
+  const typed = (await readLine(question)).trim()
+  const yes = options.answer === undefined ? /^y(es)?$/i.test(typed) : typed === options.answer
+  if (!yes) throw new CliError('refused', options.declined ?? 'Nothing was changed.')
+}
+
+/** A line typed without echo. */
+export async function readSecret(question: string): Promise<string> {
+  process.stderr.write(question)
+  const stdin = process.stdin
+  stdin.setRawMode(true)
+  stdin.resume()
+  return new Promise((done) => {
+    let typed = ''
+    const onData = (chunk: Buffer) => {
+      for (const char of chunk.toString('utf8')) {
+        if (char === '\u0003') {
+          process.stderr.write('\n')
+          process.exit(130)
+        }
+        if (char === '\r' || char === '\n') {
+          stdin.setRawMode(false)
+          stdin.pause()
+          stdin.off('data', onData)
+          process.stderr.write('\n')
+          done(typed)
+          return
+        }
+        if (char === '\u007f' || char === '\b') typed = typed.slice(0, -1)
+        else typed += char
+      }
+    }
+    stdin.on('data', onData)
+  })
+}
+
+/** Everything piped to stdin, without its trailing newline. */
+export async function readStdin(): Promise<string> {
+  return (await Bun.stdin.text()).replace(/\r?\n$/, '')
+}
+
+const needPassphrase = (what: string) =>
+  new CliError('auth', `${what} needs a passphrase.`, {
+    hint: `Set ${PASSPHRASE_ENV}, or run it in a terminal to be asked.`,
+  })
+
+/** The passphrase to open a bundle with, when it is sealed: the environment's, or asked for. */
+export async function passphraseToOpen(
+  target: string,
+  config: CromboloConfig,
+): Promise<string | undefined> {
+  const given = process.env[PASSPHRASE_ENV]
+  if (given) return given
+  let sealed = false
+  try {
+    sealed = ops.readBundle(target, config.siteDir).set.sealed === true
+  } catch {
+    // The command that follows reads it again and says what is wrong with it.
+    return undefined
+  }
+  if (!sealed) return undefined
+  if (!interactive()) throw needPassphrase(`${target} is encrypted: opening it`)
+  return readSecret('  Passphrase for this bundle: ')
+}
+
+/** The passphrase for the people a file carries: the environment's, asked for, or none. */
+export async function passphraseForPeople(): Promise<string | undefined> {
+  return (
+    process.env[PASSPHRASE_ENV] ??
+    (interactive() ? await readSecret('  Passphrase for its people: ') : undefined)
+  )
+}
+
+/** A new passphrase to seal an export with: the environment's, or asked for twice. */
+export async function passphraseToSeal(): Promise<string> {
+  const given = process.env[PASSPHRASE_ENV]
+  if (given) {
+    if (given.length < MIN_PASSPHRASE)
+      throw new CliError('usage', `${PASSPHRASE_ENV} is shorter than ${MIN_PASSPHRASE} characters.`)
+    return given
+  }
+  if (!interactive()) throw needPassphrase('An encrypted export')
+  for (;;) {
+    const first = await readSecret('  Passphrase to encrypt this bundle with: ')
+    if (first.length < MIN_PASSPHRASE) {
+      process.stderr.write(`  At least ${MIN_PASSPHRASE} characters, please.\n`)
+      continue
+    }
+    if ((await readSecret('  Again, to confirm: ')) === first) return first
+    process.stderr.write('  They did not match.\n')
+  }
+}