@transloadit/node 4.2.0 → 4.3.0

package/src/alphalib/templateMerge.ts

@@ -0,0 +1,32 @@
+import merge from 'lodash-es/merge.js'
+import type { ResponseTemplateContent, TemplateContent } from '../apiTypes.ts'
+import type { AssemblyInstructionsInput } from './types/template.ts'
+
+export function mergeTemplateContent(
+  template: TemplateContent | ResponseTemplateContent,
+  params?: AssemblyInstructionsInput,
+): AssemblyInstructionsInput {
+  const templateContent = structuredClone(template) as TemplateContent | ResponseTemplateContent
+  const templateRecord = templateContent as Record<string, unknown>
+
+  if (templateContent.allow_steps_override == null) {
+    templateContent.allow_steps_override = true
+  }
+
+  if (params?.steps != null && templateContent.allow_steps_override === false) {
+    throw new Error('TEMPLATE_DENIES_STEPS_OVERRIDE')
+  }
+
+  if (params == null) {
+    return templateContent as AssemblyInstructionsInput
+  }
+
+  const paramsRecord = { ...params } as Record<string, unknown>
+  for (const key of Object.keys(templateRecord)) {
+    if (paramsRecord[key] === null && templateRecord[key] !== null) {
+      paramsRecord[key] = templateRecord[key]
+    }
+  }
+
+  return merge({}, templateRecord, paramsRecord) as AssemblyInstructionsInput
+}

package/src/alphalib/typings/json-to-ast.d.ts

@@ -0,0 +1,34 @@
+declare module 'json-to-ast' {
+  export interface JsonToAstLocation {
+    start: { line: number; column: number }
+  }
+
+  export interface ObjectPropertyNode {
+    key: { value: string; loc?: JsonToAstLocation }
+    value: ValueNode
+    loc?: JsonToAstLocation
+  }
+
+  export interface LiteralNode {
+    type: 'Literal'
+    value: unknown
+    loc?: JsonToAstLocation
+  }
+
+  export interface ArrayNode {
+    type: 'Array'
+    children: ValueNode[]
+    loc?: JsonToAstLocation
+  }
+
+  export interface ObjectNode {
+    type: 'Object'
+    children: ObjectPropertyNode[]
+    loc?: JsonToAstLocation
+  }
+
+  export type ValueNode = LiteralNode | ArrayNode | ObjectNode
+
+  const parse: (source: string, options?: { loc?: boolean }) => ValueNode
+  export default parse
+}

package/src/cli/commands/assemblies.ts

@@ -13,15 +13,19 @@ import got from 'got'
 import PQueue from 'p-queue'
 import * as t from 'typanion'
 import { z } from 'zod'
+import { formatLintIssue } from '../../alphalib/assembly-linter.lang.en.ts'
 import { tryCatch } from '../../alphalib/tryCatch.ts'
 import type { Steps, StepsInput } from '../../alphalib/types/template.ts'
 import { stepsSchema } from '../../alphalib/types/template.ts'
 import type { CreateAssemblyParams, ReplayAssemblyParams } from '../../apiTypes.ts'
+import type { LintFatalLevel } from '../../lintAssemblyInstructions.ts'
+import { lintAssemblyInstructions } from '../../lintAssemblyInstructions.ts'
 import type { CreateAssemblyOptions, Transloadit } from '../../Transloadit.ts'
-import { createReadStream, formatAPIError, streamToBuffer } from '../helpers.ts'
+import { lintingExamples } from '../docs/assemblyLintingExamples.ts'
+import { createReadStream, formatAPIError, readCliInput, streamToBuffer } from '../helpers.ts'
 import type { IOutputCtl } from '../OutputCtl.ts'
 import { ensureError, isErrnoException } from '../types.ts'
-import { AuthenticatedCommand } from './BaseCommand.ts'
+import { AuthenticatedCommand, UnauthenticatedCommand } from './BaseCommand.ts'
 
 // --- From assemblies.ts: Schemas and interfaces ---
 export interface AssemblyListOptions {
@@ -48,6 +52,15 @@ export interface AssemblyReplayOptions {
   assemblies: string[]
 }
 
+export interface AssemblyLintOptions {
+  steps?: string
+  template?: string
+  fatal?: LintFatalLevel
+  fix?: boolean
+  providedInput?: string
+  json?: boolean
+}
+
 const AssemblySchema = z.object({
   id: z.string(),
 })
@@ -163,6 +176,97 @@ export async function replay(
   }
 }
 
