transloadit 4.7.4 → 4.7.6

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,254 @@
+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>): 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/index.ts

@@ -0,0 +1,48 @@
+import type { IntentInputPolicy } from '../intentInputPolicy.ts'
+import type {
+  IntentDynamicStepExecutionDefinition,
+  IntentRunnerKind,
+  PreparedIntentInputs,
+} from '../intentRuntime.ts'
+import { imageDescribeSemanticIntentDescriptor } from './imageDescribe.ts'
+import {
+  markdownDocxSemanticIntentDescriptor,
+  markdownPdfSemanticIntentDescriptor,
+} from './markdownPdf.ts'
+
+export interface SemanticIntentPresentation {
+  description: string
+  details: string
+  examples: Array<[string, string]>
+}
+
+export interface SemanticIntentDescriptor {
+  createStep: (rawValues: Record<string, unknown>) => Record<string, unknown>
+  execution: IntentDynamicStepExecutionDefinition
+  inputPolicy: IntentInputPolicy
+  outputDescription: string
+  prepareInputs?: (
+    preparedInputs: PreparedIntentInputs,
+    rawValues: Record<string, unknown>,
+  ) => Promise<PreparedIntentInputs>
+  presentation: SemanticIntentPresentation
+  runnerKind: IntentRunnerKind
+}
+
+const semanticIntentDescriptors: Record<string, SemanticIntentDescriptor> = {
+  'image-describe': imageDescribeSemanticIntentDescriptor,
+  'markdown-pdf': {
+    ...markdownPdfSemanticIntentDescriptor,
+  },
+  'markdown-docx': {
+    ...markdownDocxSemanticIntentDescriptor,
+  },
+}
+
+export function getSemanticIntentDescriptor(name: string): SemanticIntentDescriptor {
+  if (!(name in semanticIntentDescriptors)) {
+    throw new Error(`Semantic intent descriptor does not exist for "${name}"`)
+  }
+
+  return semanticIntentDescriptors[name]
+}

package/src/cli/semanticIntents/markdownPdf.ts

@@ -0,0 +1,120 @@
+import type { IntentOptionDefinition } from '../intentRuntime.ts'
+import type { SemanticIntentDescriptor, SemanticIntentPresentation } from './index.ts'
+import { parseOptionalEnumValue } from './parsing.ts'
+
+const defaultMarkdownFormat = 'gfm'
+const defaultMarkdownTheme = 'github'
+const markdownFormats = ['commonmark', 'gfm'] as const
+const markdownThemes = ['bare', 'github'] as const
+
+function resolveMarkdownFormat(value: unknown): 'commonmark' | 'gfm' {
+  return (
+    parseOptionalEnumValue({
+      flagName: '--markdown-format',
+      supportedValues: markdownFormats,
+      value,
+    }) ?? defaultMarkdownFormat
+  )
+}
+
+function resolveMarkdownTheme(value: unknown): 'bare' | 'github' {
+  return (
+    parseOptionalEnumValue({
+      flagName: '--markdown-theme',
+      supportedValues: markdownThemes,
+      value,
+    }) ?? defaultMarkdownTheme
+  )
+}
+
+const markdownOptionDefinitions = [
+  {
+    name: 'markdownFormat',
+    kind: 'string',
+    propertyName: 'markdownFormat',
+    optionFlags: '--markdown-format',
+    description: 'Markdown variant to parse, either commonmark or gfm',
+    required: false,
+  },
+  {
+    name: 'markdownTheme',
+    kind: 'string',
+    propertyName: 'markdownTheme',
+    optionFlags: '--markdown-theme',
+    description: 'Markdown theme to render, either github or bare',
+    required: false,
+  },
+] as const satisfies readonly IntentOptionDefinition[]
+
+function createMarkdownConvertSemanticIntent({
+  description,
+  details,
+  exampleOutput,
+  format,
+  handler,
+}: {
+  description: string
+  details: string
+  exampleOutput: string
+  format: 'docx' | 'pdf'
+  handler: 'markdown-docx' | 'markdown-pdf'
+}): SemanticIntentDescriptor {
+  const formatLabel = format.toUpperCase()
+  const presentation = {
+    description,
+    details,
+    examples: [
+      [
+        `Render a Markdown file as a ${formatLabel} file`,
+        `transloadit markdown ${format} --input README.md --out ${exampleOutput}`,
+      ],
+      [
+        'Print a temporary result URL without downloading locally',
+        `transloadit markdown ${format} --input README.md --print-urls`,
+      ],
+    ],
+  } satisfies SemanticIntentPresentation
+
+  return {
+    createStep(rawValues) {
+      return {
+        robot: '/document/convert',
+        use: ':original',
+        result: true,
+        format,
+        markdown_format: resolveMarkdownFormat(rawValues.markdownFormat),
+        markdown_theme: resolveMarkdownTheme(rawValues.markdownTheme),
+        // @TODO Replace this semantic CLI alias with a builtin/api2-owned command surface if we later
+        // want richer Markdown conversion semantics beyond `/document/convert`.
+      }
+    },
+    execution: {
+      kind: 'dynamic-step',
+      handler,
+      resultStepName: 'convert',
+      fields: markdownOptionDefinitions,
+    },
+    inputPolicy: { kind: 'required' },
+    outputDescription: `Write the rendered ${formatLabel} to this path or directory`,
+    presentation,
+    runnerKind: 'watchable',
+  }
+}
+
+export const markdownPdfSemanticIntentDescriptor = createMarkdownConvertSemanticIntent({
+  description: 'Render Markdown files as PDFs',
+  details:
+    'Runs `/document/convert` with `format: pdf`, letting the backend render Markdown and preserve features such as internal heading links in the generated PDF.',
+  exampleOutput: 'README.pdf',
+  format: 'pdf',
+  handler: 'markdown-pdf',
+})
+
+export const markdownDocxSemanticIntentDescriptor = createMarkdownConvertSemanticIntent({
+  description: 'Render Markdown files as DOCX documents',
+  details:
+    'Runs `/document/convert` with `format: docx`, letting the backend render Markdown and convert it into a Word document.',
+  exampleOutput: 'README.docx',
+  format: 'docx',
+  handler: 'markdown-docx',
+})

