transloadit 4.12.0 → 4.13.1

package/src/cli/storageCatalog.ts

@@ -0,0 +1,192 @@
+import type { StoredAsset } from '../alphalib/types/storageAsset.ts'
+import type { ResolvedCliConfig } from './helpers.ts'
+import type { IOutputCtl } from './OutputCtl.ts'
+
+import { RequestError } from 'got'
+
+import { ApiError } from '../ApiError.ts'
+import { damPathMaxCodePoints } from '../alphalib/types/storageAsset.ts'
+import { Transloadit } from '../Transloadit.ts'
+import {
+  buildMissingCredentialsMessage,
+  noticeCliCredentialSource,
+  resolveCliConfig,
+} from './helpers.ts'
+import { assertStorageWorkspace } from './storageReceipts.ts'
+
+function readDeadline(signal?: AbortSignal): AbortSignal {
+  return signal === undefined
+    ? AbortSignal.timeout(60_000)
+    : AbortSignal.any([signal, AbortSignal.timeout(60_000)])
+}
+
+/** Keeps Workspace discovery, credentials and bounded catalog reads on the same trusted origin. */
+export async function withStorageCatalog<T>(
+  options: {
+    endpoint?: string
+    workspace?: string
+    projectWorkspace?: string
+    signal?: AbortSignal
+  },
+  operation: (client: Transloadit, workspace: string, endpoint: string) => Promise<T>,
+  failure: string,
+  output?: Pick<IOutputCtl, 'notice'>,
+  config: ResolvedCliConfig = resolveCliConfig(),
+): Promise<T> {
+  if (config.credentials === undefined)
+    throw new Error(config.loadError ?? buildMissingCredentialsMessage())
+  noticeCliCredentialSource(config, output, 'credentials')
+  const endpoint = new URL(
+    options.endpoint ?? config.credentialsEndpoint ?? 'https://api2.transloadit.com',
+  )
+  if (
+    !['http:', 'https:'].includes(endpoint.protocol) ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    endpoint.pathname !== '/'
+  ) {
+    throw new Error(
+      'Storage endpoint must be an HTTP(S) API origin without credentials, query or fragment',
+    )
+  }
+  const client = new Transloadit({
+    ...config.credentials,
+    endpoint: endpoint.origin,
+    maxRetries: 0,
+  })
+  try {
+    const { workspace } = await client.listStoredAssets({
+      limit: 1,
+      signal: readDeadline(options.signal),
+    })
+    assertStorageWorkspace(workspace, options.projectWorkspace, options.workspace)
+    options.signal?.throwIfAborted()
+    return await operation(client, workspace, endpoint.origin)
+  } catch (error) {
+    options.signal?.throwIfAborted()
+    if (error instanceof ApiError) {
+      const status = error.cause?.response?.statusCode
+      if (error.code === 'DAM_INVALID_REQUEST' || error.code === 'DAM_INVALID_INPUT')
+        throw new Error(
+          `${failure} received an invalid request. Check the Storage prefix and paging options.`,
+          { cause: error },
+        )
+      throw new Error(
+        `${failure} failed${status === undefined ? '' : ` (HTTP ${status})`}. Check the Storage API at ${endpoint.origin} and the Auth Key dam:read or dam:write scope.`,
+        { cause: error },
+      )
+    }
+    if (
+      error instanceof RequestError ||
+      (error instanceof Error && ['TimeoutError', 'AbortError'].includes(error.name))
+    ) {
+      throw new Error(
+        `${failure} timed out or lost its connection. Check the Storage endpoint and retry.`,
+        { cause: error },
+      )
+    }
+    throw error
+  }
+}
+
+/** Catalog prefixes allow ordinary filenames that the image renderer intentionally restricts. */
+function validateCatalogPrefix(prefix: string): void {
+  const segments = prefix.replace(/\/$/, '').split('/')
+  if (
+    [...prefix].length > damPathMaxCodePoints ||
+    new TextEncoder().encode(prefix).length > 1024 ||
+    /[\\\p{Cc}\p{Cs}]/u.test(prefix) ||
+    (prefix !== '' &&
+      segments.some((segment) => segment.trim() === '' || segment === '.' || segment === '..'))
+  )
+    throw new Error(
+      'Invalid Storage prefix: use at most 512 characters (1024 UTF-8 bytes) in a relative path without empty, dot, or parent-directory segments.',
+    )
+}
+
+/** Completes every bounded page, refusing wrong-Workspace, duplicate or out-of-prefix metadata. */
+export async function listStorageAssets(
+  client: Transloadit,
+  workspace: string,
+  prefix: string,
+  signal?: AbortSignal,
+): Promise<StoredAsset[]> {
+  const normalizedPrefix = prefix.normalize('NFC')
+  validateCatalogPrefix(normalizedPrefix)
+  const assets: StoredAsset[] = []
+  const paths = new Set<string>()
+  const cursors = new Set<string>()
+  let cursor: string | undefined
+  do {
+    const page = await client.listStoredAssets({
+      prefix: normalizedPrefix,
+      cursor,
+      limit: 500,
+      signal: readDeadline(signal),
+    })
+    if (page.workspace !== workspace)
+      throw new Error('Storage changed Workspace while paging the catalog')
+    for (const asset of page.assets) {
+      try {
+        validateCatalogPrefix(asset.path)
+        if (asset.path.endsWith('/')) throw new Error('Expected a file path')
+      } catch (error) {
+        throw new Error(`Storage returned an invalid asset path: ${JSON.stringify(asset.path)}`, {
+          cause: error,
+        })
+      }
+      if (!asset.path.startsWith(normalizedPrefix) || paths.has(asset.path)) {
+        throw new Error(
+          `Storage returned a duplicate path or one outside the requested prefix: ${JSON.stringify(asset.path)}`,
+        )
+      }
+      paths.add(asset.path)
+      assets.push(asset)
+    }
+    if (page.next_cursor === null) break
+    cursor = page.next_cursor
+    if (!cursor || cursors.has(cursor) || page.assets.at(-1)?.path !== cursor) {
+      throw new Error('Storage omitted or repeated its listing cursor; results would be incomplete')
+    }
+    cursors.add(cursor)
+  } while (cursor !== undefined)
+  return assets
+}
+
+/** Verify writes against the selected key, not an unverified Workspace label in shell dotenv. */
+export async function resolveStorageWorkspace(
+  options: { endpoint?: string; workspace?: string },
+  config: ResolvedCliConfig,
+  projectWorkspace?: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  signal?.throwIfAborted()
+  if (config.auth === undefined || !('authKey' in config.auth)) {
+    throw new Error(
+      'Storage project binding requires an Auth Key. Unset TRANSLOADIT_AUTH_TOKEN to use key credentials; run transloadit auth login if needed.',
+    )
+  }
+  const sameEndpoint =
+    options.endpoint === undefined ||
+    new URL(options.endpoint).origin ===
+      new URL(config.endpoint ?? 'https://api2.transloadit.com').origin
+  const workspace =
+    config.authWorkspaceVerified && sameEndpoint && config.authWorkspace !== undefined
+      ? config.authWorkspace
+      : await withStorageCatalog(
+          { endpoint: options.endpoint, signal },
+          async (_client, actual) => actual,
+          'Workspace verification',
+          undefined,
+          {
+            credentials: config.auth,
+            credentialsEndpoint: config.endpoint,
+            credentialsSource: config.authSource,
+          },
+        )
+  assertStorageWorkspace(workspace, projectWorkspace, options.workspace)
+  signal?.throwIfAborted()
+  return workspace
+}