+export async function lint(
+  output: IOutputCtl,
+  client: Transloadit | null,
+  { steps, template, fatal, fix, providedInput, json }: AssemblyLintOptions,
+): Promise<number> {
+  let content: string | null
+  let isStdin: boolean
+  let inputPath: string | undefined
+  try {
+    ;({
+      content,
+      isStdin,
+      path: inputPath,
+    } = await readCliInput({
+      inputPath: steps,
+      providedInput,
+      allowStdinWhenNoPath: true,
+    }))
+  } catch (error) {
+    output.error(ensureError(error).message)
+    return 1
+  }
+
+  if (content == null && template == null) {
+    output.error('assemblies lint requires --steps or stdin input unless --template is provided')
+    return 1
+  }
+
+  if (fix && content == null && template != null) {
+    output.error('assemblies lint --fix requires local instructions (stdin or --steps)')
+    return 1
+  }
+
+  let result: Awaited<ReturnType<typeof lintAssemblyInstructions>>
+  try {
+    if (template != null) {
+      if (!client) {
+        output.error('Missing client for template lookup')
+        return 1
+      }
+      result = await client.lintAssemblyInstructions({
+        assemblyInstructions: content ?? undefined,
+        templateId: template,
+        fatal,
+        fix,
+      })
+    } else {
+      result = await lintAssemblyInstructions({
+        assemblyInstructions: content ?? undefined,
+        fatal,
+        fix,
+      })
+    }
+  } catch (error) {
+    output.error(ensureError(error).message)
+    return 1
+  }
+
+  const issues = result.issues
+
+  if (fix && isStdin) {
+    if (result.fixedInstructions == null) {
+      output.error('No fixed output available.')
+      return 1
+    }
+    process.stdout.write(`${result.fixedInstructions}\n`)
+    for (const issue of issues) {
+      const line = formatLintIssue(issue)
+      if (issue.type === 'warning') output.warn(line)
+      else output.error(line)
+    }
+    return result.success ? 0 : 1
+  }
+
+  if (fix && inputPath && result.fixedInstructions != null) {
+    await fsp.writeFile(inputPath, result.fixedInstructions)
+  }
+
+  if (json) {
+    output.print({ ...result, issues }, result)
+  } else if (issues.length === 0) {
+    output.print('No issues found', result)
+  } else {
+    for (const issue of issues) {
+      output.print(formatLintIssue(issue), issue)
+    }
+  }
+
+  return result.success ? 0 : 1
+}
+
 // --- From assemblies-create.ts: Helper classes and functions ---
 interface NodeWatcher {
   on(event: 'error', listener: (err: Error) => void): void
@@ -1373,3 +1477,58 @@ export class AssembliesReplayCommand extends AuthenticatedCommand {
     return undefined
   }
 }
+
+export class AssembliesLintCommand extends UnauthenticatedCommand {
+  static override paths = [
+    ['assemblies', 'lint'],
+    ['assembly', 'lint'],
+    ['a', 'lint'],
+  ]
+
+  static override usage = Command.Usage({
+    category: 'Assemblies',
+    description: 'Lint Assembly Instructions',
+    details: `
+      Lint Assembly Instructions locally using Transloadit's linter.
+      Provide instructions via --steps or stdin (steps-only JSON is accepted).
+      Optionally pass --template to
+      merge template content with steps before linting (same merge behavior as the API).
+    `,
+    examples: lintingExamples,
+  })
+
+  steps = Option.String('--steps,-s', {
+    description: 'JSON file with Assembly Instructions (use "-" for stdin)',
+  })
+
+  template = Option.String('--template,-t', {
+    description:
+      'Template ID to merge before linting. If the template forbids step overrides, linting will fail when steps are provided.',
+  })
+
+  fatal = Option.String('--fatal', {
+    description: 'Treat issues at this level as fatal (error or warning)',
+    validator: t.isEnum(['error', 'warning']),
+  })
+
+  fix = Option.Boolean('--fix', false, {
+    description:
+      'Apply auto-fixes. For files, overwrites in place. For stdin, writes fixed JSON to stdout.',
+  })
+
+  protected async run(): Promise<number | undefined> {
+    let client: Transloadit | null = null
+    if (this.template) {
+      if (!this.setupClient()) return 1
+      client = this.client
+    }
+
+    return await lint(this.output, client, {
+      steps: this.steps,
+      template: this.template,
+      fatal: this.fatal as LintFatalLevel | undefined,
+      fix: this.fix,
+      json: this.json,
+    })
+  }
+}

