transloadit 4.8.1 → 4.8.2

package/src/cli/generateIntentDocs.ts

@@ -182,11 +182,12 @@ function getSharedFileInputOutputRows(): DocOptionRow[] {
     getInputPathsOptionDocumentation(),
     getInputBase64OptionDocumentation(),
     {
-      flags: '--out, -o',
+      flags: '--output, -o',
       type: 'path',
-      required: 'yes*',
+      required: 'no',
       example: 'output.file',
-      description: 'Write the result to this path or directory',
+      description:
+        'Write the result to this path or directory. If omitted, the CLI infers a local output path.',
     },
     getPrintUrlsOptionDocumentation(),
   ]
@@ -195,11 +196,11 @@ function getSharedFileInputOutputRows(): DocOptionRow[] {
 function getSharedNoInputOutputRows(): DocOptionRow[] {
   return [
     {
-      flags: '--out, -o',
+      flags: '--output, -o',
       type: 'path',
-      required: 'yes*',
+      required: 'no',
       example: 'output.file',
-      description: 'Write the result to this path',
+      description: 'Write the result to this path. If omitted, the CLI infers a local output path.',
     },
     getPrintUrlsOptionDocumentation(),
   ]
@@ -349,7 +350,7 @@ export function renderIntentDocsBody({
     '',
     renderAtAGlanceTable(definitions),
     '',
-    '> At least one of `--out` or `--print-urls` is required on every intent command.',
+    '> If you omit `--output`, the CLI writes next to a single local file input when it can, otherwise it falls back to the current working directory. Use `--print-urls` alone when you want URLs without downloading locally.',
     '',
     `${heading} Shared flags`,
     '',

package/src/cli/intentCommands.ts

@@ -278,7 +278,7 @@ function inferExamples(
     }
 
     return [
-      ['Run the command', `transloadit ${spec.paths.join(' ')} --input input.mp4 --out output/`],
+      ['Run the command', `transloadit ${spec.paths.join(' ')} --input input.mp4 --output output/`],
     ]
   }
 
@@ -310,7 +310,7 @@ function inferExamples(
   }
 
   const outputMode = spec.intentDefinition.outputMode ?? 'file'
-  parts.push('--out', inferOutputPath(spec.paths, outputMode, fieldSpecs))
+  parts.push('--output', inferOutputPath(spec.paths, outputMode, fieldSpecs))
 
   return [['Run the command', parts.join(' ')]]
 }
@@ -355,11 +355,13 @@ function resolveRobotIntent(definition: RobotIntentDefinition): BuiltIntentComma
       input.kind === 'none'
         ? {
             execution,
+            defaultOutputPath: inferOutputPath(paths, outputMode, fieldSpecs),
             outputDescription: 'Write the result to this path',
             outputMode,
           }
         : {
             commandLabel,
+            defaultOutputPath: inferOutputPath(paths, outputMode, fieldSpecs),
             execution,
             inputPolicy: input.inputPolicy,
             outputDescription:
@@ -388,18 +390,18 @@ function getIntentDetails({
   robot: string
 }): string {
   if (inputMode === 'none') {
-    return `Runs \`${robot}\` and writes the result to \`--out\`.`
+    return `Runs \`${robot}\` and writes the result to \`--output\`.`
   }
 
   if (defaultSingleAssembly) {
-    return `Runs \`${robot}\` for the provided inputs and writes the result to \`--out\`.`
+    return `Runs \`${robot}\` for the provided inputs and writes the result to \`--output\`.`
   }
 
   if (outputMode === 'directory') {
-    return `Runs \`${robot}\` on each input file and writes the results to \`--out\`.`
+    return `Runs \`${robot}\` on each input file and writes the results to \`--output\`.`
   }
 
-  return `Runs \`${robot}\` on each input file and writes the result to \`--out\`.`
+  return `Runs \`${robot}\` on each input file and writes the result to \`--output\`.`
 }
 
 function resolveSemanticIntent(definition: SemanticIntentDefinition): BuiltIntentCommandDefinition {
@@ -415,6 +417,7 @@ function resolveSemanticIntent(definition: SemanticIntentDefinition): BuiltInten
     runnerKind: descriptor.runnerKind,
     intentDefinition: {
       commandLabel: paths.join(' '),
+      defaultOutputPath: descriptor.defaultOutputPath,
       execution: descriptor.execution,
       inputPolicy: descriptor.inputPolicy,
       outputDescription: descriptor.outputDescription,
@@ -430,12 +433,13 @@ function resolveTemplateIntent(
   const spec: BuiltIntentCommandDefinition = {
     className: `${toPascalCase(paths)}Command`,
     description: `Run ${stripTrailingPunctuation(definition.templateId)}`,
-    details: `Runs the \`${definition.templateId}\` template and writes the outputs to \`--out\`.`,
+    details: `Runs the \`${definition.templateId}\` template and writes the outputs to \`--output\`.`,
     examples: [],
     paths,
     runnerKind: 'standard',
     intentDefinition: {
       commandLabel: paths.join(' '),
+      defaultOutputPath: inferOutputPath(paths, outputMode, []),
       execution: {
         kind: 'template',
         templateId: definition.templateId,

package/src/cli/intentRuntime.ts

@@ -1,5 +1,5 @@
 import { statSync } from 'node:fs'
-import { basename } from 'node:path'
+import { basename, dirname, join, parse, resolve } from 'node:path'
 import { Option } from 'clipanion'
 import type { z } from 'zod'
 
@@ -59,6 +59,7 @@ export type IntentFileExecutionDefinition =
 
 export interface IntentFileCommandDefinition {
   commandLabel: string
+  defaultOutputPath: string
   execution: IntentFileExecutionDefinition
   inputPolicy: IntentInputPolicy
   outputDescription: string
@@ -66,6 +67,7 @@ export interface IntentFileCommandDefinition {
 }
 
 export interface IntentNoInputCommandDefinition {
+  defaultOutputPath: string
   execution: IntentSingleStepExecutionDefinition
   outputDescription: string
   outputMode?: 'directory' | 'file'
@@ -338,6 +340,7 @@ async function executeIntentCommand({
   client,
   definition,
   output,
+  outputMode,
   outputPath,
   printUrls,
   rawValues,
@@ -347,6 +350,7 @@ async function executeIntentCommand({
   createOptions: Omit<AssembliesCreateOptions, 'output' | 'steps' | 'stepsData' | 'template'>
   definition: IntentFileCommandDefinition | IntentNoInputCommandDefinition
   output: AuthenticatedCommand['output']
+  outputMode?: 'directory' | 'file'
   outputPath?: string
   printUrls: boolean
   rawValues: Record<string, unknown>
@@ -379,7 +383,7 @@ async function executeIntentCommand({
   const { hasFailures, resultUrls } = await assembliesCommands.create(output, client, {
     ...createOptions,
     output: outputPath ?? null,
-    outputMode: definition.outputMode,
+    outputMode,
     ...executionOptions,
   })
   if (printUrls) {
@@ -391,7 +395,8 @@ async function executeIntentCommand({
 abstract class GeneratedIntentCommandBase extends AuthenticatedCommand {
   declare static intentDefinition: IntentFileCommandDefinition | IntentNoInputCommandDefinition
 
-  outputPath = Option.String('--out,-o', {
+  // Intents standardize on --output while the surface is still young enough to change cleanly.
+  outputPath = Option.String('--output,-o', {
     description: this.getOutputDescription(),
   })
 
@@ -410,23 +415,58 @@ abstract class GeneratedIntentCommandBase extends AuthenticatedCommand {
     return this.getIntentDefinition().outputDescription
   }
 
-  protected validateOutputChoice(): number | undefined {
-    if (this.outputPath == null && !this.printUrls) {
-      this.output.error('Specify at least one of --out or --print-urls')
-      return 1
+  protected resolveDefaultOutputPath(rawValues: Record<string, unknown>): string | undefined {
+    const defaultOutputPath = this.getIntentDefinition().defaultOutputPath
+    if (this.getIntentDefinition().outputMode === 'directory') {
+      return defaultOutputPath
     }
 
-    return undefined
+    const format = rawValues.format
+    if (typeof format !== 'string') {
+      return defaultOutputPath
+    }
+
+    const trimmedFormat = format.trim().toLowerCase()
+    if (!/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(trimmedFormat)) {
+      return defaultOutputPath
+    }
+
+    const parsedDefaultOutputPath = parse(defaultOutputPath)
+    const outputBasename =
+      parsedDefaultOutputPath.name === ''
+        ? basename(defaultOutputPath, parsedDefaultOutputPath.ext)
+        : parsedDefaultOutputPath.name
+
+    return join(parsedDefaultOutputPath.dir, `${outputBasename}.${trimmedFormat}`)
+  }
+
+  protected getDefaultOutputPath(rawValues: Record<string, unknown>): string | undefined {
+    return this.resolveDefaultOutputPath(rawValues)
+  }
+
+  protected getEffectiveOutputPath(rawValues: Record<string, unknown>): string | undefined {
+    if (this.outputPath != null) {
+      return this.outputPath
+    }
+
+    if (this.printUrls) {
+      return undefined
+    }
+
+    return this.getDefaultOutputPath(rawValues)
+  }
+
+  protected getEffectiveOutputMode(
+    _rawValues: Record<string, unknown>,
+    _outputPath: string | undefined,
+  ): 'directory' | 'file' | undefined {
+    return this.getIntentDefinition().outputMode
   }
 }
 
 export abstract class GeneratedNoInputIntentCommand extends GeneratedIntentCommandBase {
   protected override async run(): Promise<number | undefined> {
-    const outputValidationError = this.validateOutputChoice()
-    if (outputValidationError != null) {
-      return outputValidationError
-    }
-
+    const rawValues = this.getIntentRawValues()
     return await executeIntentCommand({
       client: this.client,
       createOptions: {
@@ -434,9 +474,10 @@ export abstract class GeneratedNoInputIntentCommand extends GeneratedIntentComma
       },
       definition: this.getIntentDefinition() as IntentNoInputCommandDefinition,
       output: this.output,
-      outputPath: this.outputPath,
+      outputMode: this.getEffectiveOutputMode(rawValues, this.getEffectiveOutputPath(rawValues)),
+      outputPath: this.getEffectiveOutputPath(rawValues),
       printUrls: this.printUrls ?? false,
-      rawValues: this.getIntentRawValues(),
+      rawValues,
     })
   }
 }
@@ -481,6 +522,126 @@ abstract class GeneratedFileIntentCommandBase extends GeneratedIntentCommandBase
     return super.getIntentDefinition() as IntentFileCommandDefinition
   }
 
+  protected getSingleFilesystemFileInput(): string | null {
+    if ((this.inputBase64?.length ?? 0) > 0) {
+      return null
+    }
+
+    const localInputs = (this.inputs ?? []).filter((input) => input !== '-' && !isHttpUrl(input))
+    if (localInputs.length !== 1) {
+      return null
+    }
+
+    const candidate = localInputs[0]
+    if (candidate == null) {
+      return null
+    }
+
+    try {
+      return statSync(candidate).isFile() ? candidate : null
+    } catch {
+      return null
+    }
+  }
+
+  protected hasDirectoryInput(): boolean {
+    return (this.inputs ?? []).some((input) => {
+      if (input === '-' || isHttpUrl(input)) {
+        return false
+      }
+
+      try {
+        return statSync(input).isDirectory()
+      } catch {
+        return false
+      }
+    })
+  }
+
+  protected prefersDirectoryDefaultOutput(): boolean {
+    return this.getIntentDefinition().outputMode === 'directory'
+  }
+
+  protected getSuggestedDirectoryOutputPath(): string {
+    if (this.getIntentDefinition().outputMode === 'directory') {
+      return this.resolveDefaultOutputPath({}) ?? 'output/'
+    }
+
+    return 'output/'
+  }
+
+  private getSafeSiblingDirectoryOutputPath(inputPath: string): string {
+    const parsedInputPath = parse(inputPath)
+    const candidateBaseName =
+      parsedInputPath.name === '' ? basename(inputPath) : parsedInputPath.name
+    const candidateDirectoryPath = join(dirname(inputPath), candidateBaseName)
+
+    const isSafeDirectoryCandidate = (candidatePath: string): boolean => {
+      if (resolve(candidatePath) === resolve(inputPath)) {
+        return false
+      }
+
+      try {
+        return statSync(candidatePath).isDirectory()
+      } catch {
+        return true
+      }
+    }
+
+    if (isSafeDirectoryCandidate(candidateDirectoryPath)) {
+      return candidateDirectoryPath
+    }
+
+    for (let suffixIndex = 0; suffixIndex < 1000; suffixIndex += 1) {
+      const suffix = suffixIndex === 0 ? '-output' : `-output-${suffixIndex + 1}`
+      const fallbackDirectoryPath = join(dirname(inputPath), `${candidateBaseName}${suffix}`)
+      if (isSafeDirectoryCandidate(fallbackDirectoryPath)) {
+        return fallbackDirectoryPath
+      }
+    }
+
+    throw new Error(`Could not infer a safe output directory path for ${inputPath}`)
+  }
+
+  protected getSiblingOutputPath(inputPath: string, rawValues: Record<string, unknown>): string {
+    if (this.getIntentDefinition().outputMode === 'directory') {
+      return this.getSafeSiblingDirectoryOutputPath(inputPath)
+    }
+
+    const resolvedDefaultOutputPath = this.resolveDefaultOutputPath(rawValues)
+    const extension = parse(
+      resolvedDefaultOutputPath ?? this.getIntentDefinition().defaultOutputPath,
+    ).ext
+    const parsedInputPath = parse(inputPath)
+    const candidateOutputPath = join(dirname(inputPath), `${parsedInputPath.name}${extension}`)
+    if (resolve(candidateOutputPath) !== resolve(inputPath)) {
+      return candidateOutputPath
+    }
+
+    return join(dirname(inputPath), `${parsedInputPath.name}-output${extension}`)
+  }
+
+  protected override getDefaultOutputPath(rawValues: Record<string, unknown>): string | undefined {
+    if (this.prefersDirectoryDefaultOutput()) {
+      const singleFilesystemFileInput = this.getSingleFilesystemFileInput()
+      if (
+        this.getIntentDefinition().outputMode === 'directory' &&
+        singleFilesystemFileInput != null
+      ) {
+        return this.getSiblingOutputPath(singleFilesystemFileInput, rawValues)
+      }
+
+      return this.getSuggestedDirectoryOutputPath()
+    }
+
+    const singleFilesystemFileInput = this.getSingleFilesystemFileInput()
+    if (singleFilesystemFileInput != null) {
+      return this.getSiblingOutputPath(singleFilesystemFileInput, rawValues)
+    }
+
+    return this.resolveDefaultOutputPath(rawValues)
+  }
+
   protected async prepareInputs(): Promise<PreparedIntentInputs> {
     return await prepareIntentInputs({
       inputValues: this.inputs ?? [],
@@ -513,24 +674,39 @@ abstract class GeneratedFileIntentCommandBase extends GeneratedIntentCommandBase
     )
   }
 
-  protected resolveOutputMode(): 'directory' | 'file' | undefined {
+  protected resolveOutputMode(outputPath: string | undefined): 'directory' | 'file' | undefined {
     if (this.getIntentDefinition().outputMode != null) {
       return this.getIntentDefinition().outputMode
     }
 
-    if (this.outputPath == null) {
+    if (outputPath == null) {
       return undefined
     }
 
+    if (this.outputPath == null && this.prefersDirectoryDefaultOutput()) {
+      return 'directory'
+    }
+
+    if (/[\\/]$/.test(outputPath)) {
+      return 'directory'
+    }
+
     try {
-      return statSync(this.outputPath).isDirectory() ? 'directory' : 'file'
+      return statSync(outputPath).isDirectory() ? 'directory' : 'file'
     } catch {
       return 'file'
     }
   }
 
   protected isDirectoryOutputTarget(): boolean {
-    return this.resolveOutputMode() === 'directory'
+    return this.resolveOutputMode(this.outputPath) === 'directory'
+  }
+
+  protected override getEffectiveOutputMode(
+    rawValues: Record<string, unknown>,
+    outputPath: string | undefined,
+  ): 'directory' | 'file' | undefined {
+    return this.resolveOutputMode(outputPath ?? this.getDefaultOutputPath(rawValues))
   }
 
   protected validateInputPresence(rawValues: Record<string, unknown>): number | undefined {
@@ -556,11 +732,6 @@ abstract class GeneratedFileIntentCommandBase extends GeneratedIntentCommandBase
   }
 
   protected validateBeforePreparingInputs(rawValues: Record<string, unknown>): number | undefined {
-    const outputValidationError = this.validateOutputChoice()
-    if (outputValidationError != null) {
-      return outputValidationError
-    }
-
     const validationError = this.validateInputPresence(rawValues)
     if (validationError != null) {
       return validationError
@@ -591,12 +762,14 @@ abstract class GeneratedFileIntentCommandBase extends GeneratedIntentCommandBase
       }
     }
 
+    const effectiveOutputPath = this.getEffectiveOutputPath(rawValues)
     return await executeIntentCommand({
       client: this.client,
       createOptions: this.getCreateOptions(effectivePreparedInputs.inputs),
       definition: this.getIntentDefinition(),
       output: this.output,
-      outputPath: this.outputPath,
+      outputMode: this.getEffectiveOutputMode(rawValues, effectiveOutputPath),
+      outputPath: effectiveOutputPath,
       printUrls: this.printUrls ?? false,
       rawValues,
     })
@@ -669,6 +842,14 @@ export abstract class GeneratedWatchableFileIntentCommand extends GeneratedFileI
     return false
   }
 
+  protected override prefersDirectoryDefaultOutput(): boolean {
+    return (
+      super.prefersDirectoryDefaultOutput() ||
+      this.getProvidedInputCount() > 1 ||
+      this.hasDirectoryInput()
+    )
+  }
+
   protected override validatePreparedInputs(
     preparedInputs: PreparedIntentInputs,
   ): number | undefined {
@@ -687,6 +868,13 @@ export abstract class GeneratedStandardFileIntentCommand extends GeneratedWatcha
     return this.singleAssembly
   }
 
+  protected override prefersDirectoryDefaultOutput(): boolean {
+    return (
+      super.prefersDirectoryDefaultOutput() ||
+      (this.singleAssembly && (this.getProvidedInputCount() > 1 || this.hasDirectoryInput()))
+    )
+  }
+
   protected override getCreateOptions(
     inputs: string[],
   ): Omit<AssembliesCreateOptions, 'output' | 'steps' | 'stepsData' | 'template'> {
@@ -706,14 +894,7 @@ export abstract class GeneratedStandardFileIntentCommand extends GeneratedWatcha
 
     if (
       this.singleAssembly &&
-      (this.getProvidedInputCount() > 1 ||
-        this.inputs.some((inputPath) => {
-          try {
-            return statSync(inputPath).isDirectory()
-          } catch {
-            return false
-          }
-        })) &&
+      (this.getProvidedInputCount() > 1 || this.hasDirectoryInput()) &&
       this.outputPath != null &&
       !this.isDirectoryOutputTarget()
     ) {

package/src/cli/semanticIntents/imageDescribe.ts

@@ -62,19 +62,19 @@ const imageDescribeExecutionDefinition = {
 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`.',
+    'Generates image labels through `/image/describe`, or structured altText/title/caption/description through `/ai/chat`, then writes the JSON result to `--output`.',
   examples: [
     [
       'Describe an image as labels',
-      'transloadit image describe --input hero.jpg --out labels.json',
+      'transloadit image describe --input hero.jpg --output labels.json',
     ],
     [
       'Generate WordPress-ready fields',
-      'transloadit image describe --input hero.jpg --for wordpress --out fields.json',
+      'transloadit image describe --input hero.jpg --for wordpress --output fields.json',
     ],
     [
       'Request a custom field set',
-      'transloadit image describe --input hero.jpg --fields altText,title,caption --out fields.json',
+      'transloadit image describe --input hero.jpg --fields altText,title,caption --output fields.json',
     ],
   ] as Array<[string, string]>,
 } as const satisfies SemanticIntentPresentation
@@ -249,6 +249,7 @@ function createImageDescribeStep(
 
 export const imageDescribeSemanticIntentDescriptor = {
   createStep: createImageDescribeStep,
+  defaultOutputPath: 'output.json',
   execution: imageDescribeExecutionDefinition,
   inputPolicy: { kind: 'required' },
   outputDescription: 'Write the JSON result to this path or directory',

package/src/cli/semanticIntents/imageGenerate.ts

@@ -91,15 +91,15 @@ const imageGenerateCommandPresentation = {
   examples: [
     [
       'Generate an image from text',
-      'transloadit image generate --prompt "A red bicycle in a studio" --out output.png',
+      'transloadit image generate --prompt "A red bicycle in a studio" --output 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',
+      'transloadit image generate --input subject.jpg --prompt "Place subject.jpg on a magazine cover" --output 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',
+      'transloadit image generate --input person1.jpg --input person2.jpg --input background.jpg --prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" --output output.png',
     ],
   ] as Array<[string, string]>,
 } as const satisfies SemanticIntentPresentation
@@ -234,6 +234,7 @@ function ensureUniqueInputBasenames(preparedInputs: PreparedIntentInputs): Prepa
 
 export const imageGenerateSemanticIntentDescriptor = {
   createStep: createImageGenerateStep,
+  defaultOutputPath: 'output.png',
   execution: {
     kind: 'dynamic-step',
     handler: 'image-generate',

package/src/cli/semanticIntents/index.ts

@@ -22,6 +22,7 @@ export interface SemanticIntentDescriptor {
     rawValues: Record<string, unknown>,
     context: { hasInputs: boolean },
   ) => Record<string, unknown>
+  defaultOutputPath: string
   execution: IntentDynamicStepExecutionDefinition
   inputPolicy: IntentInputPolicy
   outputDescription: string

package/src/cli/semanticIntents/markdownPdf.ts

@@ -66,7 +66,7 @@ function createMarkdownConvertSemanticIntent({
     examples: [
       [
         `Render a Markdown file as a ${formatLabel} file`,
-        `transloadit markdown ${format} --input README.md --out ${exampleOutput}`,
+        `transloadit markdown ${format} --input README.md --output ${exampleOutput}`,
       ],
       [
         'Print a temporary result URL without downloading locally',
@@ -94,6 +94,7 @@ function createMarkdownConvertSemanticIntent({
       resultStepName: 'convert',
       fields: markdownOptionDefinitions,
     },
+    defaultOutputPath: exampleOutput,
     inputPolicy: { kind: 'required' },
     outputDescription: `Write the rendered ${formatLabel} to this path or directory`,
     presentation,