@crombolo/cli 0.14.4 → 0.16.0

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/media-tree.ts

@@ -0,0 +1,72 @@
+/**
+ * The media tree, for the bulk commands (story 153): its folders by name, what
+ * a file's extension makes it, and the repository and file store an upload
+ * goes through, so an imported file is placed exactly as the back office
+ * places one.
+ */
+import { ObjectTypes, SystemNodes } from '@crombolo/core'
+import {
+  currentSchemaState,
+  type Db,
+  DocumentRepository,
+  describeRefFailure,
+  NodeRepository,
+  type NodeRow,
+  resolveNodeRef,
+} from '@crombolo/data'
+import {
+  type CromboloConfig,
+  createFileIntake,
+  createMediaPort,
+  MediaFileStore,
+  mediaStoreFor,
+} from '@crombolo/server'
+import { CliError } from '../errors.ts'
+
+export async function openMedia(db: Db, config: CromboloConfig) {
+  const files = new MediaFileStore(await mediaStoreFor(config))
+  const state = await currentSchemaState(db)
+  const options = {
+    nodeState: { version: state.version, revision: state.revision },
+    nodeId: `cli:${config.nodeId}`,
+  }
+  return {
+    files,
+    nodes: new NodeRepository(db),
+    repo: new DocumentRepository(db, {
+      ...options,
+      kind: 'media',
+      valueIntake: createFileIntake(files),
+    }),
+    // For the rules alone — which type takes which file — not for writing: a
+    // write through the port tells the cluster once per item.
+    port: createMediaPort(db, files, options),
+  }
+}
+
+export type MediaTree = Awaited<ReturnType<typeof openMedia>>
+
+/** The node a `--under` names, or the root. */
+export async function mediaParent(db: Db, ref: string | undefined): Promise<NodeRow | null> {
+  if (!ref) return null
+  const resolved = await resolveNodeRef(db, [ObjectTypes.Media], ref)
+  if (!resolved.ok) throw new CliError('not_found', describeRefFailure(ref, resolved))
+  return resolved.node
+}
+
+/** The media directly under a node, by name. */
+export async function childrenByName(
+  tree: MediaTree,
+  parent: NodeRow | null,
+): Promise<Map<string, NodeRow>> {
+  const page = await tree.nodes.children(
+    parent?.id ?? SystemNodes.Root,
+    ObjectTypes.Media,
+    0,
+    Number.MAX_SAFE_INTEGER,
+  )
+  return new Map(page.items.map((node) => [node.text ?? '', node]))
+}
+
+export const sha256 = (bytes: Uint8Array): string =>
+  new Bun.CryptoHasher('sha256').update(bytes).digest('hex')

package/src/support/people.ts

@@ -0,0 +1,134 @@
+/**
+ * Back-office users from the command line (story 151), through the same user
+ * port the Management API uses, so a rule the back office keeps — who may act
+ * on an admin, what an invite is — is the rule here too. It opens the site's
+ * database directly, not through the server, so it works when the site will not
+ * boot; in a container it runs through `docker exec`.
+ */
+import type { Principal, UserPort, UserStatus } from '@crombolo/api-management'
+import { AuthStore } from '@crombolo/auth'
+import { type Db, SUPER_USER_KEY, UserRepository } from '@crombolo/data'
+import {
+  bootstrapDatabase,
+  type CromboloConfig,
+  createNodeLookup,
+  createUserPorts,
+  MediaFileStore,
+  mediaStoreFor,
+  TwoFactorService,
+} from '@crombolo/server'
+import { CliError, type ErrorKind } from '../errors.ts'
+
+/** The operator: an administrator who is nobody in particular, so no rule about acting on oneself applies. */
+const CLI_PRINCIPAL_ID = '00000000-0000-4000-8000-0000000c1c1e'
+
+const principal = (id: string): Principal =>
+  ({
+    id,
+    userName: 'crombolo',
+    name: 'The command line',
+    email: '',
+    isAdmin: true,
+    languageIsoCode: undefined,
+    avatarUrls: [],
+    allowedSections: [],
+    permissions: [],
+    groupKeys: [],
+    hasAccessToAllLanguages: true,
+    languages: [],
+  }) as unknown as Principal
+
+/** Sees every user, the built-in administrator included, as only that administrator may. */
+export const OBSERVER = principal(SUPER_USER_KEY)
+/** Acts on any user, the built-in administrator included. */
+export const OPERATOR = principal(CLI_PRINCIPAL_ID)
+
+export interface People {
+  config: CromboloConfig
+  db: Db
+  users: UserPort
+  repository: UserRepository
+  twoFactor: TwoFactorService
+  /** The link the last invite would have e-mailed. */
+  lastLink(): string | undefined
+}
+
+export async function openPeople(config: CromboloConfig): Promise<People> {
+  const { db } = await bootstrapDatabase(config)
+  const store = new AuthStore(db)
+  let link: string | undefined
+  const { users } = createUserPorts(db, {
+    config: {
+      ...config,
+      // Captured, not sent: the command prints it, for a site with no e-mail.
+      sendUserLink: async (message) => {
+        link = message.link
+      },
+    },
+    mediaFiles: new MediaFileStore(await mediaStoreFor(config)),
+    nodes: createNodeLookup(db),
+    endSessions: async (userId) => {
+      await store.endAllSessionsForUser(userId)
+    },
+  })
+  return {
+    config,
+    db,
+    users,
+    repository: new UserRepository(db),
+    twoFactor: new TwoFactorService(db, { secretKey: config.secretKey, issuer: config.siteName }),
+    lastLink: () => link,
+  }
+}
+
+/** A user by e-mail or username, whatever the casing; `not_found` otherwise. */
+export async function userNamed(people: People, who: string) {
+  const wanted = who.trim().toLowerCase()
+  const rows = await people.db.query<{ key: string }>(
+    'SELECT key FROM user_account WHERE LOWER(email) = ? OR LOWER(user_name) = ?',
+    [wanted, wanted],
+  )
+  const key = rows[0]?.key
+  const user = key ? await people.repository.byKey(String(key)) : undefined
+  if (!user)
+    throw new CliError('not_found', `No user "${who}".`, {
+      hint: '`crombolo users list` lists them.',
+    })
+  return user
+}
+
+const STATUS_KINDS: Partial<Record<UserStatus, ErrorKind>> = {
+  UserNotFound: 'not_found',
+  MissingUserGroup: 'not_found',
+  DuplicateUserName: 'conflict',
+  DuplicateEmail: 'conflict',
+  InvalidEmail: 'usage',
+  InvalidUserName: 'usage',
+  UserNameIsNotEmail: 'usage',
+  InvalidPassword: 'usage',
+  NoUserGroup: 'usage',
+}
+
+const STATUS_MESSAGES: Partial<Record<UserStatus, string>> = {
+  CannotDisableInvitedUser: 'An invited user cannot be disabled; delete the invitation instead.',
+  CannotInvite: 'The invitation could not be made.',
+  InvalidPassword: "That password does not meet this site's password rules.",
+  DuplicateEmail: 'Another user has that e-mail address.',
+  DuplicateUserName: 'Another user has that username.',
+  MissingUserGroup: 'There is no group with that alias.',
+}
+
+/** A user port status other than `Success`, as a failure. */
+export function checkStatus(status: UserStatus): void {
+  if (status === 'Success') return
+  throw new CliError(STATUS_KINDS[status] ?? 'refused', STATUS_MESSAGES[status] ?? status)
+}
+
+export function describeUser(user: {
+  key: string
+  name: string
+  email: string
+  userName: string
+}): string {
+  return `${user.name} <${user.email || user.userName}>`
+}