@crombolo/cli 0.14.1 → 0.15.0

package/src/commands/bundle/purge.ts

@@ -0,0 +1,71 @@
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { backupTaken, dryRun } from '../../support/flags.ts'
+import { confirm } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/**
+ * Drops a bundle's tables and forgets its state. Taking a bundle out of
+ * `bundles` leaves them in place, so re-adding it resumes; this is the
+ * deliberate act that does not.
+ */
+export default class BundlePurge extends BaseCommand {
+  static override summary = "back up, then drop a bundle's tables and clear its state"
+  static override description =
+    'Refused while crombolo.config.ts still wires the bundle. Asks for the id to be typed back, unless --yes.'
+  static override args = { id: Args.string({ required: true, description: "the bundle's id" }) }
+  static override flags = {
+    yes: Flags.boolean({ summary: "don't ask: drop them" }),
+    'dry-run': dryRun,
+    'backup-taken': backupTaken,
+  }
+  static override audit = { category: 'system', action: 'Purge', entityType: 'Bundle' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    confirmationBypassArg: '--yes',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'tables', type: 'array', items: { type: 'string' } },
+      { name: 'dropped', type: 'array', items: { type: 'string' } },
+      { name: 'backup', type: 'string', nullable: true },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['confirmation_required', 'refused'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(BundlePurge)
+    const id = args.id
+    this.auditKey = id
+    const config = await siteConfig()
+    const plan = await ops.bundlePurgePlan(config, id)
+    if (plan.tables.length === 0) this.say(`  The bundle "${id}" has no tables in this database.`)
+    else {
+      this.say(`  This drops ${plan.tables.length} table(s), and every row in them:`)
+      for (const table of plan.tables) this.say(`    ${table}`)
+    }
+    if (flags['dry-run']) {
+      this.changedNothing = true
+      return { id, tables: plan.tables, dropped: [], backup: null, changed: false }
+    }
+    if (!flags.yes)
+      await confirm(`  Purge the bundle "${id}"? Type its id to confirm:`, {
+        bypass: '--yes',
+        answer: id,
+        declined: 'Nothing was dropped.',
+      })
+    const result = await ops.bundlePurge(config, id, { backupTaken: flags['backup-taken'] })
+    if (result.backup.path) this.progress(`  backup   ${result.backup.path}`)
+    for (const table of result.dropped) this.say(`  dropped  ${table}`)
+    this.say(`  The bundle "${id}"'s state is cleared; adding it again starts its tables afresh.`)
+    return {
+      id,
+      tables: plan.tables,
+      dropped: result.dropped,
+      backup: result.backup.path ?? null,
+      changed: result.dropped.length > 0,
+    }
+  }
+}

package/src/commands/components/check.ts

@@ -0,0 +1,58 @@
+import { checkComponents } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { declaredTypes } from '../../support/components.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/**
+ * A view is loaded when a request renders it, so one that does not compile is a
+ * 500 waiting for a visitor. This is that failure brought forward.
+ */
+export default class ComponentsCheck extends BaseCommand {
+  static override summary = 'compile every component, and report one a type declares with no file'
+  static override description = 'Exits 20 when a component does not compile or type-check.'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'checked', type: 'integer' },
+      { name: 'templates', type: 'integer' },
+      { name: 'problems', type: 'array', items: { type: 'object' } },
+      { name: 'typeProblems', type: 'array', items: { type: 'string' } },
+      { name: 'typesNote', type: 'string', nullable: true },
+    ],
+    outcomes: ['problems_found'],
+  } as const
+
+  async run() {
+    await this.parse(this.ctor)
+    const config = await siteConfig()
+    const types = declaredTypes(config)
+    const report = await checkComponents({
+      componentsDir: config.componentsDir,
+      siteDir: config.siteDir,
+      declaredComponents: types.flatMap((type) => type.components),
+    })
+    const templates = report.declared.length
+    this.say(
+      `  checked  ${report.components.length} file(s): ${templates} template(s), ` +
+        `${report.components.length - templates} component(s)`,
+    )
+    for (const problem of report.problems)
+      this.say(`  [error]  ${problem.file}: ${problem.message}`)
+    if (report.types.note) this.say(`  types    ${report.types.note}`)
+    else {
+      this.say(`  types    tsc --noEmit over ${here(config.siteDir)}`)
+      for (const problem of report.types.problems) this.say(`  [types]  ${problem}`)
+    }
+    if (report.problems.length > 0 || report.types.problems.length > 0)
+      this.outcome = 'problems_found'
+    return {
+      checked: report.components.length,
+      templates,
+      problems: report.problems.map((p) => ({ file: p.file, message: p.message })),
+      typeProblems: report.types.problems,
+      typesNote: report.types.note ?? null,
+    }
+  }
+}

