Repository Public License
1// ORIX Convert — Packages/ConvertKit/Sources/ConvertCLI/WorkflowCommand.swift2// Description: `orix-convert workflow run|validate|example`: Conversion Flow files (the core's `Workflow` model as3// JSON) validated against the live registry and run on files through the queue.4// Author: Simon-Pierre Boucher — contact@spboucher.ai5import Foundation6import ConvertCore7import ConvertKit89enum WorkflowCommand: Command {10 static let spec = CommandSpec(11 "workflow", summary: "Run or validate a Conversion Flow file (JSON).",12 usage: "workflow run <workflow.json> <files…> [--output-dir <dir>] [--on-conflict rename|skip|replace] [--jobs <n>] [--json] [--no-history]\n orix-convert workflow validate <workflow.json> [--for <format,format…>] [--json]\n orix-convert workflow example",13 flags: ["json", "no-history"], options: ["output-dir", "on-conflict", "jobs", "for"], minPositionals: 1, unbounded: true,14 details: [15 "The file holds one workflow: {\"name\": …, \"nodes\": [ … ]}; \"id\", \"summary\" and \"errorPolicy\" are optional.",16 "'workflow example' prints a complete file. Nodes: convert, rename, filter, branch, export.",17 "Paths that end without an export node write to --output-dir (default: next to each source).",18 ])1920 struct Issue: Codable { let severity: String; let node: String; let message: String }21 struct ValidationOutput: Codable { let name: String; let valid: Bool; let issues: [Issue]; let exportedFormats: [String]; let canExportUnconverted: Bool }22 struct Item: Codable { let source: String; let status: String; let outputs: [String]; let errors: [String]; let warnings: [ConversionWarning] }23 struct RunOutput: Codable {24 let name: String25 let succeeded: Int, succeededWithErrors: Int, failed: Int, filtered: Int, cancelled: Int26 let seconds: Double27 let items: [Item]28 }2930 /// Reads a workflow file, filling the optional members.31 static func load(_ url: URL) throws -> Workflow {32 guard let data = try? Data(contentsOf: url) else { throw CommandFailure(.inputError, "\(url.path) could not be read.") }33 guard var object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {34 throw CommandFailure(.checkFailed, "\(url.lastPathComponent) is not a JSON object.")35 }36 if object["id"] == nil { object["id"] = UUID().uuidString }37 if object["summary"] == nil { object["summary"] = "" }38 if object["errorPolicy"] == nil { object["errorPolicy"] = WorkflowErrorPolicy.stopItem.rawValue }39 if object["name"] == nil { object["name"] = url.deletingPathExtension().lastPathComponent }40 do {41 return try JSONDecoder().decode(Workflow.self, from: JSONSerialization.data(withJSONObject: object))42 } catch let error as DecodingError {43 throw CommandFailure(.checkFailed, "\(url.lastPathComponent) is not a valid workflow: \(describe(error)). Run 'orix-convert workflow example' to see the format.")44 }45 }4647 static func describe(_ error: DecodingError) -> String {48 func path(_ context: DecodingError.Context) -> String {49 let p = context.codingPath.map { $0.intValue.map { "[\($0)]" } ?? $0.stringValue }.joined(separator: ".")50 return p.isEmpty ? "top level" : p51 }52 switch error {53 case .keyNotFound(let key, let context): return "missing '\(key.stringValue)' at \(path(context))"54 case .typeMismatch(_, let context), .valueNotFound(_, let context), .dataCorrupted(let context): return "\(context.debugDescription) at \(path(context))"55 @unknown default: return "unreadable content"56 }57 }5859 static func example() -> Workflow {60 Workflow(id: UUID(uuidString: "00000000-0000-4000-8000-000000000001") ?? UUID(), name: "Web images",61 summary: "Large images become 1600-pixel JPEGs; everything else that is an image becomes WebP.",62 nodes: [63 .filter(.categoryIs(.image)),64 .branch(condition: .width(.greaterThan, 1600),65 then: [.convert(destination: .jpeg, operation: nil, options: ConversionOptions(["quality": .int(82), "resize.width": .int(1600)])),66 .rename(template: "{name}-web")],67 otherwise: [.convert(destination: .webp, operation: nil, options: ConversionOptions())]),68 .export(folder: URL(fileURLWithPath: "/tmp/orix-web-images"), conflictPolicy: .rename),69 ])70 }7172 static func run(_ arguments: ParsedArguments, io: CommandIO) async throws -> ExitCode {73 let action = arguments.positionals[0]74 switch action {75 case "example":76 io.out(try Shared.json(example()))77 return .success78 case "validate":79 guard arguments.positionals.count == 2 else { throw UsageError("Usage: orix-convert workflow validate <workflow.json> [--for <format,format…>]") }80 let workflow = try load(Shared.fileURL(arguments.positionals[1]))81 let formats = try arguments.value("for").map { raw in Set(try raw.split(separator: ",").map { try Shared.format(String($0), option: "--for") }) }82 let validation = WorkflowValidator.validate(workflow, registry: Shared.registry(), inputFormats: formats)83 let issues = validation.issues.map { Issue(severity: $0.severity.rawValue, node: $0.nodePath, message: $0.message) }84 if arguments.flag("json") {85 io.out(try Shared.json(ValidationOutput(name: workflow.name, valid: validation.isValid, issues: issues,86 exportedFormats: validation.exportedFormats.map(\.rawValue).sorted(), canExportUnconverted: validation.canExportUnconverted)))87 } else {88 io.out("\(workflow.name): \(validation.isValid ? "valid" : "INVALID") — \(workflow.nodes.count) top-level node(s), \(validation.errors.count) error(s), \(issues.count - validation.errors.count) warning(s)")89 for issue in issues { io.out(" \(issue.severity) at node \(issue.node): \(issue.message)") }90 if !validation.exportedFormats.isEmpty { io.out(" exports: \(validation.exportedFormats.map(\.rawValue).sorted().joined(separator: ", "))") }91 }92 return validation.isValid ? .success : .checkFailed93 case "run":94 guard arguments.positionals.count >= 3 else { throw UsageError("Usage: orix-convert workflow run <workflow.json> <files…>") }95 return try await runWorkflow(arguments, io: io)96 default:97 throw UsageError("workflow: unknown action '\(action)'. Actions: run, validate, example.")98 }99 }100101 private static func runWorkflow(_ arguments: ParsedArguments, io: CommandIO) async throws -> ExitCode {102 let workflow = try load(Shared.fileURL(arguments.positionals[1]))103 let inputs = arguments.positionals.dropFirst(2).map(Shared.fileURL)104 var policy = ConflictPolicy.rename105 if let raw = arguments.value("on-conflict") {106 guard let parsed = ConflictPolicy(rawValue: raw), parsed != .askUser else { throw UsageError("--on-conflict expects rename, skip or replace, not '\(raw)'.") }107 policy = parsed108 }109 let history = !arguments.flag("no-history")110 let service = ConversionService(configuration: .init(maxConcurrentJobs: try arguments.int("jobs", in: 1...64), recordHistory: history))111 let options = WorkflowRunOptions(defaultExportFolder: arguments.value("output-dir").map(Shared.fileURL), defaultConflictPolicy: policy, recordRun: history)112 let json = arguments.flag("json")113 let screen = Screen(io: io, showsProgress: false)114 let started = Date()115 let task = Task {116 try await service.workflowRunner.run(workflow, inputs: Array(inputs), options: options) { item in117 guard !json else { return }118 let name = item.source.lastPathComponent119 switch item.status {120 case .succeeded: screen.line("ok \(name) → \(item.outputs.map(\.path).joined(separator: ", "))")121 case .succeededWithErrors: screen.line("partial \(name) → \(item.outputs.map(\.path).joined(separator: ", ")) — \(item.errors.joined(separator: " "))")122 case .filtered: screen.line("filtered \(name)")123 case .failed: screen.error("FAILED \(name): \(item.errors.joined(separator: " "))")124 case .cancelled: screen.error("cancelled \(name)")125 }126 for warning in item.warnings { screen.line(" warning [\(warning.severity.rawValue)] \(warning.code): \(warning.message)") }127 }128 }129 let interrupt = InterruptCenter.shared.register { task.cancel() }130 defer { InterruptCenter.shared.unregister(interrupt) }131 let result: WorkflowRunResult132 do {133 result = try await task.value134 } catch WorkflowError.invalid(let validation) {135 for issue in validation.errors { io.err(" error at node \(issue.nodePath): \(issue.message)") }136 throw CommandFailure(.checkFailed, "The workflow is not valid; nothing was run.")137 }138 let output = RunOutput(name: workflow.name, succeeded: result.count(.succeeded), succeededWithErrors: result.count(.succeededWithErrors),139 failed: result.count(.failed), filtered: result.count(.filtered), cancelled: result.count(.cancelled),140 seconds: Date().timeIntervalSince(started),141 items: result.items.map { Item(source: $0.source.path, status: $0.status.rawValue, outputs: $0.outputs.map(\.path), errors: $0.errors, warnings: $0.warnings) })142 if json {143 io.out(try Shared.json(output))144 } else {145 io.out("Summary: \(result.items.count) file(s) — \(output.succeeded) done, \(output.succeededWithErrors) done with errors, \(output.failed) failed, \(output.filtered) filtered, \(output.cancelled) cancelled — \(Shared.seconds(output.seconds))")146 }147 if InterruptCenter.shared.isInterrupted { return .interrupted }148 return output.failed + output.succeededWithErrors + output.cancelled > 0 ? .conversionFailed : .success149 }150}151