@crombolo/cli 0.14.1 → 0.15.0

package/src/commands/status.ts

@@ -0,0 +1,103 @@
+import { siteStatus } from '@crombolo/server'
+import { BaseCommand } from '../base.ts'
+import { siteConfig } from '../support/site.ts'
+
+/**
+ * What this environment resolved to, and what is wrong with it, without
+ * starting it. Read-only by construction — it opens the database rather than
+ * bootstrapping it, so asking a production node how it is never migrates it.
+ */
+export default class Status extends BaseCommand {
+  static override summary =
+    'what this environment is, and what is wrong with it, without starting it'
+  static override description =
+    'Exits 20 when something would stop the site working; the problems are in the output.'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'site', type: 'object' },
+      { name: 'database', type: 'object' },
+      { name: 'schema', type: 'object' },
+      { name: 'framework', type: 'object' },
+      { name: 'bundles', type: 'object' },
+      { name: 'content', type: 'object' },
+      { name: 'findings', type: 'object' },
+      { name: 'email', type: 'object' },
+      { name: 'versions', type: 'object' },
+      { name: 'problems', type: 'array', items: { type: 'string' } },
+    ],
+    outcomes: ['problems_found'],
+  } as const
+
+  async run() {
+    await this.parse(Status)
+    const report = await siteStatus(await siteConfig())
+    if (report.problems.length > 0) this.outcome = 'problems_found'
+
+    const line = (label: string, value: string) => this.say(`  ${label.padEnd(10)} ${value}`)
+    line('site', `${report.site.name}${report.site.dir ? `   ${report.site.dir}` : ''}`)
+    line('components', `${report.site.components}   snapshots in ${report.site.componentsCache}`)
+    line(
+      'database',
+      `${report.database.description}   ${
+        report.database.reachable
+          ? report.database.installed
+            ? 'reachable'
+            : 'reachable, not installed'
+          : 'unreachable'
+      }`,
+    )
+    const files = report.schema.files ?? 'none'
+    const database = report.schema.database
+      ? `${report.schema.database.version}+${report.schema.database.revision}`
+      : 'not installed'
+    line(
+      'schema',
+      `files ${files}  database ${database}   ${
+        !report.database.installed
+          ? 'nothing applied yet'
+          : report.schema.compatibilityMode
+            ? 'compatibility mode'
+            : report.schema.pending
+              ? 'a deploy is pending'
+              : 'up to date'
+      }`,
+    )
+    const pending = report.framework.pending
+    line(
+      'framework',
+      pending.length === 0
+        ? 'no migration pending'
+        : // The whole list is a wall of names on a fresh database; `upgrade --plan`
+          // is where somebody goes when they want them.
+          pending.length > 3
+          ? `${pending.length} pending (\`crombolo upgrade --plan\` lists them)`
+          : `${pending.length} pending: ${pending.join(', ')}`,
+    )
+    line(
+      'content',
+      `${report.content.documents} document(s), ${report.content.media} media, ${report.content.elements} element(s)` +
+        `${report.content.lastImport ? `; last import ${report.content.lastImport}` : ''}`,
+    )
+    line(
+      'email',
+      report.email.available
+        ? (report.email.description ?? 'configured')
+        : report.email.provider === 'log'
+          ? 'console only, nothing is sent'
+          : `none — ${report.email.affects.join(', ')} unavailable`,
+    )
+    line(
+      'findings',
+      `${report.findings.blocking} blocking, ${report.findings.person} need a person, ` +
+        `${report.findings.auto} automatic, ${report.findings.resolved} resolved`,
+    )
+    line(
+      'versions',
+      `crombolo ${report.versions.crombolo}${report.versions.backoffice ? `, backoffice ${report.versions.backoffice}` : ''}, bun ${report.versions.bun}`,
+    )
+    for (const problem of report.problems) this.say(`\n  ⚠ ${problem}`)
+    return report
+  }
+}