package/src/commands/components/index.ts

@@ -0,0 +1,6 @@
+import ComponentsCheck from './check.ts'
+
+/** `crombolo components` on its own is the check. */
+export default class Components extends ComponentsCheck {
+  static override hidden = true
+}

package/src/commands/components/list.ts

@@ -0,0 +1,40 @@
+import { listComponents } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { declaredTypes } from '../../support/components.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class ComponentsList extends BaseCommand {
+  static override summary = 'what is in components/, and which type declares each'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'bounded',
+    // One item of `items`, as clispec reads a collection.
+    outputFields: [
+      { name: 'alias', type: 'string' },
+      { name: 'path', type: 'string' },
+      { name: 'kind', type: 'string', enum: ['template', 'component'] },
+      { name: 'declaredBy', type: 'array', items: { type: 'string' } },
+    ],
+  } as const
+
+  async run() {
+    await this.parse(ComponentsList)
+    const config = await siteConfig()
+    const types = declaredTypes(config)
+    const found = listComponents(config.componentsDir)
+    if (found.length === 0) this.say(`Nothing in ${here(config.componentsDir)}.`)
+    const items = found.map((component) => {
+      // A component is a template because a content type names it, not
+      // because of where it sits — so the label is read off the schema.
+      const declaredBy = types
+        .filter((type) => type.components.includes(component.alias))
+        .map((type) => type.alias)
+      const kind = declaredBy.length > 0 ? ('template' as const) : ('component' as const)
+      const note = declaredBy.length > 0 ? `  ← ${declaredBy.join(', ')}` : ''
+      this.say(`  ${kind.padEnd(9)} ${here(component.path)}${note}`)
+      return { alias: component.alias, path: here(component.path), kind, declaredBy }
+    })
+    return { items }
+  }
+}

package/src/commands/components/new.ts

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { viewScaffold } from '@crombolo/schema'
+import { componentFileFor, componentScaffold, isSafeAlias } from '@crombolo/server'
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { declaredTypes } from '../../support/components.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class ComponentsNew extends BaseCommand {
+  static override summary = 'components/<alias>.tsx; the alias may carry folders'
+  static override examples = ['<%= config.bin %> components new pages/article']
+  static override args = {
+    alias: Args.string({ required: true, description: "the component's alias" }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'created', type: 'string' },
+      { name: 'template', type: 'boolean' },
+    ],
+    errors: ['usage', 'conflict'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(ComponentsNew)
+    const config = await siteConfig()
+    if (!isSafeAlias(args.alias))
+      this.fail('usage', `"${args.alias}" is not a path inside ${here(config.componentsDir)}.`)
+    const file = componentFileFor(config.componentsDir, args.alias)
+    if (existsSync(file)) this.fail('conflict', `${here(file)} already exists.`)
+    // A content type that names this alias gets the page scaffold, which takes
+    // PageProps; anything else gets the plain one. Nothing turns on the folder.
+    const type = declaredTypes(config).find((candidate) =>
+      candidate.components.includes(args.alias),
+    )
+    if (!type)
+      this.say(
+        `  note     no content type declares the template "${args.alias}" — add it to one's templates, or \`crombolo types new\``,
+      )
+    await mkdir(join(file, '..'), { recursive: true })
+    await writeFile(file, type ? viewScaffold(type) : componentScaffold(args.alias))
+    this.say(`  created  ${here(file)}`)
+    return { created: here(file), template: Boolean(type) }
+  }
+}

package/src/commands/content/check.ts

