@byline/cli 0.1.1

package/dist/templates/byline-examples/scripts/regenerate-media.ts

@@ -0,0 +1,275 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Regenerate media — example Byline script.
+ *
+ * Iterates the `media` collection, re-uploads each original through the
+ * core upload service so Sharp regenerates the variant set declared in
+ * the current schema, then updates the document with the fresh
+ * `storedFile` via `@byline/client`.
+ *
+ * Run after changing the variant set (e.g. switching `format: 'webp'`
+ * to `'avif'` in `byline/collections/media/schema.ts`) to bring existing
+ * assets in line with the new pipeline:
+ *
+ *   pnpm tsx --env-file=.env byline/scripts/regenerate-media.ts
+ *
+ * The script orchestrates the same two-step flow the admin UI uses
+ * for an existing document — upload (createDocument: false) followed by
+ * a document update — but as a single "one-shot" Client SDK pass per
+ * media item. Variants and the original written under fresh paths;
+ * the previous original + variant files are deleted once the document
+ * has been re-pointed at the new value.
+ *
+ * Bypass-MIME images (SVG / GIF) are passed through untouched — Sharp
+ * does not produce variants for them, so the only effect is a new
+ * storagePath on a re-stored copy.
+ *
+ * Status preservation: `updateDocument` always stamps new versions with
+ * the workflow's default status (`getDefaultStatus`, i.e. the first
+ * declared status — `'draft'` for media). After the update we step the
+ * new version forward through `changeStatus` until it lands in the same
+ * slot the original occupied. Skipping this leaves the previously-
+ * published version (with the old variant set) as what
+ * `current_published_documents` returns to public readers.
+ *
+ * Currently requires the local storage provider — pulls bytes back via
+ * the provider's `uploadDir`. An S3-capable variant would add a
+ * `download(storagePath)` to `IStorageProvider` and route through that.
+ */
+
+import 'dotenv/config'
+import '../server.config.js'
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { createSuperAdminContext } from '@byline/auth'
+import { type CollectionHandle, createBylineClient } from '@byline/client'
+import {
+  type FieldUploadContext,
+  getCollectionDefinition,
+  getServerConfig,
+  getWorkflowStatuses,
+  type StoredFileValue,
+} from '@byline/core'
+import { uploadField as coreUploadField } from '@byline/core/services'
+import { extractImageMeta, generateImageVariants, isBypassMimeType } from '@byline/storage-local'
+
+const COLLECTION_PATH = 'media'
+const FIELD_NAME = 'image'
+
+async function run(): Promise<void> {
+  const config = getServerConfig()
+  const definition = getCollectionDefinition(COLLECTION_PATH)
+  if (!definition) {
+    throw new Error(`Collection '${COLLECTION_PATH}' is not registered.`)
+  }
+
+  const storage = config.storage
+  if (!storage) {
+    throw new Error(
+      `regenerate-media: no storage provider configured on ServerConfig. ` +
+        `Set storage in byline/server.config.ts.`
+    )
+  }
+  // Local-only escape hatch — we read bytes back from disk via uploadDir.
+  // Lift this when IStorageProvider grows a download primitive.
+  const uploadDir = (storage as { uploadDir?: unknown }).uploadDir
+  if (typeof uploadDir !== 'string') {
+    throw new Error(
+      'regenerate-media currently requires the local storage provider ' +
+        '(no remote download primitive on IStorageProvider yet).'
+    )
+  }
+
+  const requestContext = createSuperAdminContext({ id: 'regenerate-media-script' })
+  const client = createBylineClient({ config, requestContext })
+
+  const { id: collectionId, version: collectionVersion } =
+    await client.resolveCollectionRecord(COLLECTION_PATH)
+
+  const handle = client.collection(COLLECTION_PATH)
+
+  // Snapshot the full set up-front. Each update bumps `updated_at` and
+  // reorders the default sort, so paging through a moving window would
+  // either skip or re-visit rows. Capture `status` so we can restore
+  // each doc to its original workflow slot after the regenerated draft
+  // is written (see `restoreStatus` below).
+  const allDocs: {
+    id: string
+    path: string
+    status: string
+    fields: Record<string, any>
+  }[] = []
+  const pageSize = 100
+  for (let page = 1; ; page++) {
+    const result = await handle.find({
+      page,
+      pageSize,
+      status: 'any',
+      _bypassBeforeRead: true,
+    })
+    for (const d of result.docs) {
+      allDocs.push({
+        id: d.id,
+        path: d.path,
+        status: d.status,
+        fields: d.fields as Record<string, any>,
+      })
+    }
+    if (result.docs.length < pageSize) break
+  }
+
+  console.log(`regenerate-media: found ${allDocs.length} document(s) in '${COLLECTION_PATH}'.`)
+
+  const baseUploadCtx: Omit<FieldUploadContext, 'requestContext'> = {
+    db: config.db,
+    definition,
+    collectionId,
+    collectionVersion,
+    collectionPath: COLLECTION_PATH,
+    fieldName: FIELD_NAME,
+    storage,
+    logger: client.logger,
+    defaultLocale: config.i18n.content.defaultLocale,
+    slugifier: config.slugifier,
+    imageProcessor: {
+      extractMeta: extractImageMeta,
+      isBypassMimeType,
+      generateVariants: async ({ buffer, mimeType, storedFile, storage, upload, logger }) => {
+        const dir = (storage as { uploadDir?: unknown }).uploadDir as string
+        const absoluteOriginalPath = path.join(dir, storedFile.storagePath)
+        return generateImageVariants(
+          buffer,
+          mimeType,
+          absoluteOriginalPath,
+          dir,
+          upload.sizes ?? [],
+          logger
+        )
+      },
+    },
+  }
+
+  let processed = 0
+  let skipped = 0
+
+  for (const doc of allDocs) {
+    const image = doc.fields[FIELD_NAME] as StoredFileValue | undefined | null
+    if (image == null || !image.storagePath) {
+      console.log(`  - skip ${doc.id} (${doc.path}) — no image value`)
+      skipped += 1
+      continue
+    }
+
+    const sourceAbsolutePath = path.join(uploadDir, image.storagePath)
+    let buffer: Buffer
+    try {
+      buffer = await fs.promises.readFile(sourceAbsolutePath)
+    } catch (err) {
+      console.error(
+        `  ! skip ${doc.id} (${doc.path}) — failed to read original at ${sourceAbsolutePath}:`,
+        err
+      )
+      skipped += 1
+      continue
+    }
+
+    const uploadResult = await coreUploadField(
+      { ...baseUploadCtx, requestContext },
+      {
+        buffer,
+        originalFilename: image.originalFilename || image.filename,
+        mimeType: image.mimeType,
+        fileSize: buffer.byteLength,
+        shouldCreateDocument: false,
+      }
+    )
+
+    const nextFields = { ...doc.fields, [FIELD_NAME]: uploadResult.storedFile }
+    await handle.update(doc.id, nextFields)
+
+    // `updateDocument` always stamps the new version with the workflow's
+    // default status (the first key — 'draft' for media), so without this
+    // step the public read path keeps returning the prior published
+    // version with the old variant set. Walk the new version forward to
+    // the slot the doc originally occupied.
+    await restoreStatus(handle, definition, doc.id, doc.status)
+
+    // Best-effort orphan cleanup. Failures are non-fatal — the new
+    // value is already persisted, the doc is consistent, the unused
+    // bytes are just dead weight on disk.
+    const orphans: string[] = [
+      image.storagePath,
+      ...(image.variants ?? []).map((v) => v.storagePath).filter((p): p is string => Boolean(p)),
+    ]
+    for (const orphan of orphans) {
+      try {
+        await storage.delete(orphan)
+      } catch (err) {
+        console.warn(`    ! failed to delete orphan ${orphan}:`, err)
+      }
+    }
+
+    const variantSummary =
+      uploadResult.storedFile.variants?.map((v) => `${v.name}:${v.format ?? '?'}`).join(', ') ??
+      '(none)'
+    console.log(
+      `  - ${doc.id} (${doc.path}) → ${uploadResult.storedFile.storagePath} [${variantSummary}]`
+    )
+    processed += 1
+  }
+
+  console.log(
+    `regenerate-media: done. processed=${processed}, skipped=${skipped}, total=${allDocs.length}.`
+  )
+}
+
+/**
+ * Walk the workflow ladder forward from the new version's status (the
+ * workflow's first slot, set by `updateDocument`) to `targetStatus`.
+ *
+ * `validateStatusTransition` allows ±1-step moves and reset-to-first, so
+ * jumping straight from 'draft' to 'archived' is rejected — we step
+ * through 'published' on the way. A target equal to the current status
+ * is a no-op (transition validation accepts identical-status moves but
+ * we skip the work).
+ *
+ * Throws if `targetStatus` is not declared on the collection's workflow,
+ * since that signals a stale snapshot or a workflow definition that has
+ * been edited since the docs were created.
+ */
+async function restoreStatus(
+  handle: CollectionHandle,
+  definition: Parameters<typeof getWorkflowStatuses>[0],
+  documentId: string,
+  targetStatus: string
+): Promise<void> {
+  const statuses = getWorkflowStatuses(definition).map((s) => s.name)
+  const targetIndex = statuses.indexOf(targetStatus)
+  if (targetIndex === -1) {
+    throw new Error(
+      `restoreStatus: status '${targetStatus}' is not declared on collection ` +
+        `'${definition.path}' (declared: ${statuses.join(', ')}).`
+    )
+  }
+  // The new version is always at index 0 (workflow default). Anything at
+  // index > 0 needs that many forward transitions.
+  for (let i = 1; i <= targetIndex; i++) {
+    await handle.changeStatus(documentId, statuses[i] as string)
+  }
+}
+
+run()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    console.error('regenerate-media failed:', err)
+    process.exit(1)
+  })