package/src/commands/types/add-property.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  addProperty,
+  BUILTIN_DATA_TYPES,
+  fileNameFor,
+  type SchemaContentType,
+  type SchemaTypeKind,
+  TYPE_KIND_FILES,
+  writeContentType,
+} from '@crombolo/schema'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeSync, here } from '../../support/describe.ts'
+import { dryRun } from '../../support/flags.ts'
+import { siteConfig } from '../../support/site.ts'
+import { applySchema, loadTypes, needSchemaDir, refuseProblems } from '../../support/types.ts'
+
+/** The repetitive edit: one property appended to a type, and applied. */
+export default class TypesAddProperty extends BaseCommand {
+  static override summary = 'append a property to a type, and apply it'
+  static override description =
+    'The whole file is re-emitted from the model, so comments in it are not kept; --dry-run prints the file instead.'
+  static override examples = [
+    '<%= config.bin %> types add-property article summary --type textarea --mandatory',
+  ]
+  static override aliases = ['schema:add-property']
+  static override deprecateAliases = true
+  static override args = {
+    type: Args.string({ required: true, description: "the type's alias" }),
+    alias: Args.string({ required: true, description: "the property's alias" }),
+  }
+  static override flags = {
+    type: Flags.string({ summary: 'the data type', helpValue: '<data type>', required: true }),
+    name: Flags.string({ summary: "the property's name", helpValue: '<name>' }),
+    description: Flags.string({ summary: "the property's description", helpValue: '<text>' }),
+    mandatory: Flags.boolean({ summary: 'an editor must fill it in' }),
+    tab: Flags.string({ summary: 'the tab it goes in', helpValue: '<tab>' }),
+    'dry-run': dryRun,
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'file', type: 'string' },
+      { name: 'property', type: 'object' },
+      { name: 'tab', type: 'string' },
+      { name: 'text', type: 'string', nullable: true },
+      { name: 'schema', type: 'string', nullable: true },
+    ],
+    errors: ['not_found', 'conflict', 'refused'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(TypesAddProperty)
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const loaded = loadTypes(config)
+    refuseProblems(loaded.problems)
+    const kinds: Array<[SchemaTypeKind, SchemaContentType[]]> = [
+      ['document', loaded.set.contentTypes],
+      ['media', loaded.set.mediaTypes ?? []],
+      ['member', loaded.set.memberTypes ?? []],
+    ]
+    const found = kinds
+      .map(([kind, types]) => ({ kind, type: types.find((t) => t.alias === args.type) }))
+      .find((candidate) => candidate.type)
+    if (!found?.type) this.fail('not_found', `No type "${args.type}" in ${here(config.schemaDir)}.`)
+
+    const known = new Set([
+      ...BUILTIN_DATA_TYPES.map((d) => d.alias),
+      ...loaded.set.dataTypes.map((d) => d.alias),
+    ])
+    if (!known.has(flags.type))
+      this.fail(
+        'not_found',
+        `No data type "${flags.type}".`,
+        `Built in: ${[...known].sort().join(', ')}`,
+      )
+
+    const result = addProperty(found.type, {
+      alias: args.alias,
+      type: flags.type,
+      name: flags.name,
+      description: flags.description,
+      mandatory: flags.mandatory,
+      tab: flags.tab,
+    })
+    if (!result.ok) this.fail('conflict', result.reason)
+
+    const file = join(config.schemaDir, TYPE_KIND_FILES[found.kind].dir, fileNameFor(args.type))
+    const text = writeContentType(result.type, found.kind)
+    const property = {
+      alias: result.property.alias,
+      name: result.property.name,
+      type: flags.type,
+      mandatory: result.property.mandatory === true,
+    }
+    if (flags['dry-run']) {
+      this.changedNothing = true
+      this.say(text)
+      return { file: here(file), property, tab: result.tab, text, schema: null }
+    }
+    const before = existsSync(file) ? await Bun.file(file).text() : ''
+    await writeFile(file, text)
+    this.say(`  wrote    ${here(file)}`)
+    this.say(
+      `  ${property.alias}  ${property.name} (${flags.type}${property.mandatory ? ', mandatory' : ''}) in tab "${result.tab}"`,
+    )
+    if (/^\s*#/m.test(before))
+      this.say('  note     the file is rewritten canonically, so its comments are not kept')
+    const report = await applySchema(this, config)
+    return { file: here(file), property, tab: result.tab, text: null, schema: describeSync(report) }
+  }
+}

package/src/commands/types/check.ts