@@ -0,0 +1,102 @@
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { RESOLUTIONS_FILE, writeResolutions } from '@crombolo/transfer'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import {
+  describeBundle,
+  findingsOf,
+  here,
+  printSections,
+  printTransferFindings,
+} from '../../support/describe.ts'
+import { transferFlags, transferInput } from '../../support/flags.ts'
+import { passphraseToOpen } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class ContentCheck extends BaseCommand {
+  static override summary = "read-only: what installing a bundle's content here would do"
+  static override description = [
+    'Says what it needs from a person first, and writes it to the Changes dashboard. --save writes the answers given into the bundle.',
+    'An encrypted bundle asks for its passphrase, or reads CROMBOLO_BUNDLE_PASSPHRASE. Exits 21 when a finding would stop an import.',
+  ].join('\n\n')
+  static override aliases = ['bundle:check']
+  static override args = {
+    bundle: Args.string({
+      required: true,
+      description: 'a package directory, or the name of a bundle this site depends on',
+    }),
+  }
+  static override flags = {
+    ...transferFlags,
+    save: Flags.boolean({ summary: 'write the answers into the bundle' }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'bundle', type: 'object' },
+      { name: 'under', type: 'string', nullable: true },
+      { name: 'counts', type: 'object' },
+      { name: 'findings', type: 'array', items: { type: 'object' } },
+      { name: 'outstanding', type: 'integer' },
+      { name: 'clean', type: 'boolean' },
+      { name: 'wouldNotPublish', type: 'array', items: { type: 'object' } },
+      { name: 'saved', type: 'string', nullable: true },
+    ],
+    errors: ['refused', 'auth'],
+    outcomes: ['blocked'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(ContentCheck)
+    const config = await siteConfig()
+    const result = await ops.contentCheck(config, {
+      ...transferInput(args.bundle, flags),
+      passphrase: await passphraseToOpen(args.bundle, config),
+    })
+    for (const problem of result.problems) this.warning(`  ${problem}`)
+    describeBundle(this, result.bundle)
+    if (result.under) this.say(`  under    ${result.under}`)
+    printSections(this, result.sections)
+    printTransferFindings(this, result.check)
+    // The reasons are publish's own: the check rehearsed the import to find them.
+    for (const refusal of result.publishRefusals)
+      this.say(`  would not publish  ${refusal.key}: ${refusal.reason}`)
+
+    let saved: string | null = null
+    if (flags.save) {
+      const target = join(result.payloadDir, RESOLUTIONS_FILE)
+      await writeFile(
+        target,
+        writeResolutions({
+          bundleId: result.bundle.id,
+          under: flags.under ?? null,
+          all: result.decisions.all,
+          byNode: result.decisions.byNode,
+        }),
+      )
+      saved = here(target)
+      this.say(`  wrote    ${saved}`)
+    }
+
+    if (result.clean) this.say('\nNothing outstanding: this bundle would import cleanly.')
+    else {
+      this.say(
+        `\n${result.check.outstanding.length} finding(s) would stop an import. Resolve them, or pass --resolve.`,
+      )
+      this.outcome = 'blocked'
+    }
+    return {
+      bundle: result.bundle,
+      under: result.under ?? null,
+      counts: result.check.counts,
+      findings: findingsOf(result.check.findings),
+      outstanding: result.check.outstanding.length,
+      clean: result.clean,
+      wouldNotPublish: result.publishRefusals,
+      saved,
+    }
+  }
+}

package/src/commands/content/export.ts