package/dist/templates/byline-examples/seed.ts

@@ -0,0 +1,25 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+// Initialize Byline config by importing the server config
+import 'dotenv/config'
+import './server.config.js'
+
+import { seedAdmin } from './seeds/admin.js'
+import { seedDocsCategories } from './seeds/doc-categories.js'
+import { seedDocs } from './seeds/docs.js'
+import { seedNewsCategories } from './seeds/news-categories.js'
+
+async function run() {
+  await seedAdmin()
+  await seedDocsCategories()
+  await seedNewsCategories()
+  await seedDocs()
+}
+
+run()

package/dist/templates/byline-examples/seeds/admin.ts

@@ -0,0 +1,62 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Super-admin bootstrap seed.
+ *
+ * Idempotent. Reads credentials from env (`BYLINE_SUPERADMIN_EMAIL`,
+ * `BYLINE_SUPERADMIN_PASSWORD`) and calls the built-in
+ * `seedSuperAdmin` helper from `@byline/admin/admin-users` against an
+ * `AdminStore` built on the application's single connection pool.
+ *
+ * The admin account it produces:
+ *   - `is_super_admin: true`  — bypasses every ability check
+ *   - `is_enabled: true`       — ready to sign in immediately
+ *   - `is_email_verified: true` — skip the verification gate for bootstrap
+ *
+ * In any non-dev deployment: change the credentials in env, run the seed
+ * once, then immediately change the password from inside the admin UI.
+ */
+
+import type { AdminStore } from '@byline/admin'
+import { seedSuperAdmin } from '@byline/admin/admin-users'
+import { getBylineCore } from '@byline/core'
+
+export async function seedAdmin() {
+  const email = process.env.BYLINE_SUPERADMIN_EMAIL
+  const password = process.env.BYLINE_SUPERADMIN_PASSWORD
+
+  if (!email || !password) {
+    console.warn(
+      'Skipping admin seed: BYLINE_SUPERADMIN_EMAIL and BYLINE_SUPERADMIN_PASSWORD ' +
+        'must both be set (see .env.example).'
+    )
+    return
+  }
+
+  const bylineCore = getBylineCore<AdminStore>()
+
+  if (!bylineCore.adminStore) {
+    throw new Error(
+      'seedAdmin: bylineCore.adminStore is not configured. ' +
+        'Pass adminStore to initBylineCore() in byline/server.config.ts.'
+    )
+  }
+
+  const result = await seedSuperAdmin(bylineCore.adminStore, { email, password })
+
+  const parts: string[] = []
+  if (result.created.role) parts.push('role')
+  if (result.created.user) parts.push('user')
+  if (result.created.assignment) parts.push('assignment')
+  if (parts.length === 0) {
+    console.log(`Super-admin already present (${email}) — no changes.`)
+  } else {
+    console.log(`Super-admin seed: created ${parts.join(', ')} for ${email}.`)
+  }
+}