package/src/cli/commands/auth.ts

@@ -8,7 +8,7 @@ import {
 } from '../../alphalib/types/template.ts'
 import type { OptionalAuthParams } from '../../apiTypes.ts'
 import { Transloadit } from '../../Transloadit.ts'
-import { getEnvCredentials } from '../helpers.ts'
+import { getEnvCredentials, readCliInput } from '../helpers.ts'
 import { UnauthenticatedCommand } from './BaseCommand.ts'
 
 type UrlParamPrimitive = string | number | boolean
@@ -68,19 +68,6 @@ function normalizeUrlParams(params?: Record<string, unknown>): NormalizedUrlPara
   return normalized
 }
 
-async function readStdin(): Promise<string> {
-  if (process.stdin.isTTY) return ''
-
-  process.stdin.setEncoding('utf8')
-  let data = ''
-
-  for await (const chunk of process.stdin) {
-    data += chunk
-  }
-
-  return data
-}
-
 const getCredentials = getEnvCredentials
 
 // Result type for signature operations
@@ -217,8 +204,12 @@ export async function runSig(options: RunSigOptions = {}): Promise<void> {
     return
   }
 
-  const rawInput = options.providedInput ?? (await readStdin())
-  const result = generateSignature(rawInput.trim(), credentials, options.algorithm)
+  const { content } = await readCliInput({
+    providedInput: options.providedInput,
+    allowStdinWhenNoPath: true,
+  })
+  const rawInput = (content ?? '').trim()
+  const result = generateSignature(rawInput, credentials, options.algorithm)
 
   if (result.ok) {
     process.stdout.write(`${result.output}\n`)
@@ -238,8 +229,12 @@ export async function runSmartSig(options: RunSmartSigOptions = {}): Promise<voi
     return
   }
 