@@ -0,0 +1,116 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { packageNameFor } from '@crombolo/transfer'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { counted, describeBytes, describeContentMode, here } from '../../support/describe.ts'
+import { contentFlags, contentMode, many } from '../../support/flags.ts'
+import { passphraseToSeal } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class ContentExport extends BaseCommand {
+  static override summary =
+    'write a subtree as a private bundle package, to move to another environment'
+  static override description = [
+    'The subtree, its dependencies, and what the destination must already have.',
+    'Names and the tree only, unless --include-content: values, media files (--with-blobs) and protected-page usernames, encrypted under a passphrase (asked for, or CROMBOLO_BUNDLE_PASSPHRASE). --allow-content-unencrypted writes them readable. --with-members and --with-users add people, always encrypted.',
+  ].join('\n\n')
+  static override examples = ['<%= config.bin %> content export --root /blog --out ./bundles/blog']
+  static override flags = {
+    root: many('the subtree to export; repeatable', '<path|uuid>'),
+    out: Flags.string({
+      summary: 'the directory to write the package to',
+      helpValue: '<dir>',
+      required: true,
+    }),
+    only: Flags.boolean({ summary: 'the roots alone, not what is below them' }),
+    drafts: Flags.boolean({ summary: 'drafts, not only what is published' }),
+    'with-blueprints': Flags.boolean({ summary: 'the blueprints of its types' }),
+    'with-blobs': Flags.boolean({ summary: 'with --include-content: the media files' }),
+    'with-members': Flags.boolean({ summary: 'members, encrypted' }),
+    'with-users': Flags.boolean({ summary: 'back-office users, encrypted' }),
+    name: Flags.string({ summary: "the package's npm name", helpValue: '<npm name>' }),
+    'package-version': Flags.string({ summary: "the package's version", helpValue: '<version>' }),
+    ...contentFlags,
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'out', type: 'string' },
+      { name: 'package', type: 'object' },
+      { name: 'bundleId', type: 'string' },
+      { name: 'counts', type: 'object' },
+      { name: 'expected', type: 'array', items: { type: 'object' } },
+      { name: 'content', type: 'string', enum: ['omitted', 'sealed', 'open'] },
+      { name: 'blobs', type: 'object' },
+    ],
+    errors: ['usage', 'not_found', 'refused', 'auth'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(ContentExport)
+    if (flags.root.length === 0) this.fail('usage', 'content export needs --root <path|uuid>.')
+    const content = contentMode(this, flags)
+    const result = await ops.contentExport(await siteConfig(), {
+      content,
+      roots: flags.root,
+      only: flags.only,
+      drafts: flags.drafts,
+      withBlobs: flags['with-blobs'],
+      withMembers: flags['with-members'],
+      withUsers: flags['with-users'],
+      passphrase:
+        content === 'sealed' || flags['with-members'] || flags['with-users']
+          ? await passphraseToSeal()
+          : undefined,
+      withBlueprints: flags['with-blueprints'],
+      // An export is a private package; without --name it is named for its directory.
+      package: {
+        name: flags.name ?? packageNameFor(basename(resolve(flags.out))),
+        version: flags['package-version'],
+      },
+    })
+    for (const key of result.blobs.missing)
+      this.warning(`  missing  ${key} is not in this environment's media store`)
+    for (const file of result.files) {
+      const target = join(flags.out, file.path)
+      await mkdir(join(target, '..'), { recursive: true })
+      await writeFile(target, file.bytes ?? (file.text as string))
+    }
+    if (Object.keys(result.counts).length === 0)
+      this.fail(
+        'not_found',
+        'Nothing was selected, so the package is empty.',
+        'Check the --root values.',
+      )
+    this.say(`  wrote    ${here(flags.out)}`)
+    this.say(`  package  ${result.package.name}@${result.package.version} (private)`)
+    this.say(
+      `  bundle   ${result.bundleId} (${result.snapshot}): ${counted(result.counts, 'nothing selected')}`,
+    )
+    if (result.expected.length > 0) {
+      this.say(`  expects  ${result.expected.length} node(s) to exist at the destination:`)
+      for (const e of result.expected) this.say(`    ${e.key}  ${e.name}  (${e.why})`)
+    }
+    describeContentMode(this, result.content, result.people)
+    if (result.blobs.carried > 0)
+      this.say(
+        `  blobs    ${result.blobs.carried} media file(s), ${describeBytes(result.blobs.bytes)}`,
+      )
+    else if (result.blobs.notCarried > 0)
+      this.say(
+        `  blobs    ${result.blobs.notCarried} media file(s) are not carried — pass --with-blobs to include them`,
+      )
+    return {
+      out: here(flags.out),
+      package: result.package,
+      bundleId: result.bundleId,
+      counts: result.counts,
+      expected: result.expected,
+      content: result.content,
+      blobs: result.blobs,
+    }
+  }
+}

package/src/commands/content/import.ts

