transloadit 4.7.6 → 4.8.1

package/src/cli/commands/auth.ts

@@ -9,7 +9,14 @@ import {
 import type { OptionalAuthParams } from '../../apiTypes.ts'
 import { mintBearerTokenWithCredentials } from '../../bearerToken.ts'
 import { Transloadit } from '../../Transloadit.ts'
-import { readCliInput, requireEnvCredentials } from '../helpers.ts'
+import type { CliKeySecretCredentials, ResolvedCliConfig } from '../helpers.ts'
+import {
+  buildMissingCredentialsMessage,
+  readCliInput,
+  requireCliCredentials,
+  resolveCliConfig,
+} from '../helpers.ts'
+import type { IOutputCtl } from '../OutputCtl.ts'
 import { UnauthenticatedCommand } from './BaseCommand.ts'
 
 type UrlParamPrimitive = string | number | boolean
@@ -195,14 +202,49 @@ export interface RunSmartSigOptions {
   providedInput?: string
 }
 
-export async function runSig(options: RunSigOptions = {}): Promise<void> {
-  const credentialsResult = requireEnvCredentials()
+function reportStandaloneCredentialsError(error: string): null {
+  console.error(error)
+  process.exitCode = 1
+  return null
+}
+
+function getStandaloneCredentials(): CliKeySecretCredentials | null {
+  const credentialsResult = requireCliCredentials()
   if (!credentialsResult.ok) {
-    console.error(credentialsResult.error)
-    process.exitCode = 1
+    return reportStandaloneCredentialsError(credentialsResult.error)
+  }
+
+  return credentialsResult.credentials
+}
+
+function getCommandCredentials(output: IOutputCtl): CliKeySecretCredentials | null {
+  const credentialsResult = requireCliCredentials()
+  if (!credentialsResult.ok) {
+    output.error(credentialsResult.error)
+    return null
+  }
+
+  return credentialsResult.credentials
+}
+
+function getCommandConfigWithCredentials(output: IOutputCtl): {
+  config: ResolvedCliConfig
+  credentials: CliKeySecretCredentials
+} | null {
+  const config = resolveCliConfig()
+  if (config.credentials == null) {
+    output.error(config.loadError ?? buildMissingCredentialsMessage())
+    return null
+  }
+
+  return { config, credentials: config.credentials }
+}
+
+export async function runSig(options: RunSigOptions = {}): Promise<void> {
+  const credentials = getStandaloneCredentials()
+  if (credentials == null) {
     return
   }
-  const credentials = credentialsResult.credentials
 
   const { content } = await readCliInput({
     providedInput: options.providedInput,
@@ -220,13 +262,10 @@ export async function runSig(options: RunSigOptions = {}): Promise<void> {
 }
 
 export async function runSmartSig(options: RunSmartSigOptions = {}): Promise<void> {
-  const credentialsResult = requireEnvCredentials()
-  if (!credentialsResult.ok) {
-    console.error(credentialsResult.error)
-    process.exitCode = 1
+  const credentials = getStandaloneCredentials()
+  if (credentials == null) {
     return
   }
-  const credentials = credentialsResult.credentials
 
   const { content } = await readCliInput({
     providedInput: options.providedInput,
@@ -260,6 +299,8 @@ export class SignatureCommand extends UnauthenticatedCommand {
     details: `
       Read params JSON from stdin and output signed payload JSON.
       If no input is provided, generates a signature with default params.
+      Credentials are resolved from the shell environment, the current working directory .env, or
+      ~/.transloadit/credentials.
     `,
     examples: [
       ['Generate signature', 'echo \'{"steps":{}}\' | transloadit signature'],
@@ -273,12 +314,8 @@ export class SignatureCommand extends UnauthenticatedCommand {
   })
 
   protected async run(): Promise<number | undefined> {
-    const credentialsResult = requireEnvCredentials()
-    if (!credentialsResult.ok) {
-      this.output.error(credentialsResult.error)
-      return 1
-    }
-    const credentials = credentialsResult.credentials
+    const credentials = getCommandCredentials(this.output)
+    if (credentials == null) return 1
 
     const { content } = await readCliInput({ allowStdinWhenNoPath: true })
     const rawInput = (content ?? '').trim()
@@ -312,6 +349,8 @@ export class SmartCdnSignatureCommand extends UnauthenticatedCommand {
       Read Smart CDN params JSON from stdin and output a signed URL.
       Required fields: workspace, template, input
       Optional fields: expire_at_ms, url_params
+      Credentials are resolved from the shell environment, the current working directory .env, or
+      ~/.transloadit/credentials.
     `,
     examples: [
       [
@@ -326,12 +365,8 @@ export class SmartCdnSignatureCommand extends UnauthenticatedCommand {
   })
 
   protected async run(): Promise<number | undefined> {
-    const credentialsResult = requireEnvCredentials()
-    if (!credentialsResult.ok) {
-      this.output.error(credentialsResult.error)
-      return 1
-    }
-    const credentials = credentialsResult.credentials
+    const credentials = getCommandCredentials(this.output)
+    if (credentials == null) return 1
 
     const { content } = await readCliInput({ allowStdinWhenNoPath: true })
     const rawInput = (content ?? '').trim()
@@ -359,8 +394,9 @@ export class TokenCommand extends UnauthenticatedCommand {
     category: 'Auth',
     description: 'Mint a short-lived bearer token',
     details: `
-      Calls POST /token using HTTP Basic Auth (TRANSLOADIT_KEY + TRANSLOADIT_SECRET) and prints the
-      JSON response to stdout.
+      Calls POST /token using HTTP Basic Auth and prints the JSON response to stdout.
+      Credentials are resolved from the shell environment, the current working directory .env, or
+      ~/.transloadit/credentials.
     `,
     examples: [
       ['Mint an MCP token (default aud)', 'transloadit auth token'],
@@ -378,14 +414,12 @@ export class TokenCommand extends UnauthenticatedCommand {
   })
 
   protected override async run(): Promise<number | undefined> {
-    const credentialsResult = requireEnvCredentials()
-    if (!credentialsResult.ok) {
-      this.output.error(credentialsResult.error)
-      return 1
-    }
+    const resolved = getCommandConfigWithCredentials(this.output)
+    if (resolved == null) return 1
 
-    const result = await mintBearerTokenWithCredentials(credentialsResult.credentials, {
-      endpoint: this.endpoint,
+    const result = await mintBearerTokenWithCredentials(resolved.credentials, {
+      allowProcessEnvEndpointFallback: false,
+      endpoint: this.endpoint ?? resolved.config.credentialsEndpoint,
       aud: this.aud,
       scope: this.scope,
     })

package/src/cli/generateIntentDocs.ts

@@ -1,5 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import {
   getConcurrencyOptionDocumentation,
   getDeleteAfterProcessingOptionDocumentation,
@@ -127,7 +128,14 @@ function getBackendSummary(catalogDefinition: IntentDefinition): string {
 function getUsage(definition: ResolvedIntentCommandDefinition): string {
   const parts = ['npx transloadit', ...definition.paths]
   if (definition.runnerKind !== 'no-input') {
-    parts.push('--input', '<path|dir|url|->')
+    if (
+      'inputPolicy' in definition.intentDefinition &&
+      definition.intentDefinition.inputPolicy.kind === 'optional'
+    ) {
+      parts.push('[--input', '<path|dir|url|->]')
+    } else {
+      parts.push('--input', '<path|dir|url|->')
+    }
   }
   parts.push('[options]')
   return parts.join(' ')
@@ -322,7 +330,7 @@ function renderAtAGlanceTable(definitions: ResolvedIntentCommandDefinition[]): s
   )
 }
 
-function renderIntentDocsBody({
+export function renderIntentDocsBody({
   definitions,
   headingLevel,
 }: {
@@ -334,6 +342,8 @@ function renderIntentDocsBody({
     `${heading} At a glance`,
     '',
     'Intent commands are the fastest path to common one-off tasks from the CLI.',
+    'Authentication is resolved in this order: shell environment, the current working directory `.env`, then `~/.transloadit/credentials`.',
+    'The home credentials file uses dotenv syntax and can include `TRANSLOADIT_KEY`, `TRANSLOADIT_SECRET`, `TRANSLOADIT_ENDPOINT`, and `TRANSLOADIT_AUTH_TOKEN`.',
     'Use `--print-urls` when you want temporary result URLs without downloading locally.',
     'All intent commands also support the global CLI flags `--json`, `--log-level`, `--endpoint`, and `--help`.',
     '',
@@ -359,6 +369,15 @@ function renderIntentDocsBody({
   return lines.join('\n').trim()
 }
 
+function isEntrypoint(): boolean {
+  const entrypoint = process.argv[1]
+  if (entrypoint == null) {
+    return false
+  }
+
+  return import.meta.url === pathToFileURL(entrypoint).href
+}
+
 function replaceGeneratedBlock({
   endMarker,
   markdown,
@@ -410,10 +429,12 @@ async function main(): Promise<void> {
   await writeFile(readmeUrl, `${nextReadme}\n`)
 }
 
-main().catch((error) => {
-  if (!(error instanceof Error)) {
-    throw new Error(`Was thrown a non-error: ${String(error)}`)
-  }
-  console.error(error)
-  process.exit(1)
-})
+if (isEntrypoint()) {
+  main().catch((error) => {
+    if (!(error instanceof Error)) {
+      throw new Error(`Was thrown a non-error: ${String(error)}`)
+    }
+    console.error(error)
+    process.exit(1)
+  })
+}

package/src/cli/helpers.ts

@@ -1,30 +1,295 @@
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
+import { homedir } from 'node:os'
+import path from 'node:path'
 import type { Readable } from 'node:stream'
+import { parse as parseDotenv } from 'dotenv'
 import { isAPIError } from './types.ts'
 
-const MISSING_CREDENTIALS_MESSAGE =
-  'Missing credentials. Please set TRANSLOADIT_KEY and TRANSLOADIT_SECRET environment variables.'
+export type CliKeySecretCredentials = { authKey: string; authSecret: string }
+export type CliAuthToken = { authToken: string }
+export type CliAuth = CliKeySecretCredentials | CliAuthToken
+type CliEnvSource = {
+  name: 'env' | 'credentialsFile'
+  values: Record<string, string | undefined>
+}
+
+let loadedProjectDotenvPath: string | undefined
+let projectDotenvInjectedValues: Record<string, string> | undefined
+let projectDotenvPreviousValues: Record<string, string | undefined> | undefined
+let shellEnvBeforeProjectDotenv: Record<string, string | undefined> | undefined
+
+type LoadCliEnvSourcesResult = {
+  loadError?: string
+  shellEnvSource: CliEnvSource
+  sources: CliEnvSource[]
+}
+
+export type ResolvedCliConfig = {
+  auth?: CliAuth
+  credentials?: CliKeySecretCredentials
+  credentialsEndpoint?: string
+  endpoint?: string
+  loadError?: string
+}
+
+function normalizeEnvValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : undefined
+}
+
+function getConfiguredCredentialsFilePath(): string {
+  const configuredPath = normalizeEnvValue(process.env.TRANSLOADIT_CREDENTIALS_FILE)
+  if (configuredPath != null) {
+    return path.resolve(configuredPath)
+  }
+
+  return path.join(homedir(), '.transloadit', 'credentials')
+}
+
+function getProjectDotenvPath(): string {
+  return path.resolve(process.cwd(), '.env')
+}
+
+function getDisplayPath(filePath: string): string {
+  const normalizedHome = path.resolve(homedir())
+  const normalizedFilePath = path.resolve(filePath)
+  if (normalizedFilePath === normalizedHome) return '~'
+  if (normalizedFilePath.startsWith(`${normalizedHome}${path.sep}`)) {
+    return `~${normalizedFilePath.slice(normalizedHome.length)}`
+  }
+
+  return normalizedFilePath
+}
+
+export function buildMissingCredentialsMessage(): string {
+  return [
+    'Missing credentials.',
+    '',
+    'Looked for TRANSLOADIT_KEY + TRANSLOADIT_SECRET in this order:',
+    '1. Shell env: TRANSLOADIT_KEY / TRANSLOADIT_SECRET',
+    `2. Current directory .env: ${getProjectDotenvPath()}`,
+    `3. Credentials file: ${getDisplayPath(getConfiguredCredentialsFilePath())}`,
+  ].join('\n')
+}
+
+export function buildMissingAuthMessage(): string {
+  return [
+    'Missing authentication.',
+    '',
+    'Looked for TRANSLOADIT_AUTH_TOKEN or TRANSLOADIT_KEY + TRANSLOADIT_SECRET in this order:',
+    '1. Shell env: TRANSLOADIT_AUTH_TOKEN, or TRANSLOADIT_KEY / TRANSLOADIT_SECRET',
+    `2. Current directory .env: ${getProjectDotenvPath()}`,
+    `3. Credentials file: ${getDisplayPath(getConfiguredCredentialsFilePath())}`,
+  ].join('\n')
+}
+
+function readEnvFile(
+  filePath: string,
+): { ok: true; source: CliEnvSource } | { ok: false; error: string } | null {
+  if (!fs.existsSync(filePath)) return null
+
+  try {
+    return {
+      ok: true,
+      source: {
+        name: 'credentialsFile',
+        values: parseDotenv(fs.readFileSync(filePath)),
+      },
+    }
+  } catch (err) {
+    if (!(err instanceof Error)) {
+      throw new Error(`Was thrown a non-error: ${err}`)
+    }
+    return { ok: false, error: `Failed to read ${filePath}: ${err.message}` }
+  }
+}
+
+export function loadProjectDotenvIntoProcessEnv(): string | undefined {
+  const projectDotenvPath = getProjectDotenvPath()
+  if (loadedProjectDotenvPath !== projectDotenvPath) {
+    restoreProjectDotenvFromProcessEnv()
+    shellEnvBeforeProjectDotenv = { ...process.env }
+    loadedProjectDotenvPath = projectDotenvPath
+  }
+
+  const projectDotenvResult = readEnvFile(projectDotenvPath)
+  if (projectDotenvResult == null) {
+    restoreProjectDotenvFromProcessEnv()
+    projectDotenvInjectedValues = undefined
+    projectDotenvPreviousValues = undefined
+    return undefined
+  }
+
+  if (!projectDotenvResult.ok) return projectDotenvResult.error
+  if (projectDotenvInjectedValues != null) return undefined
+
+  const previousValues: Record<string, string | undefined> = {}
+  const injectedValues: Record<string, string> = {}
+  for (const [key, value] of Object.entries(projectDotenvResult.source.values)) {
+    if (value == null) continue
+    if (normalizeEnvValue(process.env[key]) != null) continue
+    previousValues[key] = process.env[key]
+    process.env[key] = value
+    injectedValues[key] = value
+  }
+
+  projectDotenvPreviousValues = previousValues
+  projectDotenvInjectedValues = injectedValues
+  return undefined
+}
+
+function getShellEnvValues(): Record<string, string | undefined> {
+  if (loadedProjectDotenvPath === getProjectDotenvPath() && shellEnvBeforeProjectDotenv != null) {
+    return shellEnvBeforeProjectDotenv
+  }
+
+  return { ...process.env }
+}
+
+function restoreProjectDotenvFromProcessEnv(): void {
+  if (projectDotenvInjectedValues == null || projectDotenvPreviousValues == null) return
+
+  for (const [key, injectedValue] of Object.entries(projectDotenvInjectedValues)) {
+    if (process.env[key] !== injectedValue) continue
+
+    const previousValue = projectDotenvPreviousValues[key]
+    if (previousValue == null) {
+      delete process.env[key]
+      continue
+    }
+
+    process.env[key] = previousValue
+  }
+
+  projectDotenvInjectedValues = undefined
+  projectDotenvPreviousValues = undefined
+}
+
+function loadCliEnvSources(): LoadCliEnvSourcesResult {
+  const shellEnvSource: CliEnvSource = {
+    name: 'env',
+    values: getShellEnvValues(),
+  }
+  const loadErrors: string[] = []
+
+  const projectDotenvLoadError = loadProjectDotenvIntoProcessEnv()
+  if (projectDotenvLoadError != null) {
+    loadErrors.push(projectDotenvLoadError)
+  }
+
+  const sources: CliEnvSource[] = [
+    {
+      name: 'env',
+      values: { ...process.env },
+    },
+  ]
+
+  const credentialsFilePath = getConfiguredCredentialsFilePath()
+  const credentialsFileResult = readEnvFile(credentialsFilePath)
+  if (credentialsFileResult?.ok === true) {
+    sources.push(credentialsFileResult.source)
+  } else if (credentialsFileResult?.ok === false) {
+    loadErrors.push(credentialsFileResult.error)
+  } else if (normalizeEnvValue(process.env.TRANSLOADIT_CREDENTIALS_FILE) != null) {
+    loadErrors.push(`Configured credentials file does not exist: ${credentialsFilePath}`)
+  }
+
+  return {
+    shellEnvSource,
+    sources,
+    ...(loadErrors[0] ? { loadError: loadErrors[0] } : {}),
+  }
+}
 
-type EnvCredentials = { authKey: string; authSecret: string }
+function getSourceValue(source: CliEnvSource, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = normalizeEnvValue(source.values[key])
+    if (value != null) return value
+  }
 
-function getEnvCredentials(): { authKey: string; authSecret: string } | null {
-  const authKey = process.env.TRANSLOADIT_KEY ?? process.env.TRANSLOADIT_AUTH_KEY
-  const authSecret = process.env.TRANSLOADIT_SECRET ?? process.env.TRANSLOADIT_AUTH_SECRET
+  return undefined
+}
 
-  if (!authKey || !authSecret) return null
+function getSourceCredentials(source: CliEnvSource): CliKeySecretCredentials | undefined {
+  const authKey = getSourceValue(source, ['TRANSLOADIT_KEY', 'TRANSLOADIT_AUTH_KEY'])
+  const authSecret = getSourceValue(source, ['TRANSLOADIT_SECRET', 'TRANSLOADIT_AUTH_SECRET'])
+  if (authKey == null || authSecret == null) return undefined
 
   return { authKey, authSecret }
 }
 
-type RequireEnvCredentialsResult =
-  | { ok: true; credentials: EnvCredentials }
+function getSourceAuthToken(source: CliEnvSource): CliAuthToken | undefined {
+  const authToken = getSourceValue(source, ['TRANSLOADIT_AUTH_TOKEN'])
+  if (authToken == null) return undefined
+
+  return { authToken }
+}
+
+function resolveEndpointForSource(
+  source: CliEnvSource | undefined,
+  shellEnvSource: CliEnvSource,
+): string | undefined {
+  const shellEndpoint = getSourceValue(shellEnvSource, ['TRANSLOADIT_ENDPOINT'])
+  if (shellEndpoint != null) return shellEndpoint
+  if (source == null) return undefined
+
+  return getSourceValue(source, ['TRANSLOADIT_ENDPOINT'])
+}
+
+export function resolveCliConfig(): ResolvedCliConfig {
+  const { loadError, shellEnvSource, sources } = loadCliEnvSources()
+  let auth: CliAuth | undefined
+  let authSource: CliEnvSource | undefined
+  let credentials: CliKeySecretCredentials | undefined
+  let credentialsSource: CliEnvSource | undefined
+
+  for (const source of sources) {
+    if (auth == null) {
+      const authToken = getSourceAuthToken(source)
+      if (authToken != null) {
+        auth = authToken
+        authSource = source
+      } else {
+        const sourceCredentials = getSourceCredentials(source)
+        if (sourceCredentials != null) {
+          auth = sourceCredentials
+          authSource = source
+        }
+      }
+    }
+
+    if (credentials != null) continue
+
+    const sourceCredentials = getSourceCredentials(source)
+    if (sourceCredentials != null) {
+      credentials = sourceCredentials
+      credentialsSource = source
+    }
+  }
+
+  return {
+    ...(auth != null ? { auth } : {}),
+    ...(credentials != null ? { credentials } : {}),
+    ...(authSource != null
+      ? { endpoint: resolveEndpointForSource(authSource, shellEnvSource) }
+      : {}),
+    ...(credentialsSource != null
+      ? { credentialsEndpoint: resolveEndpointForSource(credentialsSource, shellEnvSource) }
+      : {}),
+    ...(loadError != null ? { loadError } : {}),
+  }
+}
+
+type RequireCliCredentialsResult =
+  | { ok: true; credentials: CliKeySecretCredentials }
   | { ok: false; error: string }
 
-export function requireEnvCredentials(): RequireEnvCredentialsResult {
-  const credentials = getEnvCredentials()
-  if (credentials == null) return { ok: false, error: MISSING_CREDENTIALS_MESSAGE }
-  return { ok: true, credentials }
+export function requireCliCredentials(): RequireCliCredentialsResult {
+  const { credentials, loadError } = resolveCliConfig()
+  if (credentials != null) return { ok: true, credentials }
+  if (loadError != null) return { ok: false, error: loadError }
+  return { ok: false, error: buildMissingCredentialsMessage() }
 }
 
 export function createReadStream(file: string): Readable {

package/src/cli/intentCommandSpecs.ts

@@ -37,10 +37,6 @@ import {
   robotImageBgremoveInstructionsSchema,
   meta as robotImageBgremoveMeta,
 } from '../alphalib/types/robots/image-bgremove.ts'
-import {
-  robotImageGenerateInstructionsSchema,
-  meta as robotImageGenerateMeta,
-} from '../alphalib/types/robots/image-generate.ts'
 import {
   robotImageOptimizeInstructionsSchema,
   meta as robotImageOptimizeMeta,
@@ -169,11 +165,10 @@ export function findIntentDefinitionByPaths(
 }
 
 export const intentCatalog = [
-  defineRobotIntent({
-    kind: 'robot',
-    robot: '/image/generate',
-    meta: robotImageGenerateMeta,
-    schema: robotImageGenerateInstructionsSchema,
+  defineSemanticIntent({
+    kind: 'semantic',
+    paths: ['image', 'generate'],
+    semantic: 'image-generate',
   }),
   defineRobotIntent({
     kind: 'robot',

package/src/cli/intentRuntime.ts

@@ -318,8 +318,9 @@ function createSingleStep(
 function createDynamicIntentStep(
   execution: IntentDynamicStepExecutionDefinition,
   rawValues: Record<string, unknown>,
+  hasInputs: boolean,
 ): Record<string, unknown> {
-  return getSemanticIntentDescriptor(execution.handler).createStep(rawValues)
+  return getSemanticIntentDescriptor(execution.handler).createStep(rawValues, { hasInputs })
 }
 
 function requiresLocalInput(
@@ -367,7 +368,11 @@ async function executeIntentCommand({
                     rawValues,
                     createOptions.inputs.length > 0,
                   )
-                : createDynamicIntentStep(definition.execution, rawValues),
+                : createDynamicIntentStep(
+                    definition.execution,
+                    rawValues,
+                    createOptions.inputs.length > 0,
+                  ),
           } as AssembliesCreateOptions['stepsData'],
         }
 
@@ -563,7 +568,7 @@ abstract class GeneratedFileIntentCommandBase extends GeneratedIntentCommandBase
 
     const execution = this.getIntentDefinition().execution
     if (execution.kind === 'dynamic-step') {
-      createDynamicIntentStep(execution, rawValues)
+      createDynamicIntentStep(execution, rawValues, this.getProvidedInputCount() > 0)
     }
 
     return undefined

package/src/cli/semanticIntents/imageDescribe.ts

@@ -212,7 +212,10 @@ function buildDescribeAiChatMessages({
   }
 }
 
-function createImageDescribeStep(rawValues: Record<string, unknown>): Record<string, unknown> {
+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 {