@crombolo/cli 0.14.4 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/cli",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "The crombolo command line: scaffolding a site, schema, views, domains, content transfer and upgrades.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,17 +28,68 @@
     "src",
     "bin",
     "templates",
+    "oclif.manifest.json",
     "NOTICE"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/auth": "0.14.4",
-    "@crombolo/core": "0.14.4",
-    "@crombolo/data": "0.14.4",
-    "@crombolo/schema": "0.14.4",
-    "@crombolo/server": "0.14.4",
-    "@crombolo/transfer": "0.14.4"
+    "@crombolo/auth": "0.15.0",
+    "@crombolo/core": "0.15.0",
+    "@crombolo/data": "0.15.0",
+    "@crombolo/schema": "0.15.0",
+    "@crombolo/server": "0.15.0",
+    "@crombolo/transfer": "0.15.0",
+    "@oclif/core": "^5.1.8"
+  },
+  "oclif": {
+    "bin": "crombolo",
+    "commands": "./src/commands",
+    "topicSeparator": " ",
+    "helpOptions": {
+      "flagSortOrder": "none"
+    },
+    "topics": {
+      "admin": {
+        "description": "the administrator's account"
+      },
+      "assets": {
+        "description": "the stylesheets and scripts beside the components"
+      },
+      "bundle": {
+        "description": "bundles: install, check, and purge their tables"
+      },
+      "components": {
+        "description": "the components in components/: check, list, new"
+      },
+      "content": {
+        "description": "move content between environments as bundles, and publish it"
+      },
+      "dictionary": {
+        "description": "the dictionary as Umbraco .udt files"
+      },
+      "domains": {
+        "description": "the hostnames this site answers on (domains.toml)"
+      },
+      "import": {
+        "description": "replace this site with a whole-site file; import an Umbraco backup"
+      },
+      "maintenance": {
+        "description": "pause and resume editors' saves, cluster-wide"
+      },
+      "media": {
+        "description": "a pulled site's media files"
+      },
+      "remote": {
+        "description": "the remotes this site pulls from and pushes to (remotes.toml)"
+      },
+      "types": {
+        "description": "schema-as-code: the content types, data types and languages in schema/"
+      },
+      "upgrade": {
+        "description": "framework migrations: check, plan, apply, ledger"
+      }
+    }
   }
 }

package/src/base.ts