@@ -0,0 +1,109 @@
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import {
+  describeBundle,
+  describePlaced,
+  findingsOf,
+  here,
+  printTransferFindings,
+} from '../../support/describe.ts'
+import { backupTaken, transferFlags, transferInput } from '../../support/flags.ts'
+import { passphraseToOpen } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class ContentImport extends BaseCommand {
+  static override summary = "re-check, back up, then apply a bundle's content"
+  static override description = [
+    'Documents and elements arrive as drafts, media is live. One transaction, so a failure leaves nothing behind.',
+    'A bundle carrying its own schema and views installs into a site that has neither. `content revert <run>` puts it back.',
+  ].join('\n\n')
+  static override aliases = ['bundle:install']
+  static override args = {
+    bundle: Args.string({
+      required: true,
+      description: 'a package directory, or the name of a bundle this site depends on',
+    }),
+  }
+  static override flags = {
+    ...transferFlags,
+    label: Flags.string({ summary: 'a label for the run', helpValue: '<text>' }),
+    'backup-taken': backupTaken,
+  }
+  static override audit = { category: 'content', action: 'Import', entityType: 'Bundle' } as const
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'runId', type: 'string' },
+      { name: 'bundle', type: 'object' },
+      { name: 'counts', type: 'object' },
+      { name: 'backup', type: 'string', nullable: true },
+      { name: 'published', type: 'integer' },
+      { name: 'notPublished', type: 'array', items: { type: 'object' } },
+    ],
+    errors: ['refused', 'auth'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(ContentImport)
+    const config = await siteConfig()
+    const result = await ops.contentImport(config, {
+      ...transferInput(args.bundle, flags),
+      passphrase: await passphraseToOpen(args.bundle, config),
+      publish: flags.publish,
+      label: flags.label,
+      backupTaken: flags['backup-taken'],
+    })
+    for (const problem of result.problems) this.warning(`  ${problem}`)
+    if (result.backup.path) this.progress(`  backup   ${result.backup.path}`)
+    describeBundle(this, result.bundle)
+
+    if (!result.runId) {
+      printTransferFindings(this, result.check)
+      // Staged, then applied in one transaction: a refusal leaves nothing behind.
+      this.fail(
+        'refused',
+        `import refused: ${result.check.outstanding.length || result.problems.length} finding(s) outstanding. Nothing was written.`,
+        'Resolve them, or pass --resolve.',
+        findingsOf(result.check.outstanding),
+      )
+    }
+
+    const c = result.check.counts
+    this.say(`  run      ${result.runId}`)
+    this.say(
+      `  applied  ${c.create} created, ${c.update} updated, ${c.unchanged} unchanged, ${c.skip} skipped`,
+    )
+    const placed = describePlaced(result.blobs)
+    if (placed) this.say(`  blobs    ${placed}`)
+    if (result.sections) {
+      this.say(
+        `  files    ${result.sections.written.length} written` +
+          (result.sections.replaced.length > 0
+            ? `, ${result.sections.replaced.length} replaced`
+            : ''),
+      )
+      if (result.sections.schema) this.say(`  schema   ${result.sections.schema.action}`)
+      if (result.sections.dictionary)
+        this.say(`  dict     ${result.sections.dictionary.imported} imported`)
+      // Named, because this is what makes reverting the install possible.
+      if (result.replacedFilesKept)
+        this.say(`  kept     ${here(result.replacedFilesKept)}  (the files it replaced)`)
+    }
+    if (result.published > 0) this.say(`  published ${result.published} node(s)`)
+    for (const failure of result.publishFailures)
+      this.warning(`  not published  ${failure.key}: ${failure.reason}`)
+    for (const finding of result.check.findings.filter((f) => f.kind === 'auto'))
+      this.say(`  [auto    ] ${finding.message}`)
+    this.say(`\nDone. \`crombolo content revert ${result.runId}\` puts it back.`)
+    return {
+      runId: result.runId,
+      bundle: result.bundle,
+      counts: c,
+      backup: result.backup.path ?? null,
+      published: result.published,
+      notPublished: result.publishFailures,
+    }
+  }
+}

package/src/commands/content/publish.ts

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../base.ts'
+import { publishArgs, publishFlags, publishPages, publishSpec } from '../../support/publish.ts'
+
+export default class ContentPublish extends BaseCommand {
+  static override summary = 'take a page live; --descendants for the branch below it'
+  static override description = '--culture per culture; --at and --until schedule it instead.'
+  static override args = publishArgs
+  static override flags = publishFlags
+  static override audit = {
+    category: 'content',
+    action: 'Publish',
+    entityType: 'Document',
+  } as const
+  static override spec = publishSpec
+
+  async run() {
+    const { args, flags } = await this.parse(ContentPublish)
+    this.auditKey = args.page
+    return publishPages(this, true, args.page, flags)
+  }
+}