package/dist/templates/byline-examples/seeds/doc-categories.ts

@@ -0,0 +1,71 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { getCollectionDefinition, getDefaultStatus, getServerConfig, slugify } from '@byline/core'
+
+const categories = [
+  {
+    name: { en: 'Whitepaper' },
+    description: { en: 'In-depth articles and research papers.' },
+  },
+  {
+    name: { en: 'Tutorial' },
+    description: { en: 'Step-by-step guides and how-tos.' },
+  },
+  {
+    name: { en: 'Framework' },
+    description: { en: 'Libraries, frameworks, and toolkits.' },
+  },
+]
+
+export async function seedDocsCategories() {
+  const db = getServerConfig().db
+
+  const collectionDefinition = getCollectionDefinition('docs-categories')
+
+  if (!collectionDefinition) {
+    console.error('Collection definition not found for "docs-categories"')
+    return
+  }
+
+  // `initBylineCore` already registered the collection row via
+  // `ensureCollections()` when byline/server.config was imported, so we
+  // look the row up rather than re-inserting (which would violate the
+  // unique-path constraint).
+  const existing = await db.queries.collections.getCollectionByPath('docs-categories')
+  if (!existing) {
+    throw new Error(
+      "seedDocsCategories: expected the 'docs-categories' collection to be registered by initBylineCore()"
+    )
+  }
+
+  const categoriesCollection = {
+    id: existing.id as string,
+    name: existing.path as string,
+    version: (existing.version as number | undefined) ?? 1,
+  }
+
+  console.log(`Seeding into Docs Categories collection (${categoriesCollection.name})`)
+
+  for (const category of categories) {
+    const seedPath = slugify(category.name.en, {
+      locale: 'en',
+      collectionPath: 'docs-categories',
+    })
+    await db.commands.documents.createDocumentVersion({
+      collectionId: categoriesCollection.id,
+      collectionVersion: categoriesCollection.version,
+      collectionConfig: collectionDefinition,
+      action: 'create',
+      documentData: category,
+      path: seedPath,
+      status: getDefaultStatus(collectionDefinition),
+    })
+    console.log(`  - seeded category: ${category.name.en} (${seedPath})`)
+  }
+}