@@ -0,0 +1,129 @@
+/**
+ * What every crombolo command shares (story 150): the output flag, the failure
+ * envelope and exit codes, the audit entry, and the description `crombolo
+ * schema` publishes. A command's `run()` returns its result; in JSON mode that
+ * result is the output, and in text mode the command says it as it goes.
+ */
+import { Command, Errors, Flags } from '@oclif/core'
+import { classify, reportFailure } from './classify.ts'
+import { CliError, type ErrorKind, exitCodeOf, OUTCOMES, type OutcomeName } from './errors.ts'
+import * as ops from './operations/commands.ts'
+import type { Io } from './support/site.ts'
+import { siteConfig } from './support/site.ts'
+
+/** A field of one output record, in clispec's closed set of types. */
+export interface OutputField {
+  name: string
+  type: 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array'
+  nullable?: boolean
+  description?: string
+  enum?: readonly unknown[]
+  fields?: readonly OutputField[]
+  items?: Omit<OutputField, 'name'>
+}
+
+/** The clispec v0.3 properties of a command, beyond its args and flags. */
+export interface CommandSpec {
+  effects: 'read_only' | 'idempotent' | 'non_idempotent'
+  outputKind?: 'data' | 'stream' | 'opaque'
+  cardinality?: 'single' | 'bounded' | 'unbounded'
+  outputFields?: readonly OutputField[]
+  /** For a shape that depends on the input: `{}` says exactly that. */
+  stdoutSchema?: Record<string, unknown>
+  errors?: readonly ErrorKind[]
+  outcomes?: readonly OutcomeName[]
+  confirmationBypassArg?: string
+  requiresTty?: boolean
+  pagination?: { style: 'offset'; offsetArg: string; limitArg: string }
+  fieldsArg?: string
+  stability?: 'stable' | 'beta' | 'experimental' | 'deprecated'
+}
+
+export interface AuditSpec {
+  category: ops.CommandAudit['category']
+  action: string
+  entityType?: string
+}
+
+/** `-o json`, `-ojson`, `-o=json`, `--output json`, `--output=json` or `--json`, before any `--`. */
+export function wantsJson(argv: readonly string[]): boolean {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string
+    if (arg === '--') return false
+    if (arg === '--json' || arg === '-ojson' || arg === '-o=json' || arg === '--output=json')
+      return true
+    if ((arg === '-o' || arg === '--output') && argv[i + 1] === 'json') return true
+  }
+  return false
+}
+
+export abstract class BaseCommand extends Command implements Io {
+  static override baseFlags = {
+    output: Flags.option({
+      char: 'o',
+      options: ['text', 'json'] as const,
+      default: 'text' as const,
+      summary: 'text for people; json for scripts, on stdout',
+      helpGroup: 'GLOBAL',
+    })(),
+    json: Flags.boolean({ hidden: true, summary: 'the same as -o json' }),
+  }
+
+  static spec: CommandSpec
+  static audit?: AuditSpec
+
+  /** Set by a command whose check found what it reports: the exit code, with no envelope. */
+  protected outcome?: OutcomeName
+  /** The entity an audit entry names, when the command acted on one. */
+  protected auditKey?: string
+  /** A dry run or a plan changes nothing, so it writes no audit entry. */
+  protected changedNothing = false
+
+  override jsonEnabled(): boolean {
+    return wantsJson(this.argv)
+  }
+
+  protected override logJson(json: unknown): void {
+    process.stdout.write(`${JSON.stringify(json, null, 2)}\n`)
+  }
+
+  say = (line = ''): void => {
+    this.log(line)
+  }
+
+  progress = (line: string): void => {
+    process.stderr.write(`${line}\n`)
+  }
+
+  warning = (line: string): void => {
+    process.stderr.write(`${line}\n`)
+  }
+
+  protected override async _run<T>(): Promise<T> {
+    const result = await super._run<T>()
+    if (this.outcome) this.exit(OUTCOMES[this.outcome].code)
+    return result
+  }
+
+  protected override async catch(error: Error): Promise<never> {
+    if (error instanceof Errors.ExitError) throw error
+    const failure = classify(error)
+    reportFailure(failure, this.jsonEnabled())
+    throw new Errors.ExitError(exitCodeOf(failure.kind))
+  }
+
+  protected override async finally(error: Error | undefined): Promise<void> {
+    const audit = (this.constructor as typeof BaseCommand).audit
+    if (error || !audit || this.changedNothing) return
+    await ops.recordCommand(await siteConfig(), {
+      ...audit,
+      command: `crombolo ${(this.id ?? '').replaceAll(':', ' ')}`,
+      entityKey: this.auditKey,
+    })
+  }
+
+  /** A failure, as the command's own sentence. */
+  protected fail(kind: ErrorKind, message: string, hint?: string, details?: unknown): never {
+    throw new CliError(kind, message, { hint, details })
+  }
+}

package/src/classify.ts