package/src/cli/semanticIntents/parsing.ts

@@ -0,0 +1,56 @@
+export function parseOptionalEnumValue<TValue extends string>({
+  flagName,
+  supportedValues,
+  value,
+}: {
+  flagName: string
+  supportedValues: readonly TValue[]
+  value: unknown
+}): TValue | null {
+  if (value == null || value === '') {
+    return null
+  }
+
+  if (typeof value === 'string' && supportedValues.includes(value as TValue)) {
+    return value as TValue
+  }
+
+  throw new Error(
+    `Unsupported ${flagName} value "${String(value)}". Supported values: ${supportedValues.join(', ')}`,
+  )
+}
+
+export function parseUniqueEnumArray<TValue extends string>({
+  flagName,
+  supportedValues,
+  values,
+}: {
+  flagName: string
+  supportedValues: readonly TValue[]
+  values: readonly string[]
+}): TValue[] {
+  if (values.length === 0) {
+    return []
+  }
+
+  const parsedValues: TValue[] = []
+  const seen = new Set<TValue>()
+
+  for (const value of values) {
+    if (!supportedValues.includes(value as TValue)) {
+      throw new Error(
+        `Unsupported ${flagName} value "${value}". Supported values: ${supportedValues.join(', ')}`,
+      )
+    }
+
+    const parsedValue = value as TValue
+    if (seen.has(parsedValue)) {
+      continue
+    }
+
+    seen.add(parsedValue)
+    parsedValues.push(parsedValue)
+  }
+
+  return parsedValues
+}

package/src/cli/stepsInput.ts

@@ -0,0 +1,32 @@
+import fsp from 'node:fs/promises'
+
+import type { StepsInput } from '../alphalib/types/template.ts'
+import { stepsSchema } from '../alphalib/types/template.ts'
+
+export function parseStepsInputJson(content: string): StepsInput {
+  const parsed: unknown = JSON.parse(content)
+  const validated = stepsSchema.safeParse(parsed)
+  if (!validated.success) {
+    throw new Error(`Invalid steps format: ${validated.error.message}`)
+  }
+
+  const parsedSteps = parsed as Record<string, Record<string, unknown>>
+  const validatedSteps = validated.data as Record<string, Record<string, unknown>>
+
+  return Object.fromEntries(
+    Object.entries(parsedSteps).map(([stepName, stepInput]) => {
+      const normalizedStep = validatedSteps[stepName] ?? {}
+      return [
+        stepName,
+        Object.fromEntries(
+          Object.keys(stepInput).map((key) => [key, normalizedStep[key] ?? stepInput[key]]),
+        ),
+      ]
+    }),
+  ) as StepsInput
+}
+
+export async function readStepsInputFile(filePath: string): Promise<StepsInput> {
+  const content = await fsp.readFile(filePath, 'utf8')
+  return parseStepsInputJson(content)
+}