@crombolo/cli 0.14.1 → 0.15.0

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')
+  }
+}

package/src/support/publish.ts

@@ -0,0 +1,142 @@
+/**
+ * Taking a page or a branch live, and back off again, without the backoffice.
+ *
+ * A publish can be refused per node — an unpublished ancestor, an unpublished
+ * mandatory language, an empty mandatory property — so the whole selection is
+ * checked before any of it is written. Half a published branch is a state
+ * nobody asked for and nobody can reason about.
+ */
+
+import { ObjectTypes } from '@crombolo/core'
+import {
+  currentSchemaState,
+  DocumentRepository,
+  describeRefFailure,
+  resolveNodeRef,
+} from '@crombolo/data'
+import { bootstrapDatabase } from '@crombolo/server'
+import { Args, Flags } from '@oclif/core'
+import { CliError } from '../errors.ts'
+import { many } from './flags.ts'
+import { type Io, siteConfig } from './site.ts'
+
+export const publishArgs = {
+  page: Args.string({ required: true, description: 'the page: a path or a uuid' }),
+}
+
+export const publishFlags = {
+  descendants: Flags.boolean({ summary: 'the branch below it too' }),
+  culture: many('only this culture; repeatable', '<iso>'),
+  at: Flags.string({ summary: 'schedule it for this time instead', helpValue: '<time>' }),
+  until: Flags.string({ summary: 'schedule the opposite for this time', helpValue: '<time>' }),
+}
+
+export const publishSpec = {
+  effects: 'idempotent',
+  cardinality: 'bounded',
+  outputFields: [
+    {
+      name: 'pages',
+      type: 'array',
+      items: {
+        type: 'object',
+        fields: [
+          { name: 'key', type: 'string' },
+          { name: 'name', type: 'string' },
+          { name: 'changed', type: 'boolean' },
+        ],
+      },
+    },
+    { name: 'scheduled', type: 'boolean' },
+    { name: 'cultures', type: 'array', items: { type: 'string' } },
+  ],
+  errors: ['not_found', 'refused', 'usage'],
+} as const
+
+const when = (value: string | undefined, what: string): Date | null => {
+  if (value === undefined) return null
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime()))
+    throw new CliError('usage', `${what} "${value}" is not a date I can read.`, {
+      hint: 'Try 2026-10-01T09:00.',
+    })
+  return date
+}
+
+export async function publishPages(
+  io: Io,
+  publishing: boolean,
+  ref: string,
+  flags: { descendants: boolean; culture: string[]; at?: string; until?: string },
+) {
+  const cultures = flags.culture
+  const publishTime = when(flags.at, '--at')
+  const unpublishTime = when(flags.until, '--until')
+  const config = await siteConfig()
+  const { db } = await bootstrapDatabase(config)
+  try {
+    const resolved = await resolveNodeRef(db, [ObjectTypes.Document], ref)
+    if (!resolved.ok) throw new CliError('not_found', describeRefFailure(ref, resolved))
+    const state = await currentSchemaState(db)
+    const docs = new DocumentRepository(db, {
+      nodeState: { version: state.version, revision: state.revision },
+      nodeId: config.nodeId,
+    })
+    // Parents before children, which is the order publishing has to happen in.
+    const targets = [
+      resolved.node,
+      ...(flags.descendants
+        ? await docs.nodes.descendants(resolved.node, [ObjectTypes.Document])
+        : []),
+    ]
+    const items: { key: string; name: string; changed: boolean }[] = []
+
+    if (publishTime || unpublishTime) {
+      // A schedule is a statement about the future, so today's blockers are not
+      // the question: the background job checks them when the time comes.
+      for (const node of targets) {
+        await docs.setSchedule(node.key, [
+          { culture: cultures[0] ?? null, publishTime, unpublishTime },
+        ])
+        items.push({ key: node.key, name: node.text ?? node.key, changed: true })
+        io.say(
+          `  scheduled ${node.text ?? node.key}${publishTime ? `  from ${publishTime.toISOString()}` : ''}${unpublishTime ? `  until ${unpublishTime.toISOString()}` : ''}`,
+        )
+      }
+      return { pages: items, scheduled: true, cultures }
+    }
+
+    if (publishing) {
+      const blocked: Array<{ name: string; reasons: string[] }> = []
+      // Everything in the selection counts as published for the check: the run
+      // publishes parents first, so a child is not blocked by an ancestor this
+      // very command is about to take live.
+      const selection = new Set(targets.map((node) => node.id))
+      for (const node of targets) {
+        const reasons = await docs.publishBlockers(node.key, cultures, selection)
+        if (reasons.length > 0) blocked.push({ name: node.text ?? node.key, reasons })
+      }
+      if (blocked.length > 0)
+        throw new CliError(
+          'refused',
+          `${blocked.length} of ${targets.length} page(s) cannot be published, so nothing was published.`,
+          { details: blocked.map((entry) => `${entry.name}  ${entry.reasons.join('; ')}`) },
+        )
+    }
+
+    for (const node of targets) {
+      const result = publishing
+        ? await docs.publish(node.key, cultures.length > 0 ? cultures : null)
+        : await docs.unpublish(node.key, cultures.length > 0 ? cultures : null)
+      items.push({ key: node.key, name: node.text ?? node.key, changed: Boolean(result) })
+      if (!result) continue
+      io.say(`  ${publishing ? 'published' : 'unpublished'} ${node.text ?? node.key}`)
+    }
+    io.say(
+      `\n${targets.length} page(s) ${publishing ? 'published' : 'unpublished'}${cultures.length > 0 ? ` in ${cultures.join(', ')}` : ''}.`,
+    )
+    return { pages: items, scheduled: false, cultures }
+  } finally {
+    await db.close()
+  }
+}

package/src/support/remote.ts

@@ -0,0 +1,58 @@
+/** What the remote commands share: the remote a command names, and the browser it opens. */
+import { osKeychain } from '@crombolo/server'
+import { CliError } from '../errors.ts'
+import { discover, RemoteClient } from '../remote/client.ts'
+import { pickRemote, readRemotes } from '../remote/remotes-file.ts'
+import { cwd } from './site.ts'
+
+export const keychain = () => osKeychain()
+
+export function openInBrowser(url: string, disabled: boolean): void {
+  if (disabled) 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 already; opening it is a convenience.
+  }
+}
+
+/** The remote a command names, signed in or not, with the environment it goes to. */
+export async function connectRemote(name: string | undefined, env: string | undefined) {
+  const entry = pickRemote(cwd(), name)
+  if (!entry) {
+    const known = readRemotes(cwd())
+    if (known.length === 0)
+      throw new CliError('not_found', 'No remotes yet.', {
+        hint: '`crombolo remote add <name> <url>` adds one.',
+      })
+    throw new CliError(
+      name ? 'not_found' : 'usage',
+      name ? `There is no remote "${name}".` : 'Which remote?',
+      { hint: `Name one of: ${known.map((r) => r.name).join(', ')}.` },
+    )
+  }
+  const discovery = await discover(entry.url)
+  const client = new RemoteClient(discovery, keychain())
+  const environment =
+    env ??
+    entry.environment ??
+    (discovery.environments.length === 1 ? discovery.environments[0]?.id : undefined)
+  return { entry, discovery, client, environment }
+}
+
+/** The environment, or a usage error naming the ones there are. */
+export function needEnvironment(
+  environment: string | undefined,
+  discovery: { environments: { id: string }[] },
+): string {
+  if (environment) return environment
+  throw new CliError('usage', 'Which environment?', {
+    hint: `Pass --env with one of: ${discovery.environments.map((e) => e.id).join(', ')}.`,
+  })
+}