@@ -0,0 +1,119 @@
+/**
+ * Any error a command lets go of, as a `CliError`: the kind it is, so the exit
+ * code and the envelope follow from one table.
+ */
+import { MigrationStepError, UpgradeStateError } from '@crombolo/data'
+import { CommandError, PassphraseError } from '@crombolo/server'
+import { CliError, ERROR_KINDS, type ErrorKind } from './errors.ts'
+import { RemoteError, TimedOut } from './remote/client.ts'
+
+const REMOTE_CODES: Record<string, ErrorKind> = {
+  'sign-in-required': 'auth',
+  unreachable: 'unavailable',
+  'not-a-remote': 'not_found',
+}
+
+function remoteKind(error: RemoteError): ErrorKind {
+  const { code, status } = error.problem
+  const known = REMOTE_CODES[code]
+  if (known) return known
+  if (status === 401) return 'auth'
+  if (status === 403) return 'refused'
+  if (status === 404) return 'not_found'
+  if (status === 409) return 'conflict'
+  if (status === 429 || status >= 500) return 'unavailable'
+  return 'refused'
+}
+
+const SYSTEM_CODES: Record<string, ErrorKind> = {
+  ENOENT: 'io',
+  EACCES: 'io',
+  EPERM: 'io',
+  ENOSPC: 'io',
+  EISDIR: 'io',
+  ENOTDIR: 'io',
+  ECONNREFUSED: 'unavailable',
+  ECONNRESET: 'unavailable',
+  ETIMEDOUT: 'unavailable',
+  ENOTFOUND: 'unavailable',
+  EAI_AGAIN: 'unavailable',
+  SQLITE_BUSY: 'conflict',
+}
+
+/**
+ * The parser's sentence without its advice: the note about a repeatable flag
+ * swallowing arguments does not apply, since every repeatable flag here takes
+ * one value each time, and the pointer to --help is the hint.
+ */
+function parserMessage(message: string): string {
+  return (
+    message
+      .split(/\n\s*\nNote: /)[0]
+      ?.split('\n')
+      .filter((line) => !/^See more help with/.test(line))
+      .join('\n')
+      .trim() ?? message
+  )
+}
+
+export function classify(error: unknown): CliError {
+  if (error instanceof CliError) return error
+  if (error instanceof TimedOut)
+    return new CliError('timeout', error.message, {
+      hint: `The job carries on at the remote: \`crombolo remote job ${error.job.id}\` watches it again.`,
+    })
+  if (error instanceof RemoteError)
+    return new CliError(remoteKind(error), error.message, {
+      details: error.problem.items,
+    })
+  if (error instanceof PassphraseError)
+    return new CliError('auth', error.message, { details: error.problems })
+  if (error instanceof CommandError)
+    return new CliError('refused', error.message, {
+      details: error.problems.length > 0 ? error.problems : undefined,
+    })
+  if (error instanceof UpgradeStateError) return new CliError('refused', error.message)
+  if (error instanceof MigrationStepError) return new CliError('internal', error.message)
+  // The parser's own errors: an unknown flag, a missing argument, a bad value;
+  // and, before any command runs, an unknown command.
+  if (error instanceof Error && ('parse' in error || /^command .* not found$/.test(error.message)))
+    return new CliError('usage', parserMessage(error.message), {
+      hint: 'Pass --help to see what it takes.',
+    })
+  const code = (error as { code?: unknown } | null)?.code
+  if (typeof code === 'string' && SYSTEM_CODES[code])
+    return new CliError(SYSTEM_CODES[code], (error as Error).message)
+  return new CliError('internal', error instanceof Error ? error.message : String(error), {
+    details: process.env.CROMBOLO_DEBUG && error instanceof Error ? error.stack : undefined,
+  })
+}
+
+/**
+ * Says a failure. In JSON mode stderr's last line is the envelope; in text mode
+ * a person reads sentences, and when stderr is not a terminal the envelope
+ * follows them as the last line, so a script reading a pipe can branch on it
+ * without asking for JSON.
+ */
+export function reportFailure(failure: CliError, json: boolean): void {
+  if (!json) {
+    if (Array.isArray(failure.details))
+      for (const item of failure.details) process.stderr.write(`  ${String(item)}\n`)
+    else if (typeof failure.details === 'string') process.stderr.write(`${failure.details}\n`)
+    process.stderr.write(`${failure.message}\n`)
+    if (failure.hint) process.stderr.write(`  ${failure.hint}\n`)
+    if (process.stderr.isTTY) return
+  }
+  const kind = ERROR_KINDS[failure.kind]
+  process.stderr.write(
+    `${JSON.stringify({
+      error: {
+        kind: failure.kind,
+        message: failure.message,
+        ...(failure.hint ? { hint: failure.hint } : {}),
+        ...(failure.details !== undefined ? { details: failure.details } : {}),
+        exit_code: kind.exitCode,
+        ...('retryable' in kind ? { retryable: kind.retryable } : {}),
+      },
+    })}\n`,
+  )
+}

package/src/clispec.ts

