@crombolo/cli 0.14.4 → 0.16.0

package/src/commands/login.ts

@@ -0,0 +1,38 @@
+import { hostname } from 'node:os'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { signIn } from '../remote/client.ts'
+import { connectRemote, keychain, openInBrowser } from '../support/remote.ts'
+
+export default class Login extends BaseCommand {
+  static override summary = 'sign in to a remote with a code you approve in its back office'
+  static override description =
+    'The sign-in is kept in your keychain. It waits for the approval, printing where to give it; no terminal is needed.'
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override flags = {
+    'no-browser': Flags.boolean({ summary: "don't open the approval page" }),
+  }
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [{ name: 'remote', type: 'string' }],
+    errors: ['not_found', 'auth', 'timeout', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(Login)
+    const { entry, discovery } = await connectRemote(args.remote, undefined)
+    await signIn(discovery, keychain(), {
+      clientName: `crombolo on ${hostname()}`,
+      onCode: (code, url) => {
+        this.progress(`  Approve this sign-in at ${url}`)
+        this.progress(`  and check it shows   ${code}`)
+        openInBrowser(url, flags['no-browser'])
+      },
+    })
+    this.say(`  signed in to ${entry.name}`)
+    return { remote: entry.name }
+  }
+}

package/src/commands/logout.ts

@@ -0,0 +1,36 @@
+import { forgetSignIn, readSignIn } from '@crombolo/server'
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { connectRemote, keychain } from '../support/remote.ts'
+
+export default class Logout extends BaseCommand {
+  static override summary = 'sign out of a remote, here and at the remote'
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'remote', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(Logout)
+    const { entry, discovery } = await connectRemote(args.remote, undefined)
+    const signedIn = await readSignIn(keychain(), discovery.api)
+    // Ended at the remote too, best effort: the device leaves "Signed-in devices".
+    if (signedIn)
+      await fetch(signedIn.tokenUrl.replace(/\/token$/, '/revoke'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ token: signedIn.accessToken }).toString(),
+      }).catch(() => undefined)
+    await forgetSignIn(keychain(), discovery.api)
+    this.say(`  signed out of ${entry.name}`)
+    return { remote: entry.name, changed: signedIn !== undefined }
+  }
+}

package/src/commands/maintenance/pause.ts

@@ -0,0 +1,29 @@
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** The cluster-wide pause on editing that a restore or a swap needs: a database flag every node reads. */
+export default class MaintenancePause extends BaseCommand {
+  static override summary = "refuse every editor's save, on every node, until resumed"
+  static override description = 'Readers are unaffected and no node drains.'
+  static override flags = {
+    reason: Flags.string({ summary: 'what editors are told', helpValue: '<text>' }),
+  }
+  static override audit = { category: 'system', action: 'PauseEditing' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'paused', type: 'boolean' },
+      { name: 'reason', type: 'string', nullable: true },
+    ],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(MaintenancePause)
+    const paused = await ops.pauseEditing(await siteConfig(), { reason: flags.reason })
+    this.say(`Editing paused${paused.reason ? `: ${paused.reason}` : ''}.`)
+    return { paused: true, reason: paused.reason ?? null }
+  }
+}

package/src/commands/maintenance/resume.ts

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class MaintenanceResume extends BaseCommand {
+  static override summary = 'let editors save again'
+  static override audit = { category: 'system', action: 'ResumeEditing' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [{ name: 'paused', type: 'boolean' }],
+  } as const
+
+  async run() {
+    await this.parse(MaintenanceResume)
+    await ops.resumeEditing(await siteConfig())
+    this.say('Editing resumed.')
+    return { paused: false }
+  }
+}

package/src/commands/maintenance/status.ts

@@ -0,0 +1,34 @@
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class MaintenanceStatus extends BaseCommand {
+  static override summary = 'whether editing is paused, by whom and why'
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      {
+        name: 'paused',
+        type: 'object',
+        nullable: true,
+        fields: [
+          { name: 'at', type: 'string' },
+          { name: 'by', type: 'string', nullable: true },
+          { name: 'reason', type: 'string', nullable: true },
+        ],
+      },
+    ],
+  } as const
+
+  async run() {
+    await this.parse(MaintenanceStatus)
+    const paused = await ops.editingPaused(await siteConfig())
+    this.say(
+      paused
+        ? `Editing paused since ${paused.at}${paused.by ? ` by ${paused.by}` : ''}${paused.reason ? `: ${paused.reason}` : ''}.`
+        : 'Editing is not paused.',
+    )
+    return { paused: paused ?? null }
+  }
+}

package/src/commands/media/export.ts

