transloadit 4.7.4 → 4.8.0

package/src/cli/resultFiles.ts

@@ -0,0 +1,105 @@
+export interface AssemblyResultEntryLike {
+  basename?: unknown
+  ext?: unknown
+  name?: unknown
+  ssl_url?: unknown
+  url?: unknown
+}
+
+export interface NormalizedAssemblyResultFile {
+  file: AssemblyResultEntryLike
+  name: string
+  stepName: string
+  url: string
+}
+
+export interface NormalizedAssemblyResults {
+  allFiles: NormalizedAssemblyResultFile[]
+  entries: Array<[string, Array<AssemblyResultEntryLike>]>
+}
+
+function isAssemblyResultEntryLike(value: unknown): value is AssemblyResultEntryLike {
+  return value != null && typeof value === 'object'
+}
+
+function normalizeAssemblyResultName(
+  stepName: string,
+  file: AssemblyResultEntryLike,
+): string | null {
+  if (typeof file.name === 'string') {
+    return file.name
+  }
+
+  if (typeof file.basename === 'string') {
+    if (typeof file.ext === 'string' && file.ext.length > 0) {
+      return `${file.basename}.${file.ext}`
+    }
+
+    return file.basename
+  }
+
+  return `${stepName}_result`
+}
+
+function normalizeAssemblyResultUrl(file: AssemblyResultEntryLike): string | null {
+  if (typeof file.ssl_url === 'string') {
+    return file.ssl_url
+  }
+
+  if (typeof file.url === 'string') {
+    return file.url
+  }
+
+  return null
+}
+
+function normalizeAssemblyResultFile(
+  stepName: string,
+  value: unknown,
+): NormalizedAssemblyResultFile | null {
+  if (!isAssemblyResultEntryLike(value)) {
+    return null
+  }
+
+  const url = normalizeAssemblyResultUrl(value)
+  const name = normalizeAssemblyResultName(stepName, value)
+  if (url == null || name == null) {
+    return null
+  }
+
+  return {
+    file: value,
+    name,
+    stepName,
+    url,
+  }
+}
+
+export function normalizeAssemblyResults(results: unknown): NormalizedAssemblyResults {
+  if (results == null || typeof results !== 'object' || Array.isArray(results)) {
+    return {
+      allFiles: [],
+      entries: [],
+    }
+  }
+
+  const files: NormalizedAssemblyResultFile[] = []
+  const entries = Object.entries(results)
+  for (const [stepName, stepResults] of entries) {
+    if (!Array.isArray(stepResults)) {
+      continue
+    }
+
+    for (const stepResult of stepResults) {
+      const normalized = normalizeAssemblyResultFile(stepName, stepResult)
+      if (normalized != null) {
+        files.push(normalized)
+      }
+    }
+  }
+
+  return {
+    allFiles: files,
+    entries,
+  }
+}

package/src/cli/resultUrls.ts

@@ -0,0 +1,72 @@
+import type { IOutputCtl } from './OutputCtl.ts'
+import type { NormalizedAssemblyResults } from './resultFiles.ts'
+import { normalizeAssemblyResults } from './resultFiles.ts'
+
+export interface ResultUrlRow {
+  assemblyId: string
+  name: string
+  step: string
+  url: string
+}
+
+export function collectResultUrlRows({
+  assemblyId,
+  results,
+}: {
+  assemblyId: string
+  results: unknown
+}): ResultUrlRow[] {
+  return collectNormalizedResultUrlRows({
+    assemblyId,
+    normalizedResults: normalizeAssemblyResults(results),
+  })
+}
+
+export function collectNormalizedResultUrlRows({
+  assemblyId,
+  normalizedResults,
+}: {
+  assemblyId: string
+  normalizedResults: NormalizedAssemblyResults
+}): ResultUrlRow[] {
+  return normalizedResults.allFiles.map((file) => ({
+    assemblyId,
+    step: file.stepName,
+    name: file.name,
+    url: file.url,
+  }))
+}
+
+export function formatResultUrlRows(rows: readonly ResultUrlRow[]): string {
+  if (rows.length === 0) {
+    return ''
+  }
+
+  const includeAssembly = new Set(rows.map((row) => row.assemblyId)).size > 1
+  const headers = includeAssembly ? ['ASSEMBLY', 'STEP', 'NAME', 'URL'] : ['STEP', 'NAME', 'URL']
+  const tableRows = rows.map((row) =>
+    includeAssembly ? [row.assemblyId, row.step, row.name, row.url] : [row.step, row.name, row.url],
+  )
+
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...tableRows.map((row) => row[index]?.length ?? 0)),
+  )
+
+  return [headers, ...tableRows]
+    .map((row) =>
+      row
+        .map((value, index) =>
+          index === row.length - 1 ? value : value.padEnd(widths[index] ?? value.length),
+        )
+        .join('  '),
+    )
+    .join('\n')
+}
+
+export function printResultUrls(output: IOutputCtl, rows: readonly ResultUrlRow[]): void {
+  if (rows.length === 0) {
+    return
+  }
+
+  output.print(formatResultUrlRows(rows), { urls: rows })
+}