@@ -0,0 +1,163 @@
+/**
+ * The CLI described as a clispec v0.3 document (https://clispec.dev), built
+ * from the loaded commands: their args and flags as oclif reads them, and the
+ * `spec` each declares. Nothing here touches a site, a network or a sign-in.
+ */
+import type { Command } from '@oclif/core'
+import type { CommandSpec, OutputField } from './base.ts'
+import { ERROR_KINDS, OUTCOMES } from './errors.ts'
+
+export const CLISPEC_VERSION = '0.3'
+
+/** The flags every command takes, published once as `global_args`. */
+const GLOBAL_FLAGS = new Set(['output', 'json'])
+
+type Arg = Record<string, unknown>
+
+function field(f: Omit<OutputField, 'name'> & { name?: string }): Record<string, unknown> {
+  return {
+    ...(f.name !== undefined ? { name: f.name } : {}),
+    type: f.type,
+    ...(f.nullable ? { nullable: true } : {}),
+    ...(f.enum ? { enum: f.enum } : {}),
+    ...(f.description ? { description: f.description } : {}),
+    ...(f.fields ? { fields: f.fields.map(field) } : {}),
+    ...(f.type === 'array' ? { items: field(f.items ?? { type: 'string' }) } : {}),
+  }
+}
+
+function flagArg(name: string, flag: Command.Flag.Cached): Arg {
+  const valued = flag.type === 'option'
+  const options = valued && 'options' in flag ? flag.options : undefined
+  const fallback = flag.default
+  const type = !valued
+    ? 'boolean'
+    : typeof fallback === 'number'
+      ? 'integer'
+      : flag.multiple
+        ? 'string[]'
+        : 'string'
+  return {
+    name: `--${name}`,
+    type,
+    ...(flag.char ? { short: `-${flag.char}` } : {}),
+    ...(flag.required ? { required: true } : {}),
+    ...(fallback !== undefined &&
+    typeof fallback !== 'function' &&
+    !(Array.isArray(fallback) && fallback.length === 0)
+      ? { default: fallback }
+      : {}),
+    ...(options ? { enum: [...options] } : {}),
+    ...(flag.summary || flag.description ? { description: flag.summary ?? flag.description } : {}),
+  }
+}
+
+function positional(name: string, arg: Command.Arg.Cached): Arg {
+  return {
+    name,
+    type: 'string',
+    ...(arg.required ? { required: true } : {}),
+    ...(arg.options ? { enum: [...arg.options] } : {}),
+    ...(arg.description ? { description: arg.description } : {}),
+  }
+}
+
+function describeCommand(command: Command.Cached): Record<string, unknown> {
+  const spec = command.spec as CommandSpec | undefined
+  if (!spec) throw new Error(`${command.id} declares no spec`)
+  const kind = spec.outputKind ?? 'data'
+  const args = [
+    ...Object.entries(command.args)
+      .filter(([, arg]) => !arg.hidden)
+      .map(([name, arg]) => positional(name, arg)),
+    ...Object.entries(command.flags)
+      .filter(([name, flag]) => !GLOBAL_FLAGS.has(name) && !flag.hidden)
+      .map(([name, flag]) => flagArg(name, flag)),
+  ]
+  const errors = [
+    ...new Set([
+      'usage',
+      'internal',
+      ...(spec.errors ?? []),
+      ...(spec.confirmationBypassArg ? ['confirmation_required'] : []),
+    ]),
+  ]
+  return {
+    name: command.id.replaceAll(':', ' '),
+    description: command.summary ?? command.description ?? command.id,
+    effects: spec.effects,
+    ...(kind !== 'data' ? { output_kind: kind } : {}),
+    ...(kind === 'data' ? { cardinality: spec.cardinality ?? 'single' } : {}),
+    ...(kind === 'data' && spec.outputFields
+      ? { output_fields: spec.outputFields.map(field) }
+      : {}),
+    ...(kind === 'data' && spec.stdoutSchema ? { stdout_schema: spec.stdoutSchema } : {}),
+    ...(kind === 'data' && !spec.outputFields && !spec.stdoutSchema ? { stdout_schema: {} } : {}),
+    ...(spec.pagination
+      ? {
+          pagination: {
+            style: spec.pagination.style,
+            offset_arg: spec.pagination.offsetArg,
+            limit_arg: spec.pagination.limitArg,
+          },
+        }
+      : {}),
+    ...(spec.fieldsArg ? { fields_arg: spec.fieldsArg } : {}),
+    ...(spec.confirmationBypassArg ? { confirmation_bypass_arg: spec.confirmationBypassArg } : {}),
+    ...(spec.requiresTty ? { requires_tty: true } : {}),
+    ...(spec.stability ? { stability: spec.stability } : {}),
+    ...(args.length > 0 ? { args } : {}),
+    errors,
+    ...(spec.outcomes?.length ? { outcomes: [...spec.outcomes] } : {}),
+  }
+}
+
+/** What the document is built from: a loaded oclif config, or the manifest's data. */
+export interface CommandSource {
+  bin: string
+  version: string
+  commands: readonly Command.Cached[]
+}
+
+/** The whole CLI, or the commands under `path` (`content`, `content import`). */
+export function clispecDocument(config: CommandSource, path: readonly string[] = []) {
+  const prefix = path.join(' ')
+  const commands = config.commands
+    .filter((command) => !command.hidden)
+    .map(describeCommand)
+    .filter((command) => {
+      const name = command.name as string
+      return prefix === '' || name === prefix || name.startsWith(`${prefix} `)
+    })
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)))
+  return {
+    clispec: CLISPEC_VERSION,
+    name: config.bin,
+    version: config.version,
+    description: 'The crombolo command line: a site, its schema, content, remotes and upgrades.',
+    output: { piped: 'text', tty: 'text' },
+    global_args: [
+      {
+        name: '--output',
+        short: '-o',
+        type: 'string',
+        enum: ['text', 'json'],
+        default: 'text',
+        description: 'text for people; json for scripts, on stdout',
+      },
+      { name: '--json', type: 'boolean', description: 'the same as -o json' },
+    ],
+    commands,
+    errors: Object.entries(ERROR_KINDS).map(([kind, e]) => ({
+      kind,
+      exit_code: e.exitCode,
+      ...('retryable' in e ? { retryable: e.retryable } : {}),
+      description: e.description,
+    })),
+    outcomes: Object.entries(OUTCOMES).map(([name, o]) => ({
+      code: o.code,
+      name,
+      description: o.description,
+    })),
+  }
+}

