transloadit 4.7.4 → 4.8.0

package/src/cli/semanticIntents/index.ts

@@ -0,0 +1,53 @@
+import type { IntentInputPolicy } from '../intentInputPolicy.ts'
+import type {
+  IntentDynamicStepExecutionDefinition,
+  IntentRunnerKind,
+  PreparedIntentInputs,
+} from '../intentRuntime.ts'
+import { imageDescribeSemanticIntentDescriptor } from './imageDescribe.ts'
+import { imageGenerateSemanticIntentDescriptor } from './imageGenerate.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>,
+    context: { hasInputs: boolean },
+  ) => 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,
+  'image-generate': imageGenerateSemanticIntentDescriptor,
+  '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, _context) {
+      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)
+}

package/src/cli.ts

@@ -6,6 +6,7 @@ import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 import 'dotenv/config'
 import { createCli } from './cli/commands/index.ts'
+import { ensureError } from './cli/types.ts'
 
 const currentFile = realpathSync(fileURLToPath(import.meta.url))
 
@@ -32,13 +33,13 @@ export async function main(args = process.argv.slice(2)): Promise<void> {
   }
 }
 
-export function runCliWhenExecuted(): void {
+export async function runCliWhenExecuted(): Promise<void> {
   if (!shouldRunCli(process.argv[1])) return
 
-  void main().catch((error) => {
-    console.error((error as Error).message)
+  await main().catch((error) => {
+    console.error(ensureError(error).message)
     process.exitCode = 1
   })
 }
 
-runCliWhenExecuted()
+await runCliWhenExecuted()

package/src/ensureUniqueCounter.ts

@@ -0,0 +1,75 @@
+const uniqueCounterScopes = new WeakMap<object, Promise<void>>()
+
+async function runEnsureUniqueCounterValue<T>({
+  initialValue,
+  isTaken,
+  reserve,
+  nextValue,
+}: {
+  initialValue: T
+  isTaken: (candidate: T) => Promise<boolean> | boolean
+  reserve: (candidate: T) => void
+  nextValue: (counter: number) => T
+}): Promise<T> {
+  let candidate = initialValue
+  let counter = 1
+
+  while (await isTaken(candidate)) {
+    candidate = nextValue(counter)
+    counter += 1
+  }
+
+  reserve(candidate)
+  return candidate
+}
+
+export async function ensureUniqueCounterValue<T>({
+  initialValue,
+  isTaken,
+  reserve,
+  nextValue,
+  scope,
+}: {
+  initialValue: T
+  isTaken: (candidate: T) => Promise<boolean> | boolean
+  reserve: (candidate: T) => void
+  nextValue: (counter: number) => T
+  scope?: object
+}): Promise<T> {
+  if (scope == null) {
+    return await runEnsureUniqueCounterValue({
+      initialValue,
+      isTaken,
+      reserve,
+      nextValue,
+    })
+  }
+
+  const previous = uniqueCounterScopes.get(scope) ?? Promise.resolve()
+  let releaseScope: (() => void) | undefined
+  const pendingScope = new Promise<void>((resolve) => {
+    releaseScope = resolve
+  })
+  const currentScope = previous
+    .catch(() => undefined)
+    .then(async () => {
+      await pendingScope
+    })
+  uniqueCounterScopes.set(scope, currentScope)
+
+  await previous.catch(() => undefined)
+
+  try {
+    return await runEnsureUniqueCounterValue({
+      initialValue,
+      isTaken,
+      reserve,
+      nextValue,
+    })
+  } finally {
+    releaseScope?.()
+    if (uniqueCounterScopes.get(scope) === currentScope) {
+      uniqueCounterScopes.delete(scope)
+    }
+  }
+}