package/src/cli/semanticIntents/imageDescribe.ts

@@ -0,0 +1,257 @@
+import { parseStringArrayValue } from '../intentFields.ts'
+import type {
+  IntentDynamicStepExecutionDefinition,
+  IntentOptionDefinition,
+} from '../intentRuntime.ts'
+import type { SemanticIntentDescriptor, SemanticIntentPresentation } from './index.ts'
+import { parseOptionalEnumValue, parseUniqueEnumArray } from './parsing.ts'
+
+const imageDescribeFields = ['labels', 'altText', 'title', 'caption', 'description'] as const
+
+type ImageDescribeField = (typeof imageDescribeFields)[number]
+
+const wordpressDescribeFields = [
+  'altText',
+  'title',
+  'caption',
+  'description',
+] as const satisfies readonly ImageDescribeField[]
+
+const defaultDescribeModel = 'anthropic/claude-4-sonnet-20250514'
+const describeFieldDescriptions = {
+  altText: 'A concise accessibility-focused alt text that objectively describes the image',
+  title: 'A concise publishable title for the image',
+  caption: 'A short caption suitable for displaying below the image',
+  description: 'A richer description of the image suitable for CMS usage',
+} as const satisfies Record<Exclude<ImageDescribeField, 'labels'>, string>
+
+const imageDescribeExecutionDefinition = {
+  kind: 'dynamic-step',
+  handler: 'image-describe',
+  resultStepName: 'describe',
+  fields: [
+    {
+      name: 'fields',
+      kind: 'string-array',
+      propertyName: 'fields',
+      optionFlags: '--fields',
+      description:
+        'Describe output fields to generate, for example labels or altText,title,caption,description',
+      required: false,
+    },
+    {
+      name: 'forProfile',
+      kind: 'string',
+      propertyName: 'forProfile',
+      optionFlags: '--for',
+      description: 'Use a named output profile, currently: wordpress',
+      required: false,
+    },
+    {
+      name: 'model',
+      kind: 'string',
+      propertyName: 'model',
+      optionFlags: '--model',
+      description:
+        'Model to use for generated text fields (default: anthropic/claude-4-sonnet-20250514)',
+      required: false,
+    },
+  ] as const satisfies readonly IntentOptionDefinition[],
+} satisfies IntentDynamicStepExecutionDefinition
+
+const imageDescribeCommandPresentation = {
+  description: 'Describe images as labels or publishable text fields',
+  details:
+    'Generates image labels through `/image/describe`, or structured altText/title/caption/description through `/ai/chat`, then writes the JSON result to `--out`.',
+  examples: [
+    [
+      'Describe an image as labels',
+      'transloadit image describe --input hero.jpg --out labels.json',
+    ],
+    [
+      'Generate WordPress-ready fields',
+      'transloadit image describe --input hero.jpg --for wordpress --out fields.json',
+    ],
+    [
+      'Request a custom field set',
+      'transloadit image describe --input hero.jpg --fields altText,title,caption --out fields.json',
+    ],
+  ] as Array<[string, string]>,
+} as const satisfies SemanticIntentPresentation
+
+function parseDescribeFields(value: string[] | undefined): ImageDescribeField[] {
+  const rawFields = parseStringArrayValue(value ?? [])
+  return parseUniqueEnumArray({
+    flagName: '--fields',
+    supportedValues: imageDescribeFields,
+    values: rawFields,
+  })
+}
+
+function resolveDescribeProfile(profile: string | undefined): 'wordpress' | null {
+  return parseOptionalEnumValue({
+    flagName: '--for',
+    supportedValues: ['wordpress'] as const,
+    value: profile,
+  })
+}
+
+function resolveRequestedDescribeFields({
+  explicitFields,
+  profile,
+}: {
+  explicitFields: ImageDescribeField[]
+  profile: 'wordpress' | null
+}): ImageDescribeField[] {
+  if (explicitFields.length > 0) {
+    return explicitFields
+  }
+
+  if (profile === 'wordpress') {
+    return [...wordpressDescribeFields]
+  }
+
+  return ['labels']
+}
+
+function validateDescribeFields({
+  fields,
+  model,
+  profile,
+}: {
+  fields: ImageDescribeField[]
+  model: string
+  profile: 'wordpress' | null
+}): void {
+  const includesLabels = fields.includes('labels')
+
+  if (includesLabels && fields.length > 1) {
+    throw new Error(
+      'The labels field cannot be combined with altText, title, caption, or description',
+    )
+  }
+
+  if (includesLabels && profile != null) {
+    throw new Error('--for cannot be combined with --fields labels')
+  }
+
+  if (includesLabels && model !== defaultDescribeModel) {
+    throw new Error(
+      '--model is only supported when generating altText, title, caption, or description',
+    )
+  }
+}
+
+function resolveImageDescribeRequest(rawValues: Record<string, unknown>): {
+  fields: ImageDescribeField[]
+  profile: 'wordpress' | null
+} {
+  const explicitFields = parseDescribeFields(rawValues.fields as string[] | undefined)
+  const profile = resolveDescribeProfile(rawValues.forProfile as string | undefined)
+  const fields = resolveRequestedDescribeFields({ explicitFields, profile })
+  validateDescribeFields({
+    fields,
+    model: String(rawValues.model ?? defaultDescribeModel),
+    profile,
+  })
+
+  return { fields, profile }
+}
+
+function buildDescribeAiChatSchema(fields: readonly ImageDescribeField[]): Record<string, unknown> {
+  const properties = Object.fromEntries(
+    fields.map((field) => {
+      return [
+        field,
+        {
+          type: 'string',
+          description: describeFieldDescriptions[field as Exclude<ImageDescribeField, 'labels'>],
+        },
+      ]
+    }),
+  )
+
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: [...fields],
+    properties,
+  }
+}
+
+function buildDescribeAiChatMessages({
+  fields,
+  profile,
+}: {
+  fields: readonly ImageDescribeField[]
+  profile: 'wordpress' | null
+}): {
+  messages: string
+  systemMessage: string
+} {
+  const requestedFields = fields.join(', ')
+  const profileHint =
+    profile === 'wordpress'
+      ? 'The output is for the WordPress media library.'
+      : 'The output is for a publishing workflow.'
+
+  return {
+    systemMessage: [
+      'You generate accurate image copy for publishing workflows.',
+      profileHint,
+      'Return only the schema fields requested.',
+      'Be concrete, concise, and faithful to what is visibly present in the image.',
+      'Do not invent facts, brands, locations, or identities that are not clearly visible.',
+      'Avoid keyword stuffing, hype, and mentions of SEO or accessibility in the output itself.',
+      'For altText, write one objective sentence focused on what matters to someone who cannot see the image.',
+      'For title, keep it short and natural.',
+      'For caption, write one short sentence suitable for publication.',
+      'For description, write one or two sentences with slightly more context than the caption.',
+    ].join(' '),
+    messages: `Analyze the attached image and fill these fields: ${requestedFields}.`,
+  }
+}
+
+function createImageDescribeStep(
+  rawValues: Record<string, unknown>,
+  _context: { hasInputs: boolean },
+): Record<string, unknown> {
+  const { fields, profile } = resolveImageDescribeRequest(rawValues)
+  if (fields.length === 1 && fields[0] === 'labels') {
+    return {
+      robot: '/image/describe',
+      use: ':original',
+      result: true,
+      provider: 'aws',
+      format: 'json',
+      granularity: 'list',
+      explicit_descriptions: false,
+    }
+  }
+
+  const { messages, systemMessage } = buildDescribeAiChatMessages({ fields, profile })
+
+  return {
+    robot: '/ai/chat',
+    use: ':original',
+    result: true,
+    model: String(rawValues.model ?? defaultDescribeModel),
+    format: 'json',
+    return_messages: 'last',
+    test_credentials: true,
+    schema: JSON.stringify(buildDescribeAiChatSchema(fields)),
+    messages,
+    system_message: systemMessage,
+    // @TODO Move these inline /ai/chat instructions into a builtin template in api2 and
+    // switch this command to call that builtin instead of shipping prompt logic in the CLI.
+  }
+}
+
+export const imageDescribeSemanticIntentDescriptor = {
+  createStep: createImageDescribeStep,
+  execution: imageDescribeExecutionDefinition,
+  inputPolicy: { kind: 'required' },
+  outputDescription: 'Write the JSON result to this path or directory',
+  presentation: imageDescribeCommandPresentation,
+  runnerKind: 'watchable',
+} as const satisfies SemanticIntentDescriptor