package/src/commands/admin/reset-password.ts

@@ -0,0 +1,53 @@
+import { AuthStore, resetAdminPassword } from '@crombolo/auth'
+import { bootstrapDatabase } from '@crombolo/server'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { readStdin } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class AdminResetPassword extends BaseCommand {
+  static override summary = "reset the administrator's password and print it"
+  static override description =
+    'A new one is generated unless --stdin gives it, so it never sits in shell history.'
+  static override examples = [
+    '<%= config.bin %> admin reset-password',
+    'printf %s "$PASSWORD" | <%= config.bin %> admin reset-password --stdin',
+  ]
+  static override args = {
+    password: Args.string({ hidden: true, description: 'deprecated: use --stdin' }),
+  }
+  static override flags = {
+    stdin: Flags.boolean({ summary: 'read the new password from stdin' }),
+  }
+  static override audit = { category: 'user', action: 'ResetPassword', entityType: 'User' } as const
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'login', type: 'string' },
+      { name: 'password', type: 'string' },
+    ],
+    errors: ['not_found'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(AdminResetPassword)
+    if (args.password)
+      this.warning('  deprecated  a password on the command line: pipe it to --stdin instead')
+    const given = flags.stdin ? await readStdin() : args.password
+    const config = await siteConfig()
+    // The database, not the server: resetting a password has nothing to do with
+    // the schema sync, the caches or the port, and should not need them to be
+    // healthy to work.
+    const { db } = await bootstrapDatabase(config)
+    const result = await resetAdminPassword(
+      new AuthStore(db),
+      config.adminLogin,
+      given || undefined,
+    )
+    await db.close()
+    if (!result) this.fail('not_found', `No account '${config.adminLogin}'.`)
+    this.say(`${result.login}\n${result.password}`)
+    return { login: result.login, password: result.password }
+  }
+}

package/src/commands/assets/index.ts

@@ -0,0 +1,6 @@
+import AssetsList from './list.ts'
+
+/** `crombolo assets` on its own lists them. */
+export default class Assets extends AssetsList {
+  static override hidden = true
+}

package/src/commands/assets/list.ts

@@ -0,0 +1,27 @@
+import { listAssets } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** The stylesheets and scripts the backoffice also edits. */
+export default class AssetsList extends BaseCommand {
+  static override summary = 'the stylesheets and scripts this site has'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'bounded',
+    // One item of `items`, as clispec reads a collection.
+    outputFields: [
+      { name: 'kind', type: 'string' },
+      { name: 'path', type: 'string' },
+    ],
+  } as const
+
+  async run() {
+    await this.parse(this.ctor)
+    const found = listAssets(await siteConfig())
+    if (found.length === 0) this.say('No stylesheets or scripts here.')
+    const items = found.map((asset) => ({ kind: asset.kind, path: here(asset.path) }))
+    for (const asset of items) this.say(`  ${asset.kind.padEnd(10)} ${asset.path}`)
+    return { items }
+  }
+}

package/src/commands/assets/new.ts

@@ -0,0 +1,42 @@
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { assetDirs, assetScaffold } from '@crombolo/server'
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class AssetsNew extends BaseCommand {
+  static override summary = 'write an empty stylesheet or script in the place the backoffice edits'
+  static override examples = ['<%= config.bin %> assets new stylesheet site.css']
+  static override args = {
+    kind: Args.string({
+      required: true,
+      options: ['stylesheet', 'script'],
+      description: 'which kind',
+    }),
+    name: Args.string({ required: true, description: 'its file name' }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [{ name: 'created', type: 'string' }],
+    errors: ['conflict'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(AssetsNew)
+    const kind = args.kind as 'stylesheet' | 'script'
+    const where = assetDirs(await siteConfig())[kind]
+    const file = join(
+      where.dir,
+      args.name.endsWith(where.extension) ? args.name : `${args.name}${where.extension}`,
+    )
+    if (existsSync(file)) this.fail('conflict', `${here(file)} already exists.`)
+    await mkdir(join(file, '..'), { recursive: true })
+    await writeFile(file, assetScaffold(kind, relative(where.dir, file)))
+    this.say(`  created  ${here(file)}`)
+    return { created: here(file) }
+  }
+}