@@ -0,0 +1,91 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { extname, join, resolve } from 'node:path'
+import type { NodeRow } from '@crombolo/data'
+import { bootstrapDatabase, mediaFileOf, safeFileName } from '@crombolo/server'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { here } from '../../support/describe.ts'
+import { childrenByName, mediaParent, openMedia } from '../../support/media-tree.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** The media library, or a folder of it, back out as files in folders. */
+export default class MediaExport extends BaseCommand {
+  static override summary = 'write media files back out as a folder tree'
+  static override examples = ['<%= config.bin %> media export /Gallery --out ./gallery']
+  static override args = {
+    folder: Args.string({
+      description: 'a media folder, as a path or uuid; everything when not given',
+    }),
+  }
+  static override flags = {
+    out: Flags.string({ summary: 'the folder to write into', helpValue: '<dir>', required: true }),
+  }
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'bounded',
+    outputFields: [
+      { name: 'out', type: 'string' },
+      { name: 'files', type: 'integer' },
+      { name: 'bytes', type: 'integer' },
+      {
+        name: 'missing',
+        type: 'array',
+        items: { type: 'string' },
+        description: 'items whose file is not in the store',
+      },
+    ],
+    errors: ['not_found'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(MediaExport)
+    const config = await siteConfig()
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const tree = await openMedia(db, config)
+      const start = await mediaParent(db, args.folder)
+      const out = resolve(flags.out)
+      let files = 0
+      let bytes = 0
+      const missing: string[] = []
+
+      const write = async (node: NodeRow, dir: string) => {
+        const media = await tree.repo.byKey(node.key)
+        const src = media ? mediaFileOf(media) : null
+        const name = node.text ?? node.key
+        if (!src) {
+          // A folder, or an item with nothing uploaded: its children follow.
+          const children = await childrenByName(tree, node)
+          if (children.size === 0 && media) return
+          const into = join(dir, safeFileName(name))
+          for (const child of children.values()) await write(child, into)
+          return
+        }
+        const stored = await tree.files.open(src)
+        if (!stored) {
+          missing.push(name)
+          return
+        }
+        const extension = extname(src)
+        const fileName = safeFileName(
+          extname(name).toLowerCase() === extension.toLowerCase() ? name : `${name}${extension}`,
+        )
+        const content = await stored.bytes()
+        mkdirSync(dir, { recursive: true })
+        writeFileSync(join(dir, fileName), content)
+        files += 1
+        bytes += content.length
+      }
+
+      if (start) await write(start, out)
+      else for (const child of (await childrenByName(tree, null)).values()) await write(child, out)
+      mkdirSync(out, { recursive: true })
+      this.say(`  wrote    ${files} file(s) to ${here(out)}`)
+      for (const name of missing)
+        this.warning(`  missing  ${name}: its file is not in the media store`)
+      return { out: here(out), files, bytes, missing }
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/media/fetch.ts

@@ -0,0 +1,62 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { mediaStoreFor, readRemoteMedia } from '@crombolo/server'
+import { BaseCommand } from '../../base.ts'
+import { discover, RemoteClient } from '../../remote/client.ts'
+import { fetchReferencedMedia } from '../../remote/transfer.ts'
+import { describeBytes } from '../../support/describe.ts'
+import { keychain } from '../../support/remote.ts'
+import { cwd, siteConfig } from '../../support/site.ts'
+
+export default class MediaFetch extends BaseCommand {
+  static override summary = "a lazily pulled site's media files, all of them now"
+  static override description =
+    'Exits 10 when a file could not be fetched; running it again fetches only what is missing.'
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'fetched', type: 'integer' },
+      { name: 'skipped', type: 'integer' },
+      { name: 'bytes', type: 'integer' },
+      { name: 'failed', type: 'array', items: { type: 'string' } },
+    ],
+    errors: ['not_found', 'auth', 'unavailable', 'io'],
+  } as const
+
+  async run() {
+    await this.parse(MediaFetch)
+    const source = readRemoteMedia(cwd())
+    const listed = join(cwd(), '.crombolo', 'remote-media-blobs.json')
+    if (!source || !existsSync(listed))
+      this.fail(
+        'not_found',
+        'This site was not pulled with --lazy-media: there is nothing to fetch.',
+      )
+    const client = new RemoteClient(await discover(source.api), keychain())
+    const blobs = JSON.parse(await Bun.file(listed).text()) as {
+      key: string
+      etag: string | null
+    }[]
+    const fetched = await fetchReferencedMedia(client, {
+      environment: source.environment,
+      blobs,
+      store: await mediaStoreFor(await siteConfig()),
+      siteDir: cwd(),
+      onProgress: (done, total) => {
+        if (done % 50 === 0 || done === total) this.progress(`  ${done}/${total}`)
+      },
+    })
+    this.say(
+      `  media    ${fetched.fetched} fetched (${describeBytes(fetched.bytes)}), ${fetched.skipped} already here`,
+    )
+    if (fetched.failed.length > 0)
+      this.fail(
+        'io',
+        `${fetched.failed.length} file(s) could not be fetched.`,
+        'Run it again to fetch them.',
+        fetched.failed,
+      )
+    return fetched
+  }
+}

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()
+    }
+  }
+}