@crombolo/cli 0.15.0 → 0.16.0

package/src/commands/media/import.ts

@@ -0,0 +1,175 @@
+import { readdirSync, statSync } from 'node:fs'
+import { extname, join, relative, resolve } from 'node:path'
+import { appendCacheInstruction, type NodeRow } from '@crombolo/data'
+import { bootstrapDatabase, mediaFileOf } from '@crombolo/server'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { dryRun } from '../../support/flags.ts'
+import { childrenByName, mediaParent, openMedia, sha256 } from '../../support/media-tree.ts'
+import { siteConfig } from '../../support/site.ts'
+
+interface Outcome {
+  path: string
+  action: 'created' | 'folder' | 'skipped' | 'differs' | 'unsupported'
+  type?: string
+}
+
+/**
+ * A folder of files into the media library: a media folder for each directory,
+ * an item for each file, typed by its extension as an upload is. A file already
+ * there with the same bytes is skipped, so an import that stopped part-way runs
+ * again from where it got to.
+ */
+export default class MediaImport extends BaseCommand {
+  static override summary = 'import a folder of files into the media library, keeping its folders'
+  static override description = [
+    'Each directory becomes a media folder and each file a media item, typed by its extension as an upload is. Files no media type takes are reported and left.',
+    'Run it again after a stop: a file already imported with the same bytes is skipped, and one whose bytes differ is reported and left alone.',
+  ].join('\n\n')
+  static override examples = ['<%= config.bin %> media import ./photos --under /Gallery --dry-run']
+  static override args = {
+    dir: Args.string({ required: true, description: 'the folder to import' }),
+  }
+  static override flags = {
+    under: Flags.string({
+      summary: 'the media folder to import into; the root when not given',
+      helpValue: '<path|uuid>',
+    }),
+    'dry-run': dryRun,
+  }
+  static override audit = { category: 'media', action: 'Import', entityType: 'Media' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'bounded',
+    outputFields: [
+      { name: 'created', type: 'integer' },
+      { name: 'folders', type: 'integer' },
+      { name: 'skipped', type: 'integer' },
+      { name: 'differs', type: 'array', items: { type: 'string' } },
+      { name: 'unsupported', type: 'array', items: { type: 'string' } },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'io'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(MediaImport)
+    const root = resolve(args.dir)
+    if (!statSync(root, { throwIfNoEntry: false })?.isDirectory())
+      this.fail('not_found', `${args.dir} is not a folder.`)
+    const config = await siteConfig()
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const tree = await openMedia(db, config)
+      const parent = await mediaParent(db, flags.under)
+      const folderTypes = await tree.port.folderTypes()
+      const folderType = folderTypes.find((t) => t.name === 'Folder') ?? folderTypes[0]
+      if (!folderType) this.fail('refused', 'This site has no media folder type to import into.')
+      const typeFor = new Map<string, { key: string; name: string } | undefined>()
+      const outcomes: Outcome[] = []
+      const dry = flags['dry-run']
+
+      const walk = async (dir: string, into: NodeRow | null, intoKey: string | null) => {
+        const existing =
+          into || !dry ? await childrenByName(tree, into) : new Map<string, NodeRow>()
+        for (const name of readdirSync(dir).sort()) {
+          if (name.startsWith('.')) continue
+          const path = join(dir, name)
+          const shown = relative(root, path)
+          if (statSync(path).isDirectory()) {
+            let folder = existing.get(name) ?? null
+            if (!folder) {
+              outcomes.push({ path: shown, action: 'folder' })
+              if (!dry) {
+                const key = crypto.randomUUID()
+                await tree.repo.create({
+                  key,
+                  contentTypeKey: folderType.key,
+                  componentKey: null,
+                  parentKey: intoKey,
+                  values: [],
+                  variants: [{ culture: null, segment: null, name }],
+                })
+                folder = (await tree.nodes.byKey(key)) ?? null
+              }
+            }
+            await walk(path, folder, folder?.key ?? null)
+            continue
+          }
+          const extension = extname(name).slice(1).toLowerCase()
+          if (!typeFor.has(extension)) {
+            const types = await tree.port.typesForExtension(extension)
+            typeFor.set(extension, types.find((t) => t.matched) ?? types[0])
+          }
+          const type = typeFor.get(extension)
+          if (!type) {
+            outcomes.push({ path: shown, action: 'unsupported' })
+            continue
+          }
+          const bytes = await Bun.file(path).bytes()
+          const there = existing.get(name)
+          if (there) {
+            const media = await tree.repo.byKey(there.key)
+            const src = media ? mediaFileOf(media) : null
+            const stored = src ? await tree.files.open(src) : undefined
+            const same = stored ? sha256(await stored.bytes()) === sha256(bytes) : false
+            outcomes.push({ path: shown, action: same ? 'skipped' : 'differs', type: type.name })
+            continue
+          }
+          outcomes.push({ path: shown, action: 'created', type: type.name })
+          if (dry) continue
+          const upload = crypto.randomUUID()
+          await tree.files.saveTemporary(upload, new File([bytes], name))
+          await tree.repo.create({
+            key: crypto.randomUUID(),
+            contentTypeKey: type.key,
+            componentKey: null,
+            parentKey: intoKey,
+            values: [
+              {
+                alias: 'umbracoFile',
+                culture: null,
+                segment: null,
+                value: { temporaryFileId: upload },
+              },
+            ],
+            variants: [{ culture: null, segment: null, name }],
+          })
+          const made = outcomes.filter((o) => o.action === 'created').length
+          if (made % 25 === 0) this.progress(`  imported ${made}`)
+        }
+      }
+      await walk(root, parent, parent?.key ?? null)
+
+      const count = (action: Outcome['action']) => outcomes.filter((o) => o.action === action)
+      const verb = dry ? 'would create' : 'created'
+      for (const o of outcomes.filter((o) => o.action !== 'skipped'))
+        this.say(
+          `  ${(o.action === 'created' ? verb : o.action === 'folder' ? `${verb} folder` : o.action).padEnd(20)} ${o.path}${o.type ? `  (${o.type})` : ''}`,
+        )
+      this.say(
+        `\n  ${count('created').length} file(s) and ${count('folder').length} folder(s) ${dry ? 'to create' : 'created'}, ${count('skipped').length} already here` +
+          `${count('differs').length > 0 ? `, ${count('differs').length} differ` : ''}${count('unsupported').length > 0 ? `, ${count('unsupported').length} no media type takes` : ''}`,
+      )
+      const changed = !dry && (count('created').length > 0 || count('folder').length > 0)
+      if (dry) this.changedNothing = true
+      // Once for the run: the nodes refresh what shows media.
+      if (changed)
+        await appendCacheInstruction(db, {
+          kind: 'content',
+          payload: { media: true },
+          by: `cli:${config.nodeId}`,
+        })
+      return {
+        created: count('created').length,
+        folders: count('folder').length,
+        skipped: count('skipped').length,
+        differs: count('differs').map((o) => o.path),
+        unsupported: count('unsupported').map((o) => o.path),
+        changed,
+      }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/recycle-bin/empty.ts

@@ -0,0 +1,157 @@
+import { ObjectTypes } from '@crombolo/core'
+import {
+  appendCacheInstruction,
+  currentSchemaState,
+  DocumentRepository,
+  type NodeRow,
+} from '@crombolo/data'
+import { bootstrapDatabase, MediaFileStore, mediaFileOf, mediaStoreFor } from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { dryRun } from '../../support/flags.ts'
+import { confirm } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** Deletes for good what is in the recycle bin: pages, media and their files. */
+export default class RecycleBinEmpty extends BaseCommand {
+  static override summary = 'delete what is in the recycle bin, for good'
+  static override description = [
+    'Pages and media both, unless --content or --media names one. --older-than keeps what was trashed recently; an item trashed before crombolo recorded when is kept by it too, and counted.',
+    'Asks first, unless --yes; --dry-run lists what would go.',
+  ].join('\n\n')
+  static override flags = {
+    content: Flags.boolean({ summary: 'only pages', exclusive: ['media'] }),
+    media: Flags.boolean({ summary: 'only media, with their files', exclusive: ['content'] }),
+    'older-than': Flags.integer({
+      summary: 'only what was trashed more than this many days ago',
+      min: 0,
+    }),
+    yes: Flags.boolean({ summary: "don't ask" }),
+    'dry-run': dryRun,
+  }
+  static override audit = {
+    category: 'content',
+    action: 'EmptyRecycleBin',
+    entityType: 'Document',
+  } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'bounded',
+    confirmationBypassArg: '--yes',
+    outputFields: [
+      {
+        name: 'items',
+        type: 'array',
+        items: {
+          type: 'object',
+          fields: [
+            { name: 'key', type: 'string' },
+            { name: 'name', type: 'string' },
+            { name: 'kind', type: 'string', enum: ['content', 'media'] },
+            { name: 'trashedAt', type: 'string', nullable: true },
+          ],
+        },
+      },
+      { name: 'kept', type: 'integer', description: 'trashed too recently, or at an unknown time' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['confirmation_required', 'refused'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(RecycleBinEmpty)
+    const config = await siteConfig()
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const kinds = (['content', 'media'] as const).filter(
+        (kind) => (!flags.content && !flags.media) || flags[kind],
+      )
+      const files = new MediaFileStore(await mediaStoreFor(config))
+      const state = await currentSchemaState(db)
+      const cutoff =
+        flags['older-than'] === undefined
+          ? undefined
+          : Date.now() - flags['older-than'] * 86_400_000
+      const chosen: Array<{
+        repo: DocumentRepository
+        node: NodeRow
+        kind: 'content' | 'media'
+        trashedAt: Date | undefined
+      }> = []
+      let kept = 0
+      for (const kind of kinds) {
+        const repo = new DocumentRepository(db, {
+          kind: kind === 'media' ? 'media' : 'document',
+          nodeState: { version: state.version, revision: state.revision },
+          nodeId: `cli:${config.nodeId}`,
+        })
+        const roots = await repo.trashedRoots()
+        const dates = await repo.trashedDates(roots.map((node) => node.id))
+        for (const node of roots) {
+          const trashedAt = dates.get(node.id)
+          if (cutoff !== undefined && (!trashedAt || trashedAt.getTime() > cutoff)) {
+            kept += 1
+            continue
+          }
+          chosen.push({ repo, node, kind, trashedAt })
+        }
+      }
+      const items = chosen.map(({ node, kind, trashedAt }) => ({
+        key: node.key,
+        name: node.text ?? node.key,
+        kind,
+        trashedAt: trashedAt?.toISOString() ?? null,
+      }))
+      for (const item of items)
+        this.say(
+          `  ${flags['dry-run'] ? 'would delete' : 'deletes'}  ${item.kind.padEnd(7)} ${item.name}`,
+        )
+      if (kept > 0)
+        this.say(`  keeps    ${kept} item(s) trashed too recently, or before the date was recorded`)
+      if (items.length === 0) {
+        this.say('  The recycle bin has nothing to delete.')
+        this.changedNothing = true
+        return { items, kept, changed: false }
+      }
+      if (flags['dry-run']) {
+        this.changedNothing = true
+        return { items, kept, changed: false }
+      }
+      if (!flags.yes)
+        await confirm(
+          `  Delete ${items.length} item(s) and everything below them, for good? [y/N]`,
+          {
+            bypass: '--yes',
+          },
+        )
+      let mediaChanged = false
+      for (const { repo, node, kind } of chosen) {
+        // A media item's file goes with it, as emptying the bin in the back office does.
+        const paths: string[] = []
+        if (kind === 'media') {
+          const rows = await db.query<{ unique_id: string }>(
+            'SELECT unique_id FROM node WHERE (id = ? OR path LIKE ?) AND node_object_type = ?',
+            [node.id, `${node.path},%`, ObjectTypes.Media],
+          )
+          for (const row of rows) {
+            const media = await repo.byKey(String(row.unique_id))
+            const file = media ? mediaFileOf(media) : null
+            if (file) paths.push(file)
+          }
+        }
+        if (await repo.delete(node.key)) for (const path of paths) await files.remove(path)
+        if (kind === 'media') mediaChanged = true
+      }
+      // One instruction for the run, as a node's own empty-bin does.
+      await appendCacheInstruction(db, {
+        kind: 'content',
+        payload: mediaChanged ? { media: true } : { recycleBin: true },
+        by: `cli:${config.nodeId}`,
+      })
+      this.say(`  deleted  ${items.length} item(s)`)
+      return { items, kept, changed: true }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/users/disable.ts

@@ -0,0 +1,54 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import {
+  checkStatus,
+  describeUser,
+  OBSERVER,
+  OPERATOR,
+  openPeople,
+  userNamed,
+} from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersDisable extends BaseCommand {
+  static override summary = 'stop a user signing in, and end their sessions'
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = { category: 'user', action: 'Disable', entityType: 'User' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'state', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersDisable)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const snapshot = async () => {
+        const found = await people.users.get(OBSERVER, user.key)
+        return found.status === 'Success'
+          ? { state: found.value.state, failed: found.value.failedLoginAttempts }
+          : { state: 'unknown', failed: 0 }
+      }
+      const before = await snapshot()
+      checkStatus(await people.users.setApproved(OPERATOR, [user.key], false))
+      const after = await snapshot()
+      const state = after.state
+      const changed = before.state !== after.state || before.failed !== after.failed
+      this.say(`  disabled  ${describeUser(user)}${changed ? '' : ' (no change)'}`)
+      return { id: user.key, email: user.email, state, changed }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/enable.ts

@@ -0,0 +1,54 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import {
+  checkStatus,
+  describeUser,
+  OBSERVER,
+  OPERATOR,
+  openPeople,
+  userNamed,
+} from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersEnable extends BaseCommand {
+  static override summary = 'let a disabled user sign in again'
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = { category: 'user', action: 'Enable', entityType: 'User' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'state', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersEnable)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const snapshot = async () => {
+        const found = await people.users.get(OBSERVER, user.key)
+        return found.status === 'Success'
+          ? { state: found.value.state, failed: found.value.failedLoginAttempts }
+          : { state: 'unknown', failed: 0 }
+      }
+      const before = await snapshot()
+      checkStatus(await people.users.setApproved(OPERATOR, [user.key], true))
+      const after = await snapshot()
+      const state = after.state
+      const changed = before.state !== after.state || before.failed !== after.failed
+      this.say(`  enabled   ${describeUser(user)}${changed ? '' : ' (no change)'}`)
+      return { id: user.key, email: user.email, state, changed }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/invite.ts

@@ -0,0 +1,82 @@
+import { UserGroupRepository } from '@crombolo/data'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { many } from '../../support/flags.ts'
+import { checkStatus, OPERATOR, openPeople } from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersInvite extends BaseCommand {
+  static override summary = 'create a user and print the link they set their password with'
+  static override description =
+    'The link is printed rather than e-mailed, so it works on a site with no e-mail delivery. It is used once, and expires as an invitation does.'
+  static override examples = [
+    '<%= config.bin %> users invite editor@example.com --group editor --name "Ada Lovelace"',
+  ]
+  static override args = {
+    email: Args.string({ required: true, description: 'their e-mail address' }),
+  }
+  static override flags = {
+    group: many('a user group, by alias; repeatable', '<alias>'),
+    name: Flags.string({ summary: 'their name; the address when not given', helpValue: '<name>' }),
+  }
+  static override audit = { category: 'user', action: 'Invite', entityType: 'User' } as const
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'groups', type: 'array', items: { type: 'string' } },
+      { name: 'link', type: 'string' },
+    ],
+    errors: ['usage', 'not_found', 'conflict', 'refused'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(UsersInvite)
+    if (flags.group.length === 0)
+      this.fail('usage', 'An invited user needs at least one group.', 'Pass --group <alias>.')
+    const config = await siteConfig()
+    const people = await openPeople(config)
+    try {
+      const repository = new UserGroupRepository(people.db)
+      const groupKeys: string[] = []
+      for (const alias of flags.group) {
+        const group = await repository.byAlias(alias)
+        if (!group)
+          this.fail(
+            'not_found',
+            `There is no user group "${alias}".`,
+            `It has: ${(await repository.all()).map((g) => g.alias).join(', ')}.`,
+          )
+        groupKeys.push(group.key)
+      }
+      const result = await people.users.invite(
+        OPERATOR,
+        {
+          kind: 'Default',
+          email: args.email,
+          userName: args.email,
+          name: flags.name ?? args.email,
+          groupKeys,
+        },
+        null,
+      )
+      checkStatus(result.status)
+      const id = result.status === 'Success' ? result.value : ''
+      this.auditKey = id
+      const captured = people.lastLink() ?? ''
+      // Without an application URL the link is relative: it is the path on the site's own address.
+      const link = config.applicationUrl ? captured : captured.replace(/^[^/]*/, '')
+      this.say(`  invited  ${args.email} to ${flags.group.join(', ')}`)
+      this.say(link)
+      if (!config.applicationUrl)
+        this.warning(
+          '  note     the link is a path on the site: set CROMBOLO_APPLICATION_URL to print the whole address',
+        )
+      return { id, email: args.email, groups: flags.group, link }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/list.ts

@@ -0,0 +1,62 @@
+import { UserGroupRepository } from '@crombolo/data'
+import { BaseCommand } from '../../base.ts'
+import { page, pageFlags, pagination } from '../../support/flags.ts'
+import { OBSERVER, openPeople } from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersList extends BaseCommand {
+  static override summary = 'the back-office users: who, their groups, their state and last sign-in'
+  static override flags = { ...pageFlags(50) }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'unbounded',
+    pagination,
+    fieldsArg: '--fields',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'name', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'userName', type: 'string' },
+      { name: 'kind', type: 'string', enum: ['Default', 'Api'] },
+      { name: 'state', type: 'string' },
+      { name: 'groups', type: 'array', items: { type: 'string' } },
+      { name: 'failedLoginAttempts', type: 'integer' },
+      { name: 'lastLoginDate', type: 'string', nullable: true },
+    ],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(UsersList)
+    const people = await openPeople(await siteConfig())
+    try {
+      const found = await people.users.list(OBSERVER, flags.offset, flags.limit)
+      const groups = new Map(
+        (await new UserGroupRepository(people.db).all()).map((g) => [g.key, g.alias]),
+      )
+      const items = found.items.map((user) => ({
+        id: user.id,
+        name: user.name,
+        email: user.email,
+        userName: user.userName,
+        kind: user.kind,
+        state: user.state,
+        groups: user.userGroupIds.map((g) => groups.get(g.id) ?? g.id),
+        failedLoginAttempts: user.failedLoginAttempts,
+        lastLoginDate: user.lastLoginDate ?? null,
+      }))
+      if (items.length === 0) this.say('No users.')
+      for (const user of items)
+        this.say(
+          `  ${user.state.padEnd(9)} ${user.name} <${user.email || user.userName}>  ${user.groups.join(', ') || 'no groups'}` +
+            `${user.lastLoginDate ? `  last in ${user.lastLoginDate}` : '  never signed in'}`,
+        )
+      if (flags.offset + items.length < found.total)
+        this.say(
+          `  … ${found.total - flags.offset - items.length} more: --offset ${flags.offset + items.length}`,
+        )
+      return page(items, found.total, flags)
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/reset-2fa.ts

@@ -0,0 +1,48 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeUser, openPeople, userNamed } from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** For someone who has lost their authenticator: their next sign-in enrols again. */
+export default class UsersReset2fa extends BaseCommand {
+  static override summary =
+    "remove a user's second factors, so their next sign-in sets one up again"
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = {
+    category: 'user',
+    action: 'ResetTwoFactor',
+    entityType: 'User',
+  } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'removed', type: 'array', items: { type: 'string' } },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersReset2fa)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const removed = await people.twoFactor.providers(user.key)
+      await people.twoFactor.reset(user.key)
+      this.say(
+        removed.length > 0
+          ? `  removed  ${removed.join(', ')} from ${describeUser(user)}`
+          : `  ${describeUser(user)} has no second factor; nothing changed`,
+      )
+      return { id: user.key, email: user.email, removed, changed: removed.length > 0 }
+    } finally {
+      await people.db.close()
+    }
+  }
+}