@@ -0,0 +1,88 @@
+import { loadValueMigrations, validateSchemaSet } from '@crombolo/schema'
+import { componentAliasesIn, formTypesFor } from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeProblem, findingsOf } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+import { loadTypes, needSchemaDir, staticProblems, upgradeCheck } from '../../support/types.ts'
+
+export default class TypesCheck extends BaseCommand {
+  static override summary = 'validate schema/ and report what a sync would do to this database'
+  static override description =
+    '--static checks the files alone, with no database: the check for a pull request. Exits 20 when it finds problems, 21 when a finding needs a person.'
+  static override aliases = ['schema:check']
+  static override deprecateAliases = true
+  static override flags = {
+    static: Flags.boolean({ summary: 'validate the files only, no database' }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'version', type: 'string' },
+      {
+        name: 'counts',
+        type: 'object',
+        fields: [
+          { name: 'contentTypes', type: 'integer' },
+          { name: 'mediaTypes', type: 'integer' },
+          { name: 'dataTypes', type: 'integer' },
+          { name: 'languages', type: 'integer' },
+        ],
+      },
+      { name: 'problems', type: 'array', items: { type: 'string' } },
+      { name: 'classification', type: 'string', nullable: true },
+      { name: 'findings', type: 'array', items: { type: 'object' } },
+    ],
+    errors: ['not_found'],
+    outcomes: ['problems_found', 'blocked'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(TypesCheck)
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const loaded = loadTypes(config)
+    const counts = {
+      contentTypes: loaded.set.contentTypes.length,
+      mediaTypes: (loaded.set.mediaTypes ?? []).length,
+      dataTypes: loaded.set.dataTypes.length,
+      languages: loaded.set.languages.length,
+    }
+    const result = {
+      version: loaded.set.version,
+      counts,
+      problems: [] as string[],
+      classification: null as string | null,
+      findings: [] as ReturnType<typeof findingsOf>,
+    }
+    result.problems = [
+      ...loaded.problems,
+      ...validateSchemaSet(loaded.set, {
+        componentAliases: componentAliasesIn(config.componentsDir),
+        types: formTypesFor(config),
+      }),
+    ].map(describeProblem)
+    if (result.problems.length > 0) {
+      this.say(`${result.problems.length} problem(s):`)
+      for (const problem of result.problems) this.say(`  ${problem}`)
+      this.outcome = 'problems_found'
+      return result
+    }
+    this.say(
+      `schema ${loaded.set.version}: ${counts.contentTypes} content type(s), ${counts.mediaTypes} media type(s), ${counts.dataTypes} data type(s), ${counts.languages} language(s) — valid`,
+    )
+    if (flags.static) {
+      result.problems = staticProblems(loaded, await loadValueMigrations(config.schemaDir))
+      for (const issue of result.problems) this.say(`  ${issue}`)
+      if (result.problems.length > 0) this.outcome = 'problems_found'
+      return result
+    }
+    // The same check an upgrade runs, over the site's own diff.
+    const report = await upgradeCheck(this, config, {})
+    result.classification = report.classification
+    result.findings = findingsOf(report.findings)
+    if (report.blocking) this.outcome = 'blocked'
+    return result
+  }
+}