package/src/cli/storagePublic.ts

@@ -0,0 +1,15 @@
+import { ApiError } from '../ApiError.ts'
+
+/** Actionable CLI advice without printing remote response bodies or credentials. */
+export function storagePublicError(error: unknown, workspace?: string): string {
+  if (error instanceof ApiError && error.code === 'STORAGE_PUBLIC_PREFIX_NEEDS_SMART_CDN_KEY') {
+    const slug =
+      workspace !== undefined && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(workspace)
+        ? workspace
+        : '<workspace>'
+    return `Enable Smart CDN on an Auth Key at https://transloadit.com/c/${slug}/template-credentials/ and retry. The same key can serve Assemblies and Smart CDN.`
+  }
+  if (error instanceof TypeError) return error.message
+  // Keep unrecognized server errors out of CLI output; only known codes select specific advice.
+  return 'Could not update or list public Storage prefixes. Check the API endpoint and Auth Key dam:write scope, then retry.'
+}

package/src/cli/storageReceipts.ts

@@ -0,0 +1,307 @@
+import type { FileHandle } from 'node:fs/promises'
+
+import { randomUUID } from 'node:crypto'
+import { chmod, lstat, open, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+
+import { z } from 'zod'
+
+import { storedAssetSchema } from '../alphalib/types/storageAsset.ts'
+import { normalizeStoragePublicPrefix } from '../storagePublicPrefixes.ts'
+import { ensureError, isErrnoException } from './types.ts'
+
+// Keep every JSON key verbatim: a Storage filename may be "__proto__", which z.record strips.
+const receiptsSchema = z.custom<Record<string, unknown>>(
+  (value: unknown) => typeof value === 'object' && value !== null && !Array.isArray(value),
+)
+const deliveryParameterSchema = z.union([z.string(), z.number(), z.boolean()])
+
+/** Project identity and rendering metadata (including optional preview pixels), without credentials. */
+export const storageCatalogSchema = z
+  .object({
+    workspace: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/),
+    apiOrigin: z.string().url().optional(),
+    public: z.array(
+      z.string().refine((prefix) => {
+        try {
+          return normalizeStoragePublicPrefix(prefix) === prefix
+        } catch {
+          return false
+        }
+      }, 'Expected a normalized public directory'),
+    ),
+    images: receiptsSchema,
+    delivery: z
+      .object({
+        baseUrl: z.string().url().optional(),
+        urlParams: z
+          .record(z.string(), z.union([deliveryParameterSchema, z.array(deliveryParameterSchema)]))
+          .optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough()
+export type StorageProjectCatalog = z.infer<typeof storageCatalogSchema>
+
+/** Default project catalog; --receipts can select a separate project explicitly. */
+export const defaultStorageCatalog = 'transloadit.images.json'
+
+/** Non-production login origins are explicit transport overrides, never rendering credentials. */
+export function storageCatalogDelivery(endpoint?: string): StorageProjectCatalog['delivery'] {
+  if (!endpoint) return undefined
+  const { origin } = new URL(endpoint)
+  if (origin === 'https://api2.transloadit.com') return undefined
+  return { baseUrl: `${origin}/file/{workspace}`, urlParams: { cdn: 'required' } }
+}
+
+const imageReceiptSchema = storedAssetSchema.extend({
+  width: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  height: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+})
+
+const typesHeader =
+  '// Generated by transloadit storage. Commit this file with the image catalog; do not edit.'
+
+/** The single conventional type-registration file beside a CLI catalog. */
+export function storageTypesPath(catalog: string): string {
+  return join(dirname(catalog), 'transloadit-images.d.ts')
+}
+
+function catalogTypes(catalog: StorageProjectCatalog, file?: string): string {
+  // Canonical LF keeps generated output deterministic; Git controls checkout-specific EOL conversion.
+  const properties = Object.entries(catalog.images)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .flatMap(([path, receipt]) => {
+      const dimensions = imageReceiptSchema.safeParse(receipt)
+      // Legacy entries remain on disk, but require native recovery before they are usable sources.
+      if (!dimensions.success) return []
+      const { width, height, asset_id, version_id, workspace } = dimensions.data
+      const name = JSON.stringify(path)
+      return `    ${name}: { path: ${name}; workspace: ${JSON.stringify(workspace)}; asset_id: ${JSON.stringify(asset_id)}; version_id: ${JSON.stringify(version_id)}; width: ${width}; height: ${height}; thumbhash?: string; hasAlpha?: boolean }`
+    })
+  return [
+    typesHeader,
+    ...(file === undefined ? [] : [`// Catalog: ${JSON.stringify(basename(file))}`]),
+    "import '@transloadit/viewer/next'",
+    '',
+    "declare module '@transloadit/viewer/next' {",
+    '  interface RegisteredStorageImages {',
+    ...properties,
+    '  }',
+    '}',
+    '',
+  ].join('\n')
+}
+
+async function readReceipts(
+  file: string,
+): Promise<{ catalog?: StorageProjectCatalog; mode?: number }> {
+  try {
+    const info = await lstat(file)
+    if (!info.isFile()) throw new Error('Expected a regular JSON file, not a symlink or directory')
+    return {
+      catalog: storageCatalogSchema.parse(JSON.parse(await readFile(file, 'utf8'))),
+      mode: info.mode & 0o777,
+    }
+  } catch (error) {
+    if (isErrnoException(error) && error.code === 'ENOENT') return {}
+    const reason =
+      error instanceof SyntaxError
+        ? 'invalid JSON'
+        : error instanceof z.ZodError
+          ? `invalid catalog field ${error.issues[0]?.path.join('.') || 'workspace/public/images'}`
+          : ensureError(error).message
+    throw new Error(`Cannot read receipts ${JSON.stringify(file)}: ${reason}`, { cause: error })
+  }
+}
+
+/** Read a project binding without creating a catalog or making a network request. */
+export async function readStorageCatalog(file: string): Promise<StorageProjectCatalog | undefined> {
+  return (await readReceipts(file)).catalog
+}
+
+/** A workspace override selects another workspace, never another key or implicit project rebinding. */
+export function assertStorageWorkspace(actual: string, project?: string, requested?: string): void {
+  if (!storageCatalogSchema.shape.workspace.safeParse(actual).success)
+    throw new Error(
+      `Invalid Storage Workspace ${JSON.stringify(actual)}: expected a URL-safe slug beginning with a letter or digit.`,
+    )
+  if (requested !== undefined && requested !== actual)
+    throw new Error(`Selected credentials belong to ${actual}, not ${requested}. Nothing uploaded.`)
+  if (project !== undefined && project !== actual && requested === undefined)
+    throw new Error(
+      `Project uses ${project}; the selected credentials belong to ${actual}. Nothing uploaded.`,
+    )
+}
+
+const receiptOriginSchema = z.object({ apiOrigin: z.string().url().optional() })
+
+/** Delivery hosts do not prove provenance; a matching Workspace slug is not an API identity. */
+export function assertStorageCatalogOrigin(
+  catalog: StorageProjectCatalog | undefined,
+  endpoint: string,
+  file: string,
+): void {
+  const mismatch = (): Error =>
+    new Error(
+      `Catalog ${JSON.stringify(file)} belongs to another API environment. Use --receipts for a separate catalog; the existing file was preserved.`,
+    )
+  if (catalog?.apiOrigin !== undefined && new URL(catalog.apiOrigin).origin !== endpoint)
+    throw mismatch()
+  if (
+    catalog !== undefined &&
+    catalog.apiOrigin === undefined &&
+    Object.keys(catalog.images).length === 0 &&
+    (catalog.public.length > 0 || catalog.delivery !== undefined)
+  )
+    throw new Error(
+      `Catalog ${JSON.stringify(file)} has no verified API origin. Run storage receipts sync into a new --receipts file using the original API --endpoint, then review and replace this catalog. The existing file was preserved.`,
+    )
+  for (const [path, value] of Object.entries(catalog?.images ?? {})) {
+    const previous = receiptOriginSchema.safeParse(value)
+    if (
+      !previous.success ||
+      (previous.data.apiOrigin === undefined && catalog?.apiOrigin === undefined)
+    )
+      throw new Error(
+        `Catalog ${JSON.stringify(file)} has no verified API origin for ${JSON.stringify(path)}. Run storage receipts sync into a new --receipts file using the original API --endpoint, then review and replace this catalog. The existing file was preserved.`,
+      )
+    if (
+      previous.data.apiOrigin !== undefined &&
+      new URL(previous.data.apiOrigin).origin !== endpoint
+    )
+      throw mismatch()
+  }
+}
+
+/**
+ * Serializes CLI receipt writers and replaces a catalog only after the complete update succeeds.
+ * onCheckpoint observes a completed rename even if interruption or cleanup subsequently fails.
+ */
+export async function updateStorageReceipts(
+  file: string,
+  update: (
+    catalog: StorageProjectCatalog | undefined,
+    signal: AbortSignal,
+  ) => Promise<StorageProjectCatalog | undefined>,
+  onCheckpoint?: () => void,
+): Promise<void> {
+  const lockPath = `${file}.lock`
+  const temporary = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`)
+  const typesFile = storageTypesPath(file)
+  if (basename(file) === 'transloadit-images.d.ts')
+    throw new Error(
+      'The catalog cannot use the generated declarations filename transloadit-images.d.ts',
+    )
+  const typesTemporary = `${temporary}.d.ts`
+  const cancellation = new AbortController()
+  const cancel = (): void =>
+    cancellation.abort(
+      new Error('Storage command canceled. Check Storage before retrying a write.'),
+    )
+  // The first interrupt is cooperative; a forced exit/crash still leaves a lock for inspection.
+  process.once('SIGINT', cancel)
+  process.once('SIGTERM', cancel)
+  let lock: FileHandle | undefined
+  let typesLock: FileHandle | undefined
+  let retainTemporary = false
+  try {
+    lock = await open(lockPath, 'wx', 0o600).catch((error: unknown) => {
+      if (isErrnoException(error) && error.code === 'EEXIST') {
+        throw new Error(
+          `The receipts file is locked by another storage store or receipts sync. Remove ${lockPath} only after confirming no writer is running.`,
+          { cause: error },
+        )
+      }
+      throw error
+    })
+    cancellation.signal.throwIfAborted()
+    // Different catalog filenames still share one ambient type-registration file.
+    typesLock = await open(`${typesFile}.lock`, 'wx', 0o600).catch((error: unknown) => {
+      throw new Error(
+        `Generated declarations are locked: ${typesFile}. Wait for the other catalog writer.`,
+        { cause: error },
+      )
+    })
+    const { catalog, mode } = await readReceipts(file)
+    const typesInfo = await lstat(typesFile).catch((error: unknown) => {
+      if (isErrnoException(error) && error.code === 'ENOENT') return undefined
+      throw error
+    })
+    if (typesInfo !== undefined && !typesInfo.isFile())
+      throw new Error(`Expected a regular generated types file: ${typesFile}`)
+    if (
+      typesInfo !== undefined &&
+      (await readFile(typesFile, 'utf8')).split(/\r?\n/, 1)[0] !== typesHeader
+    )
+      throw new Error(
+        `Refusing to overwrite handwritten declarations in ${typesFile}. Move them to a separate file before retrying.`,
+      )
+    if (typesInfo !== undefined) {
+      const existing = (await readFile(typesFile, 'utf8')).replaceAll('\r\n', '\n')
+      const owner = existing.split('\n')[1]
+      const expectedOwner = `// Catalog: ${JSON.stringify(basename(file))}`
+      // Upgrade older generated files only when they exactly describe this existing catalog.
+      if (owner !== expectedOwner && !(catalog !== undefined && existing === catalogTypes(catalog)))
+        throw new Error(
+          `Generated declarations in ${typesFile} belong to ${owner?.startsWith('// Catalog: ') ? owner.slice(12) : 'another catalog'}. Use --receipts in a separate directory; the active catalog was preserved.`,
+        )
+    }
+    const updated = await update(catalog, cancellation.signal)
+    // An explicit one-off workspace override must not mix two workspaces in one catalog.
+    if (updated === undefined) {
+      cancellation.signal.throwIfAborted()
+      return
+    }
+    if (!storageCatalogSchema.safeParse(updated).success)
+      throw new Error(
+        'Cannot write an invalid Storage catalog; check its Workspace, public prefixes and delivery configuration.',
+      )
+    // Once a remote write returned a receipt, finish its atomic checkpoint even if interrupted.
+    // New catalogs are ordinary source files: let the kernel apply umask, without reading it.
+    await writeFile(temporary, `${JSON.stringify(updated, null, 2)}\n`, {
+      flag: 'wx',
+      mode: mode === undefined ? 0o666 : 0o600,
+    })
+    retainTemporary = true
+    if (mode !== undefined) await chmod(temporary, mode)
+    await writeFile(typesTemporary, catalogTypes(updated, file), { flag: 'wx', mode: 0o666 })
+    if (typesInfo !== undefined) await chmod(typesTemporary, typesInfo.mode & 0o777)
+    await rename(temporary, file)
+    retainTemporary = false
+    onCheckpoint?.()
+    // The catalog is the authoritative checkpoint. A failure replacing derived types must
+    // never discard a verified upload; sync can regenerate declarations without another write.
+    await rename(typesTemporary, typesFile).catch((error: unknown) => {
+      throw new Error(
+        `Catalog saved, but cannot update ${typesFile}. Run storage receipts sync to regenerate types without re-uploading.`,
+        { cause: error },
+      )
+    })
+    cancellation.signal.throwIfAborted()
+  } catch (error) {
+    if (retainTemporary)
+      throw new Error(
+        `${ensureError(error).message}\nComplete catalog retained at ${JSON.stringify(temporary)}.`,
+        { cause: error },
+      )
+    throw error
+  } finally {
+    try {
+      if (typesLock !== undefined) {
+        await typesLock.close()
+        await rm(`${typesFile}.lock`, { force: true })
+      }
+      if (lock !== undefined) {
+        await lock.close()
+        await rm(lockPath, { force: true })
+        if (!retainTemporary) await rm(temporary, { force: true })
+        await rm(typesTemporary, { force: true })
+      }
+    } finally {
+      process.off('SIGINT', cancel)
+      process.off('SIGTERM', cancel)
+    }
+  }
+}

package/src/cli/storageSnippets.ts

@@ -0,0 +1,96 @@
+import { statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+
+import { quoteCliArgument } from './helpers.ts'
+
+/** Locate ordinary Next.js app directories without assuming the consumer's source layout. */
+export function nextAppRoot(): '' | 'src/' | undefined {
+  if (statSync('app', { throwIfNoEntry: false })?.isDirectory()) return ''
+  if (statSync('src/app', { throwIfNoEntry: false })?.isDirectory()) return 'src/'
+  return undefined
+}
+
+/** Advice only: never execute or rewrite a consumer's Next config after a successful upload. */
+export async function storageImageConfigAdvice(): Promise<string> {
+  for (const file of ['next.config.ts', 'next.config.mjs', 'next.config.js']) {
+    // An unavailable optional hint must not turn a completed Storage write into a CLI failure.
+    const source = await readFile(file, 'utf8').catch(() => undefined)
+    if (source === undefined) continue
+    if (source.includes('withTransloaditImages')) return ''
+    const commonJsAdvice = file.endsWith('.js')
+      ? '\nFor CommonJS, rename next.config.js to next.config.mjs and convert require/module.exports to import/export before using this ESM example.'
+      : ''
+    return `\n${file} is not wrapped yet. Keep your existing config in nextConfig and wrap its export:${commonJsAdvice}\nimport { withTransloaditImages } from '@transloadit/viewer/next/config'\nexport default withTransloaditImages(nextConfig)`
+  }
+  return ''
+}
+
+/** Private redirect delivery needs an application authorizer and key, not the CLI login key. */
+export function storageImagePrivateAdvice(path: string, receipts?: string): string {
+  const prefix = path.slice(0, path.lastIndexOf('/') + 1)
+  if (prefix === '')
+    return '\nThis object is private. Configure per-object authorization explicitly, or store it under a directory to use image init --private. Set TRANSLOADIT_SMART_CDN_KEY/SECRET for rendering.'
+  const catalogOption = receipts === undefined ? '' : ` --receipts=${quoteCliArgument(receipts)}`
+  // Stop option parsing explicitly: Storage paths are data, including names starting with a dash.
+  return `\nThis directory is private. Rendering needs transloadit.authorize.ts and ${nextAppRoot() ?? ''}app/api/storage-images/route.ts (npx transloadit image init --private${catalogOption} -- ${quoteCliArgument(prefix)}) and TRANSLOADIT_SMART_CDN_KEY/SECRET. Restart next dev after adding them.`
+}
+
+function relativeImport(path: string): string {
+  return path.startsWith('./') || path.startsWith('../') ? path : `./${path}`
+}
+
+function sourceString(value: string): string {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n').replaceAll('\r', '\\r').replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029')}'`
+}
+
+/** An empty-safe scaffold showing the first receipt in the initialized directory. */
+export function storageImagePage(
+  receiptsImport: string,
+  prefix: string,
+  receipts?: string,
+): string {
+  const catalogOption = receipts === undefined ? '' : ` --receipts=${quoteCliArgument(receipts)}`
+  const command = `npx transloadit storage store${catalogOption}${prefix.startsWith('-') ? ' --' : ''} ./hero.jpg ${quoteCliArgument(`${prefix}hero.jpg`)}`
+  return [
+    "import { Image } from '@transloadit/viewer/next'",
+    `import catalog from ${sourceString(relativeImport(receiptsImport))}`,
+    '',
+    'export default function Page() {',
+    `  const path = Object.keys(catalog.images).find((path) => path.startsWith(${sourceString(prefix)}))`,
+    '  if (path === undefined)',
+    '    return (',
+    '      <p>',
+    `        Run <code>{${sourceString(command)}}</code> to add your`,
+    '        first image.',
+    '      </p>',
+    '    )',
+    '  // Object.keys only returns own catalog keys, including when the catalog is still empty.',
+    '  const src = path as keyof typeof catalog.images',
+    '  // Replace the filename-derived alt with a description, or an empty string if decorative.',
+    '  const alt = path',
+    "    .slice(path.lastIndexOf('/') + 1)",
+    "    .replace(/\\.[^.]+$/, '')",
+    "    .replaceAll(/[-_]+/g, ' ')",
+    '  return (',
+    '    <Image',
+    '      storage',
+    '      src={src}',
+    '      alt={alt}',
+    '      width={960}',
+    '      preload',
+    '      errorFallback={',
+    '        <p role="status">',
+    '          This image could not be loaded. Check the Storage path and delivery configuration.',
+    '        </p>',
+    '      }',
+    '    />',
+    '  )',
+    '}',
+    '',
+  ].join('\n')
+}
+
+/** Rendering-only variable names; values belong in the application's secret configuration. */
+export function storageImageEnvBlock(publicOnly: boolean): string {
+  return publicOnly ? '' : 'TRANSLOADIT_KEY=\nTRANSLOADIT_SECRET=\n'
+}