-  const rawInput = options.providedInput ?? (await readStdin())
-  const result = generateSmartCdnUrl(rawInput.trim(), credentials)
+  const { content } = await readCliInput({
+    providedInput: options.providedInput,
+    allowStdinWhenNoPath: true,
+  })
+  const rawInput = (content ?? '').trim()
+  const result = generateSmartCdnUrl(rawInput, credentials)
 
   if (result.ok) {
     process.stdout.write(`${result.output}\n`)
@@ -287,8 +282,9 @@ export class SignatureCommand extends UnauthenticatedCommand {
       return 1
     }
 
-    const rawInput = await readStdin()
-    const result = generateSignature(rawInput.trim(), credentials, this.algorithm)
+    const { content } = await readCliInput({ allowStdinWhenNoPath: true })
+    const rawInput = (content ?? '').trim()
+    const result = generateSignature(rawInput, credentials, this.algorithm)
 
     if (result.ok) {
       process.stdout.write(`${result.output}\n`)
@@ -340,8 +336,9 @@ export class SmartCdnSignatureCommand extends UnauthenticatedCommand {
       return 1
     }
 
-    const rawInput = await readStdin()
-    const result = generateSmartCdnUrl(rawInput.trim(), credentials)
+    const { content } = await readCliInput({ allowStdinWhenNoPath: true })
+    const rawInput = (content ?? '').trim()
+    const result = generateSmartCdnUrl(rawInput, credentials)
 
     if (result.ok) {
       process.stdout.write(`${result.output}\n`)

package/src/cli/commands/index.ts

@@ -6,6 +6,7 @@ import {
   AssembliesCreateCommand,
   AssembliesDeleteCommand,
   AssembliesGetCommand,
+  AssembliesLintCommand,
   AssembliesListCommand,
   AssembliesReplayCommand,
 } from './assemblies.ts'
@@ -46,6 +47,7 @@ export function createCli(): Cli {
   cli.register(AssembliesGetCommand)
   cli.register(AssembliesDeleteCommand)
   cli.register(AssembliesReplayCommand)
+  cli.register(AssembliesLintCommand)
 
   // Templates commands
   cli.register(TemplatesCreateCommand)

package/src/cli/docs/assemblyLintingExamples.ts

@@ -0,0 +1,9 @@
+export const lintingExamples: Array<[string, string]> = [
+  ['Lint a steps file', 'transloadit assemblies lint --steps steps.json'],
+  ['Lint from stdin', 'cat steps.json | transloadit assemblies lint --steps -'],
+  [
+    'Lint with template merge',
+    'transloadit assemblies lint --template TEMPLATE_ID --steps steps.json',
+  ],
+  ['Auto-fix in place', 'transloadit assemblies lint --steps steps.json --fix'],
+]

package/src/cli/helpers.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs'
+import fsp from 'node:fs/promises'
 import type { Readable } from 'node:stream'
 import { isAPIError } from './types.ts'
 
@@ -24,6 +25,55 @@ export async function streamToBuffer(stream: Readable): Promise<Buffer> {
   return Buffer.concat(chunks)
 }
 
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) return ''
+
+  process.stdin.setEncoding('utf8')
+  let data = ''
+
+  for await (const chunk of process.stdin) {
+    data += chunk
+  }
+
+  return data
+}
+
+export interface CliInputResult {
+  content: string | null
+  isStdin: boolean
+  path?: string
+}
+
+export interface ReadCliInputOptions {
+  inputPath?: string
+  providedInput?: string
+  allowStdinWhenNoPath?: boolean
+}
+
+export async function readCliInput(options: ReadCliInputOptions): Promise<CliInputResult> {
+  const { inputPath, providedInput, allowStdinWhenNoPath = false } = options
+  const canUseProvided = providedInput != null && (inputPath == null || inputPath === '-')
+
+  if (canUseProvided) {
+    return { content: providedInput, isStdin: inputPath === '-' || inputPath == null }
+  }
+
+  if (inputPath === '-') {
+    return { content: await readStdin(), isStdin: true }
+  }
+
+  if (inputPath != null) {
+    const content = await fsp.readFile(inputPath, 'utf8')
+    return { content, isStdin: false, path: inputPath }
+  }
+
+  if (allowStdinWhenNoPath && !process.stdin.isTTY) {
+    return { content: await readStdin(), isStdin: true }
+  }
+
+  return { content: null, isStdin: false }
+}
+
 export function formatAPIError(err: unknown): string {
   if (isAPIError(err)) {
     return `${err.error}: ${err.message}`

package/src/lintAssemblyInput.ts

@@ -0,0 +1,89 @@
+import { getIndentation } from './alphalib/stepParsing.ts'
+import { mergeTemplateContent } from './alphalib/templateMerge.ts'
+import type { AssemblyInstructionsInput, StepsInput } from './alphalib/types/template.ts'
+import type { ResponseTemplateContent, TemplateContent } from './apiTypes.ts'
+
+const DEFAULT_INDENT = '  '
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+export interface BuildLintInputResult {
+  lintContent: string
+  wasStepsOnly: boolean
+  indent: string
+}
+
+export const unwrapStepsOnly = (content: string, indent: string): string => {
+  try {
+    const parsed = JSON.parse(content)
+    if (isRecord(parsed) && 'steps' in parsed) {
+      return JSON.stringify((parsed as { steps?: unknown }).steps ?? {}, null, indent)
+    }
+  } catch (_err) {
+    return content
+  }
+  return content
+}
+
+export const buildLintInput = (
+  assemblyInstructions?: AssemblyInstructionsInput | StepsInput | string,
+  template?: TemplateContent | ResponseTemplateContent,
+): BuildLintInputResult => {
+  let inputString: string | undefined
+  let parsedInput: unknown | undefined
+  let parseFailed = false
+  let indent = DEFAULT_INDENT
+
+  if (typeof assemblyInstructions === 'string') {
+    inputString = assemblyInstructions
+    indent = getIndentation(assemblyInstructions)
+    try {
+      parsedInput = JSON.parse(assemblyInstructions)
+    } catch (_err) {
+      parseFailed = true
+    }
+  } else if (assemblyInstructions != null) {
+    parsedInput = assemblyInstructions
+  }
+
+  let wasStepsOnly = false
+  let instructions: AssemblyInstructionsInput | undefined
+
+  if (parsedInput !== undefined) {
+    if (isRecord(parsedInput)) {
+      if ('steps' in parsedInput) {
+        instructions = parsedInput as AssemblyInstructionsInput
+      } else {
+        instructions = { steps: parsedInput as StepsInput }
+        wasStepsOnly = true
+      }
+    } else {
+      instructions = { steps: parsedInput as StepsInput }
+      wasStepsOnly = true
+    }
+  }
+
+  const shouldMergeTemplate = template != null && !parseFailed
+  if (shouldMergeTemplate) {
+    instructions = mergeTemplateContent(template, instructions)
+  }
+
+  let lintContent = ''
+  if (instructions != null) {
+    if (
+      typeof assemblyInstructions === 'string' &&
+      !wasStepsOnly &&
+      !parseFailed &&
+      !shouldMergeTemplate
+    ) {
+      lintContent = assemblyInstructions
+    } else {
+      lintContent = JSON.stringify(instructions, null, indent)
+    }
+  } else if (inputString != null) {
+    lintContent = inputString
+  }
+
+  return { lintContent, wasStepsOnly, indent }
+}

package/src/lintAssemblyInstructions.ts

@@ -0,0 +1,72 @@
+import type { HydratedLintIssue } from './alphalib/assembly-linter.lang.en.ts'
+import { hydrateLintIssues } from './alphalib/assembly-linter.lang.en.ts'
+import { applyFix, parseAndLint } from './alphalib/assembly-linter.ts'
+import type { AssemblyInstructionsInput, StepsInput } from './alphalib/types/template.ts'
+import type { ResponseTemplateContent, TemplateContent } from './apiTypes.ts'
+import { buildLintInput, unwrapStepsOnly } from './lintAssemblyInput.ts'
+
+export type LintFatalLevel = 'error' | 'warning'
+
+export interface LintAssemblyInstructionsInput {
+  /**
+   * Assembly Instructions as a JSON string, a full instructions object, or a steps-only object.
+   */
+  assemblyInstructions?: AssemblyInstructionsInput | StepsInput | string
+  /**
+   * Optional template content to merge with the provided instructions.
+   */
+  template?: TemplateContent | ResponseTemplateContent
+  /**
+   * Treat issues at this level or above as fatal. Defaults to "error".
+   */
+  fatal?: LintFatalLevel
+  /**
+   * Apply auto-fixes where possible and return the fixed JSON.
+   */
+  fix?: boolean
+}
+
+export interface LintAssemblyInstructionsResult {
+  success: boolean
+  issues: HydratedLintIssue[]
+  fixedInstructions?: string
+}
+
+export async function lintAssemblyInstructions(
+  options: LintAssemblyInstructionsInput,
+): Promise<LintAssemblyInstructionsResult> {
+  const { assemblyInstructions, template, fix = false, fatal = 'error' } = options
+
+  if (assemblyInstructions == null && template == null) {
+    throw new Error('Provide assemblyInstructions or template content to lint.')
+  }
+
+  const { lintContent, wasStepsOnly, indent } = buildLintInput(assemblyInstructions, template)
+
+  let issues = await parseAndLint(lintContent)
+  let fixedContent = lintContent
+
+  if (fix) {
+    for (const issue of issues) {
+      if (!issue.fixId) continue
+      // applyFix validates fixData against the fix schema for the fixId.
+      fixedContent = applyFix(fixedContent, issue.fixId, issue.fixData as never)
+    }
+    issues = await parseAndLint(fixedContent)
+  }
+
+  const describedIssues = hydrateLintIssues(issues)
+  const fatalTypes = fatal === 'warning' ? new Set(['warning', 'error']) : new Set(['error'])
+  const success = !describedIssues.some((issue) => fatalTypes.has(issue.type))
+
+  const result: LintAssemblyInstructionsResult = {
+    success,
+    issues: describedIssues,
+  }
+
+  if (fix) {
+    result.fixedInstructions = wasStepsOnly ? unwrapStepsOnly(fixedContent, indent) : fixedContent
+  }
+
+  return result
+}