package/src/commands/types/export.ts

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs'
+import { exportSchemaSet, writeSchemaFiles } from '@crombolo/schema'
+import { bootstrapDatabase } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+import { loadTypes } from '../../support/types.ts'
+
+export default class TypesExport extends BaseCommand {
+  static override summary = "write the database's definitions as schema/ files"
+  static override aliases = ['schema:export']
+  static override deprecateAliases = true
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'bounded',
+    outputFields: [{ name: 'wrote', type: 'array', items: { type: 'string' } }],
+  } as const
+
+  async run() {
+    await this.parse(TypesExport)
+    const config = await siteConfig()
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const version = existsSync(config.schemaDir) ? loadTypes(config).set.version : '1.0.0'
+      const wrote = writeSchemaFiles(config.schemaDir, await exportSchemaSet(db, version)).map(here)
+      for (const file of wrote) this.say(`  wrote  ${file}`)
+      return { wrote }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/types/new.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  fileNameFor,
+  newType,
+  type SchemaTypeKind,
+  TYPE_KIND_FILES,
+  viewScaffold,
+  writeContentType,
+} from '@crombolo/schema'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeSync, here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+import { applySchema, loadTypes, needSchemaDir } from '../../support/types.ts'
+
+const TYPE_KINDS: Record<string, SchemaTypeKind> = {
+  'content-type': 'document',
+  'media-type': 'media',
+  'member-type': 'member',
+}
+
+/** The file a site would otherwise write from memory, keys and all, and the view it points at. */
+export default class TypesNew extends BaseCommand {
+  static override summary = 'write a type file, with keys, and the view it points at, then apply it'
+  static override examples = ['<%= config.bin %> types new content-type article --at-root']
+  static override aliases = ['schema:new']
+  static override deprecateAliases = true
+  static override args = {
+    kind: Args.string({
+      required: true,
+      options: Object.keys(TYPE_KINDS),
+      description: 'what kind of type',
+    }),
+    alias: Args.string({ required: true, description: "the type's alias" }),
+  }
+  static override flags = {
+    name: Flags.string({ summary: "the type's name", helpValue: '<name>' }),
+    description: Flags.string({ summary: "the type's description", helpValue: '<text>' }),
+    icon: Flags.string({ summary: "the type's icon", helpValue: '<icon>' }),
+    'at-root': Flags.boolean({ summary: 'allow it at the root of the tree' }),
+    element: Flags.boolean({ summary: 'an element type, for blocks' }),
+    tab: Flags.string({ summary: 'the tab its first property goes in', helpValue: '<tab>' }),
+    'no-view': Flags.boolean({ summary: 'no view: a type nothing renders' }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'created', type: 'array', items: { type: 'string' } },
+      { name: 'schema', type: 'string' },
+    ],
+    errors: ['not_found', 'conflict', 'refused'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(TypesNew)
+    const kind = TYPE_KINDS[args.kind] as SchemaTypeKind
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const loaded = loadTypes(config)
+    const existing = [
+      ...loaded.set.contentTypes,
+      ...(loaded.set.mediaTypes ?? []),
+      ...(loaded.set.memberTypes ?? []),
+    ]
+    if (existing.some((type) => type.alias === args.alias))
+      this.fail('conflict', `There is already a type with the alias "${args.alias}".`)
+
+    const element = flags.element
+    const type = newType({
+      alias: args.alias,
+      kind,
+      name: flags.name,
+      description: flags.description,
+      icon: flags.icon,
+      allowAtRoot: flags['at-root'],
+      element,
+      template: !flags['no-view'],
+      // A content type with nothing in it cannot be published, so it starts with
+      // the one property every page has; the other kinds get what they are given.
+      tab: kind === 'document' ? (flags.tab ?? 'Content') : undefined,
+    })
+
+    const created: string[] = []
+    const file = join(config.schemaDir, TYPE_KIND_FILES[kind].dir, fileNameFor(args.alias))
+    await mkdir(join(file, '..'), { recursive: true })
+    await writeFile(file, writeContentType(type, kind))
+    created.push(here(file))
+    this.say(`  created  ${here(file)}`)
+
+    // A type nothing allows cannot be created anywhere, which is a confusing
+    // first five minutes: the editor simply never offers it.
+    if (kind === 'document' && !element && !type.allowAtRoot) {
+      const parents = loaded.set.contentTypes.filter((t) => t.allowChildren.includes(args.alias))
+      if (parents.length === 0)
+        this.say(
+          `  note     nothing allows a "${args.alias}" yet — add it to a parent's allow-children, or pass --at-root`,
+        )
+    }
+
+    if (type.components.length > 0) {
+      const view = join(config.componentsDir, `${args.alias}.tsx`)
+      if (existsSync(view)) this.say(`  exists   ${here(view)}`)
+      else {
+        await mkdir(join(view, '..'), { recursive: true })
+        await writeFile(view, viewScaffold(type))
+        created.push(here(view))
+        this.say(`  created  ${here(view)}`)
+      }
+    }
+    const report = await applySchema(this, config)
+    return { created, schema: describeSync(report) }
+  }
+}

package/src/commands/types/purge.ts