package/src/cli/semanticIntents/imageGenerate.ts

@@ -0,0 +1,254 @@
+import { basename } from 'node:path'
+import type { IntentOptionDefinition, PreparedIntentInputs } from '../intentRuntime.ts'
+import type { SemanticIntentDescriptor, SemanticIntentPresentation } from './index.ts'
+import { parseOptionalEnumValue } from './parsing.ts'
+
+const defaultImageGenerateModel = 'google/nano-banana-2'
+const imageGenerateFormats = ['jpeg', 'jpg', 'png', 'gif', 'webp', 'svg'] as const
+
+const imageGenerateOptionDefinitions = [
+  {
+    name: 'prompt',
+    kind: 'string',
+    propertyName: 'prompt',
+    optionFlags: '--prompt',
+    description: 'The prompt describing the desired image content.',
+    required: true,
+    exampleValue: JSON.stringify('A red bicycle in a studio'),
+  },
+  {
+    name: 'model',
+    kind: 'string',
+    propertyName: 'model',
+    optionFlags: '--model',
+    description: `The AI model to use for image generation. Defaults to ${defaultImageGenerateModel}.`,
+    required: false,
+    exampleValue: defaultImageGenerateModel,
+  },
+  {
+    name: 'format',
+    kind: 'string',
+    propertyName: 'format',
+    optionFlags: '--format',
+    description: 'Format of the generated image.',
+    required: false,
+    exampleValue: 'jpg',
+  },
+  {
+    name: 'seed',
+    kind: 'number',
+    propertyName: 'seed',
+    optionFlags: '--seed',
+    description: 'Seed for the random number generator.',
+    required: false,
+  },
+  {
+    name: 'aspectRatio',
+    kind: 'string',
+    propertyName: 'aspectRatio',
+    optionFlags: '--aspect-ratio',
+    description: 'Aspect ratio of the generated image.',
+    required: false,
+  },
+  {
+    name: 'height',
+    kind: 'number',
+    propertyName: 'height',
+    optionFlags: '--height',
+    description: 'Height of the generated image.',
+    required: false,
+  },
+  {
+    name: 'width',
+    kind: 'number',
+    propertyName: 'width',
+    optionFlags: '--width',
+    description: 'Width of the generated image.',
+    required: false,
+  },
+  {
+    name: 'style',
+    kind: 'string',
+    propertyName: 'style',
+    optionFlags: '--style',
+    description: 'Style of the generated image.',
+    required: false,
+  },
+  {
+    name: 'numOutputs',
+    kind: 'number',
+    propertyName: 'numOutputs',
+    optionFlags: '--num-outputs',
+    description: 'Number of image variants to generate.',
+    required: false,
+  },
+] as const satisfies readonly IntentOptionDefinition[]
+
+const imageGenerateCommandPresentation = {
+  description: 'Generate images from text prompts',
+  details:
+    'Runs `/image/generate`. Without inputs, this is text-to-image. With one or more `--input` files, the inputs are bundled into a single assembly so the prompt can refer to them by filename.',
+  examples: [
+    [
+      'Generate an image from text',
+      'transloadit image generate --prompt "A red bicycle in a studio" --out output.png',
+    ],
+    [
+      'Guide generation with one input image',
+      'transloadit image generate --input subject.jpg --prompt "Place subject.jpg on a magazine cover" --out output.png',
+    ],
+    [
+      'Guide generation with multiple input images',
+      'transloadit image generate --input person1.jpg --input person2.jpg --input background.jpg --prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" --out output.png',
+    ],
+  ] as Array<[string, string]>,
+} as const satisfies SemanticIntentPresentation
+
+function parseOptionalFormat(value: unknown): (typeof imageGenerateFormats)[number] | null {
+  return parseOptionalEnumValue({
+    flagName: '--format',
+    supportedValues: imageGenerateFormats,
+    value,
+  })
+}
+
+function parseRequiredPrompt(value: unknown): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('image generate requires --prompt')
+  }
+
+  return value
+}
+
+function parseOptionalNumber(flagName: string, value: unknown): number | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+
+  const numericValue = typeof value === 'number' ? value : Number(String(value).trim())
+  if (Number.isNaN(numericValue)) {
+    throw new Error(`${flagName} must be a number`)
+  }
+
+  return numericValue
+}
+
+function parseOptionalIntegerRange(
+  flagName: string,
+  value: unknown,
+  { max, min }: { max: number; min: number },
+): number | undefined {
+  const numericValue = parseOptionalNumber(flagName, value)
+  if (numericValue == null) {
+    return undefined
+  }
+
+  if (!Number.isInteger(numericValue) || numericValue < min || numericValue > max) {
+    throw new Error(`${flagName} must be an integer between ${min} and ${max}`)
+  }
+
+  return numericValue
+}
+
+function createImageGenerateStep(
+  rawValues: Record<string, unknown>,
+  context: { hasInputs: boolean },
+): Record<string, unknown> {
+  const step: Record<string, unknown> = {
+    robot: '/image/generate',
+    result: true,
+    model: defaultImageGenerateModel,
+    prompt: parseRequiredPrompt(rawValues.prompt),
+  }
+
+  if (context.hasInputs) {
+    step.use = {
+      steps: [':original'],
+      bundle_steps: true,
+    }
+  }
+
+  const model = rawValues.model
+  if (typeof model === 'string' && model.trim() !== '') {
+    step.model = model
+  }
+
+  const format = parseOptionalFormat(rawValues.format)
+  if (format != null) {
+    step.format = format
+  }
+
+  const seed = parseOptionalNumber('--seed', rawValues.seed)
+  if (seed != null) {
+    step.seed = seed
+  }
+
+  const aspectRatio = rawValues.aspectRatio
+  if (typeof aspectRatio === 'string' && aspectRatio.trim() !== '') {
+    step.aspect_ratio = aspectRatio
+  }
+
+  const height = parseOptionalNumber('--height', rawValues.height)
+  if (height != null) {
+    step.height = height
+  }
+
+  const width = parseOptionalNumber('--width', rawValues.width)
+  if (width != null) {
+    step.width = width
+  }
+
+  const style = rawValues.style
+  if (typeof style === 'string' && style.trim() !== '') {
+    step.style = style
+  }
+
+  const numOutputs = parseOptionalIntegerRange('--num-outputs', rawValues.numOutputs, {
+    min: 1,
+    max: 10,
+  })
+  if (numOutputs != null) {
+    step.num_outputs = numOutputs
+  }
+
+  return step
+}
+
+function ensureUniqueInputBasenames(preparedInputs: PreparedIntentInputs): PreparedIntentInputs {
+  const seenBasenames = new Map<string, string>()
+
+  for (const input of preparedInputs.inputs) {
+    const inputBasename = basename(input)
+    const previousInput = seenBasenames.get(inputBasename)
+    if (previousInput != null) {
+      throw new Error(
+        `image generate requires unique input basenames when prompts refer to files; found duplicate ${inputBasename} in ${previousInput} and ${input}`,
+      )
+    }
+
+    seenBasenames.set(inputBasename, input)
+  }
+
+  return preparedInputs
+}
+
+export const imageGenerateSemanticIntentDescriptor = {
+  createStep: createImageGenerateStep,
+  execution: {
+    kind: 'dynamic-step',
+    handler: 'image-generate',
+    resultStepName: 'generate',
+    fields: imageGenerateOptionDefinitions,
+  },
+  inputPolicy: {
+    kind: 'optional',
+    field: 'prompt',
+    attachUseWhenInputsProvided: false,
+  },
+  outputDescription: 'Write the result to this path',
+  async prepareInputs(preparedInputs) {
+    return await Promise.resolve(ensureUniqueInputBasenames(preparedInputs))
+  },
+  presentation: imageGenerateCommandPresentation,
+  runnerKind: 'bundled',
+} as const satisfies SemanticIntentDescriptor