@@ -0,0 +1,65 @@
+import { ContentTypeRepository, recordInLedger } from '@crombolo/data'
+import { backupBefore, bootstrapDatabase } from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { backupTaken } from '../../support/flags.ts'
+import { siteConfig } from '../../support/site.ts'
+import { needSchemaDir } from '../../support/types.ts'
+
+export default class TypesPurge extends BaseCommand {
+  static override summary = 'delete properties retired more than N days ago, with their values'
+  static override aliases = ['schema:purge']
+  static override deprecateAliases = true
+  static override flags = {
+    'older-than': Flags.integer({
+      summary: 'how long, in days, a property must have been retired',
+      required: true,
+      min: 0,
+    }),
+    'backup-taken': backupTaken,
+  }
+  static override audit = { category: 'schema', action: 'Purge', entityType: 'Schema' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'bounded',
+    outputFields: [
+      { name: 'purged', type: 'array', items: { type: 'string' } },
+      { name: 'backup', type: 'string', nullable: true },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(TypesPurge)
+    const days = flags['older-than']
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const backup = await backupBefore(config, {
+      reason: 'purge',
+      backupTaken: flags['backup-taken'],
+    })
+    if (backup.path) this.progress(`  backup   ${backup.path}`)
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const before = new Date(Date.now() - days * 86_400_000)
+      const started = performance.now()
+      const purged = (await new ContentTypeRepository(db).purgeRetired(before)).map(
+        (p) => `${p.type}.${p.alias}`,
+      )
+      for (const name of purged) this.say(`  purged   ${name}`)
+      if (purged.length === 0) this.say(`Nothing retired more than ${days} day(s) ago.`)
+      else
+        await recordInLedger(db, {
+          name: `purge ${purged.join(', ')}`,
+          kind: 'contract',
+          durationMs: Math.round(performance.now() - started),
+          appliedBy: config.nodeId,
+          note: `--older-than ${days}`,
+        })
+      return { purged, backup: backup.path ?? null, changed: purged.length > 0 }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/types/rewrite.ts

@@ -0,0 +1,30 @@
+import { writeSchemaFiles } from '@crombolo/schema'
+import { BaseCommand } from '../../base.ts'
+import { here } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+import { loadTypes, needSchemaDir, refuseProblems } from '../../support/types.ts'
+
+export default class TypesRewrite extends BaseCommand {
+  static override summary = 'rewrite every schema/ file canonically'
+  static override description =
+    'Every file in the canonical layout: a reviewable commit when the vocabulary changes.'
+  static override aliases = ['schema:rewrite', 'upgrade:schema']
+  static override deprecateAliases = true
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'bounded',
+    outputFields: [{ name: 'wrote', type: 'array', items: { type: 'string' } }],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    await this.parse(TypesRewrite)
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const loaded = loadTypes(config)
+    refuseProblems(loaded.problems)
+    const wrote = writeSchemaFiles(config.schemaDir, loaded.set).map(here)
+    for (const file of wrote) this.say(`  wrote  ${file}`)
+    return { wrote }
+  }
+}

package/src/commands/types/sync.ts

@@ -0,0 +1,66 @@
+import { bootstrapDatabase, syncSchemaDirectory } from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeProblem, describeSync, printProblems } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+import { needSchemaDir } from '../../support/types.ts'
+
+export default class TypesSync extends BaseCommand {
+  static override summary = 'apply schema/ to the database'
+  static override aliases = ['schema:sync']
+  static override deprecateAliases = true
+  static override flags = {
+    'force-retire-types': Flags.boolean({
+      summary: 'retire a type the files no longer have even though content uses it',
+    }),
+  }
+  static override audit = { category: 'schema', action: 'Sync', entityType: 'Schema' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      {
+        name: 'action',
+        type: 'string',
+        enum: ['applied', 'would-apply', 'skipped-same', 'skipped-older', 'refused'],
+      },
+      { name: 'changed', type: 'boolean' },
+      { name: 'summary', type: 'string' },
+      { name: 'problems', type: 'array', items: { type: 'string' } },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(TypesSync)
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const report = await syncSchemaDirectory(
+        db,
+        config,
+        { nodeId: config.nodeId, revision: config.schemaRevision },
+        { forceRetireTypes: flags['force-retire-types'] },
+      )
+      if (report.problems.length > 0) printProblems(this, report.problems)
+      const summary = describeSync(report)
+      if (report.action === 'refused')
+        this.fail(
+          'refused',
+          `The schema was not applied: ${summary}.`,
+          undefined,
+          report.problems.map(describeProblem),
+        )
+      this.say(summary)
+      return {
+        action: report.action,
+        changed: report.action === 'applied',
+        summary,
+        problems: report.problems.map(describeProblem),
+      }
+    } finally {
+      await db.close()
+    }
+  }
+}