Repository Public License
1// ORIX Convert — Packages/ORIXConvertCore/Sources/ConvertCore/Workflows.swift2// Description: Conversion Flow. A workflow is an ordered list of nodes (convert, rename, filter, branch, export)3// applied to each input file. The runner turns every convert node into a queue job, chains the4// intermediates through a private work directory, and exports with the safe writer. Workflows are5// validated against the registry before they run.6// Author: Simon-Pierre Boucher — contact@spboucher.ai7import Foundation89// MARK: - Model1011public enum Comparison: String, Sendable, Codable, CaseIterable {12 case lessThan, lessOrEqual, equal, greaterOrEqual, greaterThan1314 public func holds<T: Comparable>(_ a: T, _ b: T) -> Bool {15 switch self {16 case .lessThan: a < b17 case .lessOrEqual: a <= b18 case .equal: a == b19 case .greaterOrEqual: a >= b20 case .greaterThan: a > b21 }22 }23}2425/// A test on the file a workflow is currently holding (the original, or the result of the previous convert node).26public indirect enum WorkflowCondition: Sendable, Hashable, Codable {27 case formatIs(FormatID)28 case categoryIs(FormatCategory)29 /// File size strictly above the given number of bytes.30 case sizeAbove(Int64)31 /// File size strictly below the given number of bytes.32 case sizeBelow(Int64)33 /// File name matches a shell glob (`*.jpg`, `IMG_????.*`), case-insensitively.34 case nameMatches(String)35 /// Pixel width / height / duration in seconds, read by the engine's inspection. When the value cannot be read36 /// the condition is false.37 case width(Comparison, Int)38 case height(Comparison, Int)39 case duration(Comparison, Double)40 case not(WorkflowCondition)41 case all([WorkflowCondition])42 case any([WorkflowCondition])4344 /// The condition needs the engine's inspection (dimensions, duration).45 public var needsInspection: Bool {46 switch self {47 case .width, .height, .duration: true48 case .not(let c): c.needsInspection49 case .all(let list), .any(let list): list.contains(where: \.needsInspection)50 default: false51 }52 }5354 /// Evaluates the condition on known facts.55 public func evaluate(name: String, format: FormatID?, size: Int64?, inspection: FileInspection?) -> Bool {56 switch self {57 case .formatIs(let wanted): return format == wanted58 case .categoryIs(let category): return format.flatMap(FormatCatalog.format)?.category == category59 case .sizeAbove(let bytes): return size.map { $0 > bytes } ?? false60 case .sizeBelow(let bytes): return size.map { $0 < bytes } ?? false61 case .nameMatches(let pattern): return Glob.matches(pattern, name)62 case .width(let comparison, let value): return inspection?.pixelWidth.map { comparison.holds($0, value) } ?? false63 case .height(let comparison, let value): return inspection?.pixelHeight.map { comparison.holds($0, value) } ?? false64 case .duration(let comparison, let value): return inspection?.durationSeconds.map { comparison.holds($0, value) } ?? false65 case .not(let c): return !c.evaluate(name: name, format: format, size: size, inspection: inspection)66 case .all(let list): return list.allSatisfy { $0.evaluate(name: name, format: format, size: size, inspection: inspection) }67 case .any(let list): return list.contains { $0.evaluate(name: name, format: format, size: size, inspection: inspection) }68 }69 }70}7172public enum Glob {73 /// Shell-style match (`*`, `?`, `[a-z]`), case-insensitive.74 public static func matches(_ pattern: String, _ name: String) -> Bool {75 fnmatch(pattern, name, FNM_CASEFOLD) == 076 }77}7879public indirect enum WorkflowNode: Sendable, Hashable, Codable {80 /// Converts the current file. A file already in `destination` format passes through untouched when81 /// `operation` is `nil`.82 case convert(destination: FormatID, operation: String?, options: ConversionOptions)83 /// Sets the output name template used by the following export nodes (see `OutputNameTemplate`).84 case rename(template: String)85 /// Stops processing the file when the condition is false (the file is reported as `filtered`).86 case filter(WorkflowCondition)87 /// Runs `then` or `otherwise`, then continues with the nodes after the branch.88 case branch(condition: WorkflowCondition, then: [WorkflowNode], otherwise: [WorkflowNode])89 /// Writes the current file into `folder`. The original is copied, never moved.90 case export(folder: URL, conflictPolicy: ConflictPolicy)91}9293public enum WorkflowErrorPolicy: String, Sendable, Codable, CaseIterable {94 /// A failing node ends the processing of that file (other files continue).95 case stopItem96 /// A failing convert or export node is logged and skipped; the following nodes run on the unchanged file.97 case continueItem98}99100public struct Workflow: Sendable, Hashable, Codable, Identifiable {101 public var id: UUID102 public var name: String103 public var summary: String104 public var nodes: [WorkflowNode]105 public var errorPolicy: WorkflowErrorPolicy106107 public init(id: UUID = UUID(), name: String, summary: String = "", nodes: [WorkflowNode], errorPolicy: WorkflowErrorPolicy = .stopItem) {108 self.id = id; self.name = name; self.summary = summary; self.nodes = nodes; self.errorPolicy = errorPolicy109 }110}111112public extension WorkflowNode {113 /// A copy whose convert nodes (also inside branches) carry no secret option value.114 func redactingSecrets() -> WorkflowNode {115 switch self {116 case .convert(let destination, let operation, let options):117 return .convert(destination: destination, operation: operation, options: options.redactingSecrets())118 case .branch(let condition, let then, let otherwise):119 return .branch(condition: condition, then: then.map { $0.redactingSecrets() }, otherwise: otherwise.map { $0.redactingSecrets() })120 default:121 return self122 }123 }124}125126public extension Workflow {127 /// A copy without any secret option value (keys containing `password`). This is what `WorkflowLibrary` stores128 /// and exports: a password typed in a convert node is used by a run of the in-memory workflow only.129 func redactingSecrets() -> Workflow {130 var copy = self131 copy.nodes = nodes.map { $0.redactingSecrets() }132 return copy133 }134}135136// MARK: - Validation137138public struct WorkflowIssue: Sendable, Hashable, Codable {139 public enum Severity: String, Sendable, Codable { case error, warning }140 public let severity: Severity141 /// 1-based position of the node, nested through branches: `2`, `3.then.1`, `3.otherwise.2`. Empty for142 /// workflow-level issues.143 public let nodePath: String144 public let message: String145}146147public struct WorkflowValidation: Sendable, Hashable {148 public let issues: [WorkflowIssue]149 /// Formats that can reach an export (explicit or implicit), given the input formats considered.150 public let exportedFormats: Set<FormatID>151 /// At least one path of the workflow can export a file that went through no convert node.152 public let canExportUnconverted: Bool153 public var errors: [WorkflowIssue] { issues.filter { $0.severity == .error } }154 public var isValid: Bool { errors.isEmpty }155}156157public enum WorkflowValidator {158 /// Checks a workflow against the registry.159 ///160 /// The set of formats that can reach each node is propagated through the workflow (filters and branches on161 /// format or category narrow it; a convert node replaces it by its destination).162 ///163 /// - With explicit `inputFormats` (the detected formats of a batch), a convert node is an **error** as soon as164 /// one reaching format has no real path (direct or chained) to its destination.165 /// - Without them, the registry's source formats are assumed; a convert node is an error only when **no**166 /// reaching format has a path — the remaining unsupported inputs fail individually at run time.167 public static func validate(_ workflow: Workflow, registry: FormatRegistry, inputFormats: Set<FormatID>? = nil) -> WorkflowValidation {168 var issues: [WorkflowIssue] = []169 var exported = Set<FormatID>()170 var exportsUnconverted = false171 let planner = ConversionPlanner(registry: registry)172 let strict = inputFormats != nil173174 // `formats`: every format reaching this point; `unconverted`: a file that went through no convert node can.175 struct Flow { var formats: Set<FormatID>; var unconverted: Bool; var exportedAny: Bool }176177 func narrow(_ formats: Set<FormatID>, _ condition: WorkflowCondition, _ truth: Bool) -> Set<FormatID> {178 switch condition {179 case .formatIs(let f): return truth ? formats.intersection([f]) : formats.subtracting([f])180 case .categoryIs(let category): return formats.filter { (FormatCatalog.format($0)?.category == category) == truth }181 case .not(let c): return narrow(formats, c, !truth)182 case .all(let list): return truth ? list.reduce(formats) { narrow($0, $1, true) } : formats183 case .any(let list): return truth ? (list.isEmpty ? [] : list.reduce(Set<FormatID>()) { $0.union(narrow(formats, $1, true)) }) : list.reduce(formats) { narrow($0, $1, false) }184 default: return formats185 }186 }187188 func walk(_ nodes: [WorkflowNode], _ start: Flow, prefix: String) -> Flow {189 var flow = start190 for (index, node) in nodes.enumerated() {191 let path = prefix + String(index + 1)192 switch node {193 case .convert(let destination, let operation, _):194 if flow.formats.isEmpty {195 issues.append(WorkflowIssue(severity: .warning, nodePath: path, message: "No file can reach this conversion to \(destination.rawValue.uppercased())."))196 continue197 }198 var unsupported: [FormatID] = []199 for format in flow.formats.sorted() where !(format == destination && operation == nil) {200 if (try? planner.plan(from: format, to: destination, operation: operation)) == nil { unsupported.append(format) }201 }202 let operationText = operation.map { " (\($0))" } ?? ""203 if !unsupported.isEmpty, strict || unsupported.count == flow.formats.count {204 let list = unsupported.prefix(8).map { $0.rawValue.uppercased() }.joined(separator: ", ") + (unsupported.count > 8 ? "…" : "")205 issues.append(WorkflowIssue(severity: .error, nodePath: path,206 message: "No conversion to \(destination.rawValue.uppercased())\(operationText) exists for: \(list)."))207 }208 flow.unconverted = flow.unconverted && operation == nil && flow.formats.contains(destination)209 flow.formats = [destination]210 case .rename(let template):211 if template.trimmingCharacters(in: .whitespaces).isEmpty {212 issues.append(WorkflowIssue(severity: .error, nodePath: path, message: "The name template is empty."))213 }214 case .filter(let condition):215 flow.formats = narrow(flow.formats, condition, true)216 case .branch(let condition, let then, let otherwise):217 let yes = narrow(flow.formats, condition, true), no = narrow(flow.formats, condition, false)218 let a = walk(then, Flow(formats: yes, unconverted: flow.unconverted, exportedAny: flow.exportedAny), prefix: path + ".then.")219 let b = walk(otherwise, Flow(formats: no, unconverted: flow.unconverted, exportedAny: flow.exportedAny), prefix: path + ".otherwise.")220 flow = Flow(formats: a.formats.union(b.formats), unconverted: a.unconverted || b.unconverted, exportedAny: a.exportedAny && b.exportedAny)221 case .export(let folder, let policy):222 if folder.path.isEmpty {223 issues.append(WorkflowIssue(severity: .error, nodePath: path, message: "The export folder is not set."))224 }225 if policy == .askUser {226 issues.append(WorkflowIssue(severity: .warning, nodePath: path,227 message: "A workflow cannot ask: with this policy an existing file is reported as an error for that item."))228 }229 exported.formUnion(flow.formats)230 if flow.unconverted, !flow.formats.isEmpty { exportsUnconverted = true }231 flow.exportedAny = true232 }233 }234 return flow235 }236237 if workflow.nodes.isEmpty {238 issues.append(WorkflowIssue(severity: .error, nodePath: "", message: "The workflow has no step."))239 }240 let universe = inputFormats ?? Set(registry.sourceFormats)241 let end = walk(workflow.nodes, Flow(formats: universe, unconverted: true, exportedAny: false), prefix: "")242 if !end.exportedAny, !workflow.nodes.isEmpty {243 // Implicit export at the end of the paths that have none.244 exported.formUnion(end.formats)245 if end.unconverted, !end.formats.isEmpty { exportsUnconverted = true }246 issues.append(WorkflowIssue(severity: .warning, nodePath: "", message: "Some paths have no export step: their results are written to the default folder (next to the source unless the run says otherwise)."))247 }248 return WorkflowValidation(issues: issues, exportedFormats: exported, canExportUnconverted: exportsUnconverted)249 }250}251252// MARK: - Running253254public enum WorkflowError: Error, Sendable, LocalizedError {255 case invalid(WorkflowValidation)256 case notFound257 case storage(String)258259 public var errorDescription: String? {260 switch self {261 case .invalid(let validation):262 "The workflow cannot run. " + validation.errors.map { ($0.nodePath.isEmpty ? "" : "Step \($0.nodePath): ") + $0.message }.joined(separator: " ")263 case .notFound: "The workflow no longer exists."264 case .storage(let m): "Workflows could not be saved. \(m)"265 }266 }267}268269public struct WorkflowItemResult: Sendable, Identifiable {270 public enum Status: String, Sendable, Codable {271 /// Every node ran.272 case succeeded273 /// The file went through, but a node failed and was skipped (`continueItem`).274 case succeededWithErrors275 /// A filter excluded the file.276 case filtered277 case failed278 case cancelled279 }280281 public let source: URL282 public var status: Status283 /// Files written by export nodes.284 public var outputs: [URL] = []285 public var errors: [String] = []286 public var warnings: [ConversionWarning] = []287 /// Queue jobs created for this file.288 public var jobIDs: [UUID] = []289 public var log: [String] = []290 public var id: URL { source }291}292293public struct WorkflowRunResult: Sendable {294 public let runID: UUID295 public let workflowID: UUID296 public let startedAt: Date297 public let finishedAt: Date298 /// One result per input, in input order.299 public let items: [WorkflowItemResult]300 public func count(_ status: WorkflowItemResult.Status) -> Int { items.filter { $0.status == status }.count }301}302303public struct WorkflowRunOptions: Sendable {304 /// Where paths without an export node write (default: next to each source file).305 public var defaultExportFolder: URL?306 public var defaultConflictPolicy: ConflictPolicy307 /// Files processed at once by the runner (the queue still decides how many conversions actually run).308 public var maxConcurrentItems: Int309 public var priority: JobPriority310 /// Write a run row in the history store.311 public var recordRun: Bool312313 public init(defaultExportFolder: URL? = nil, defaultConflictPolicy: ConflictPolicy = .rename, maxConcurrentItems: Int = 8,314 priority: JobPriority = .normal, recordRun: Bool = true) {315 self.defaultExportFolder = defaultExportFolder; self.defaultConflictPolicy = defaultConflictPolicy316 self.maxConcurrentItems = max(1, maxConcurrentItems); self.priority = priority; self.recordRun = recordRun317 }318}319320/// Runs workflows over batches of files.321///322/// Each convert node becomes a job of the `ConversionQueue` (so resource limits, logs and cancellation apply), whose323/// output stays in the run's private work directory until an export node copies it out. A convert node producing324/// several files (pages, slides) makes the following nodes apply to each of them; conditions are evaluated on the325/// first. Cancelling the task that called `run` cancels the outstanding jobs; files already exported stay.326public struct WorkflowRunner: Sendable {327 public let queue: ConversionQueue328 public let history: ConversionHistoryStore?329 public let workDirectories: WorkDirectoryManager330331 public init(queue: ConversionQueue, history: ConversionHistoryStore? = nil, workDirectories: WorkDirectoryManager = WorkDirectoryManager()) {332 self.queue = queue; self.history = history; self.workDirectories = workDirectories333 }334335 /// Validates then runs `workflow` on every input.336 ///337 /// - Parameter onItem: called as each file ends (from a background task).338 /// - Throws: `WorkflowError.invalid` when the workflow has validation errors; nothing is started in that case.339 public func run(_ workflow: Workflow, inputs: [URL], options: WorkflowRunOptions = WorkflowRunOptions(),340 onItem: (@Sendable (WorkflowItemResult) -> Void)? = nil) async throws -> WorkflowRunResult {341 let validation = WorkflowValidator.validate(workflow, registry: queue.registry)342 guard validation.isValid else { throw WorkflowError.invalid(validation) }343 let runID = UUID()344 let started = Date()345 let runDirectory = try workDirectories.create()346 defer { workDirectories.remove(runDirectory) }347348 var results = [WorkflowItemResult?](repeating: nil, count: inputs.count)349 await withTaskGroup(of: (Int, WorkflowItemResult).self) { group in350 var next = 0351 func submit() {352 guard next < inputs.count else { return }353 let index = next354 next += 1355 group.addTask {356 let processor = ItemProcessor(runner: self, workflow: workflow, options: options, runID: runID, index: index, source: inputs[index],357 directory: runDirectory.appendingPathComponent("item-\(index + 1)", isDirectory: true))358 let result = await processor.process()359 onItem?(result)360 return (index, result)361 }362 }363 for _ in 0..<min(options.maxConcurrentItems, inputs.count) { submit() }364 for await (index, result) in group {365 results[index] = result366 submit()367 }368 }369 let items = results.enumerated().map { index, result in370 result ?? WorkflowItemResult(source: inputs[index], status: .cancelled)371 }372 let run = WorkflowRunResult(runID: runID, workflowID: workflow.id, startedAt: started, finishedAt: Date(), items: items)373 if options.recordRun, let history {374 let record = WorkflowRunRecord(375 id: runID, workflowID: workflow.id, workflowName: workflow.name, startedAt: started, finishedAt: run.finishedAt, itemCount: items.count,376 succeeded: run.count(.succeeded) + run.count(.succeededWithErrors), failed: run.count(.failed), filtered: run.count(.filtered),377 cancelled: run.count(.cancelled),378 items: items.map { WorkflowRunRecord.Item(sourcePath: $0.source.path, status: $0.status.rawValue, outputPaths: $0.outputs.map(\.path), error: $0.errors.first) })379 try? await history.recordWorkflowRun(record)380 }381 return run382 }383}384385/// What a convert step does with a file that already has the step's destination format (no named operation).386///387/// The rule: the file is converted again **only when a real same-format path exists and the step sets at least one388/// option to something other than its default** ("images → JPEG, long edge 2000 px" resizes the JPEGs too). A step389/// without settings passes such a file on unchanged — re-encoding a JPEG to JPEG for nothing would only lose quality.390/// Named operations (`image.optimize`, `subtitle.retime`, `pdf.compress`…) are not concerned: they always run.391public enum SameFormatRule {392 public enum Decision: Sendable, Equatable {393 /// A same-format path exists and a setting differs from its default: run the conversion.394 case run395 /// Nothing to apply: the file goes on unchanged.396 case passThrough397 /// Settings were given but no same-format path exists: the file goes on unchanged, and that must be said.398 case settingsIgnored399 }400401 public static func decide(format: FormatID, options: ConversionOptions, registry: FormatRegistry) -> Decision {402 let paths = registry.paths(from: format, to: format, operation: .some(nil)).sorted { ConversionCapabilityResolver.prefers($0, over: $1) }403 guard let path = paths.first, let engine = registry.engine(id: path.engine) else {404 return options.values.isEmpty ? .passThrough : .settingsIgnored405 }406 let defaults = Dictionary(engine.options(for: path).map { ($0.id, $0.defaultValue) }, uniquingKeysWith: { first, _ in first })407 let changed = options.values.contains { key, value in408 guard let known = defaults[key] else { return false } // not an option of this path: nothing to apply409 return known != value410 }411 return changed ? .run : .passThrough412 }413}414415/// Processes one input file through a workflow.416private struct ItemProcessor: Sendable {417 let runner: WorkflowRunner418 let workflow: Workflow419 let options: WorkflowRunOptions420 let runID: UUID421 let index: Int422 let source: URL423 let directory: URL424425 private struct State {426 var files: [URL]427 var format: FormatID?428 var converted = false429 var template: String?430 var exported = false431 var conversions = 0432 }433434 private enum Stop: Error { case filtered, failed, cancelled }435436 func process() async -> WorkflowItemResult {437 var result = WorkflowItemResult(source: source, status: .succeeded)438 guard FileManager.default.fileExists(atPath: source.path) else {439 result.status = .failed440 result.errors.append("\(source.lastPathComponent) no longer exists.")441 return result442 }443 let detection = FileTypeDetector.detect(source)444 var state = State(files: [source], format: detection.format)445 result.log.append("Detected \(detection.format?.rawValue ?? "unknown format").")446 do {447 try await run(workflow.nodes, &state, &result)448 if !state.exported { try await implicitExport(&state, &result) }449 if !result.errors.isEmpty { result.status = .succeededWithErrors }450 } catch Stop.filtered {451 result.status = .filtered452 } catch Stop.cancelled {453 result.status = .cancelled454 } catch {455 result.status = Task.isCancelled ? .cancelled : .failed456 }457 return result458 }459460 private func fail(_ message: String, _ result: inout WorkflowItemResult) throws {461 result.errors.append(message)462 result.log.append("Error: \(message)")463 if workflow.errorPolicy == .stopItem { throw Stop.failed }464 }465466 private func run(_ nodes: [WorkflowNode], _ state: inout State, _ result: inout WorkflowItemResult) async throws {467 for node in nodes {468 if Task.isCancelled { throw Stop.cancelled }469 switch node {470 case .convert(let destination, let operation, let conversionOptions):471 try await convert(to: destination, operation: operation, options: conversionOptions, &state, &result)472 case .rename(let template):473 state.template = template474 case .filter(let condition):475 if !(await evaluate(condition, state)) {476 result.log.append("Filtered out.")477 throw Stop.filtered478 }479 case .branch(let condition, let then, let otherwise):480 let taken = await evaluate(condition, state)481 result.log.append("Branch: \(taken ? "then" : "otherwise").")482 try await run(taken ? then : otherwise, &state, &result)483 case .export(let folder, let policy):484 try export(to: folder, policy: policy, &state, &result)485 }486 }487 }488489 private func evaluate(_ condition: WorkflowCondition, _ state: State) async -> Bool {490 guard let file = state.files.first else { return false }491 var inspection: FileInspection?492 if condition.needsInspection {493 inspection = await FileInspector(registry: runner.queue.registry).inspect(file).inspection494 }495 return condition.evaluate(name: file.lastPathComponent, format: state.format, size: FileSizer.size(of: file), inspection: inspection)496 }497498 private func convert(to destination: FormatID, operation: String?, options conversionOptions: ConversionOptions,499 _ state: inout State, _ result: inout WorkflowItemResult) async throws {500 if operation == nil, state.format == destination {501 switch SameFormatRule.decide(format: destination, options: conversionOptions, registry: runner.queue.registry) {502 case .run:503 result.log.append("Already \(destination.rawValue.uppercased()): converted again because the step changes a setting.")504 case .passThrough:505 result.log.append("Already \(destination.rawValue.uppercased()): conversion skipped.")506 return507 case .settingsIgnored:508 result.log.append("Already \(destination.rawValue.uppercased()): conversion skipped.")509 let warning = ConversionWarning(.caution, code: "same-format-settings-ignored",510 "\(source.lastPathComponent) is already \(destination.rawValue.uppercased()) and no \(destination.rawValue.uppercased()) → \(destination.rawValue.uppercased()) conversion exists: it is passed on unchanged, the settings of the step are not applied.")511 if !result.warnings.contains(warning) { result.warnings.append(warning) }512 return513 }514 }515 guard let format = state.format else {516 try fail("The format of \(source.lastPathComponent) could not be recognised.", &result)517 return518 }519 var produced: [URL] = []520 for file in state.files {521 state.conversions += 1522 let stepDirectory = directory.appendingPathComponent("convert-\(state.conversions)", isDirectory: true)523 var request = ConversionJobRequest(524 sources: [file], sourceFormat: format, destinationFormat: destination, operation: operation, options: conversionOptions,525 destination: OutputDestination(directory: stepDirectory, conflictPolicy: .rename), priority: options.priority)526 request.workflowRunID = runID527 request.counter = index + 1528 request.recordInHistory = false529 request.groupMultipleOutputs = false530 let queue = runner.queue531 let id = await queue.enqueue(request)532 result.jobIDs.append(id)533 let job = await withTaskCancellationHandler {534 await queue.waitForJob(id)535 } onCancel: {536 Task { await queue.cancel(id) }537 }538 if Task.isCancelled { throw Stop.cancelled }539 for warning in job?.warnings ?? [] where !result.warnings.contains(warning) { result.warnings.append(warning) }540 guard let job, job.state == .finished else {541 if job?.state == .cancelled { throw Stop.cancelled }542 try fail(job?.error ?? "The conversion to \(destination.rawValue.uppercased()) did not finish.", &result)543 return544 }545 produced += job.outputs.filter { $0.outcome != .skipped }.map(\.url)546 }547 guard !produced.isEmpty else {548 try fail("The conversion to \(destination.rawValue.uppercased()) produced no file.", &result)549 return550 }551 result.log.append("Converted to \(destination.rawValue.uppercased()) (\(produced.count) file\(produced.count == 1 ? "" : "s")).")552 state.files = produced553 state.format = destination554 state.converted = true555 }556557 private func export(to folder: URL, policy: ConflictPolicy, _ state: inout State, _ result: inout WorkflowItemResult) throws {558 let originalBase = source.deletingPathExtension().lastPathComponent559 var names: [String] = []560 for file in state.files {561 guard let template = state.template else { names.append(file.lastPathComponent); continue }562 let base = OutputNameTemplate.render(template, OutputNameContext(source: source, counter: index + 1))563 let stem = file.deletingPathExtension().lastPathComponent564 // Keep the engine's own suffix ("-1", "-2"… for pages) after the rendered name.565 let suffix = stem.hasPrefix(originalBase) ? String(stem.dropFirst(originalBase.count)) : (state.files.count > 1 ? "-\(names.count + 1)" : "")566 names.append(OutputNameTemplate.fileName(base: base + suffix, ext: file.pathExtension))567 }568 // Several files from one input (pages, slides): one folder named after the input, like the queue does.569 var folder = folder570 if state.files.count > 1 {571 let base = state.template.map { OutputNameTemplate.render($0, OutputNameContext(source: source, counter: index + 1)) } ?? originalBase572 let wanted = OutputNameTemplate.fileName(base: base, ext: "")573 folder = policy == .rename ? (SafeWriter.resolvedDestination(name: wanted, in: folder, policy: .rename) ?? folder.appendingPathComponent(wanted))574 : folder.appendingPathComponent(wanted, isDirectory: true)575 }576 do {577 let committed = try SafeWriter.commit(state.files, names: names, to: folder, policy: policy, sources: [source], copy: true)578 let written = committed.filter { $0.outcome != .skipped }.map(\.url)579 result.outputs += written580 result.log.append(written.isEmpty ? "Export skipped: the files already exist in \(folder.path)." : "Exported \(written.count) file\(written.count == 1 ? "" : "s") to \(folder.path).")581 state.exported = true582 } catch {583 try fail((error as? LocalizedError)?.errorDescription ?? error.localizedDescription, &result)584 }585 }586587 /// Paths without an export node: write to the default folder, or next to the source. Nothing is written when588 /// the file is unchanged and would land in its own folder.589 private func implicitExport(_ state: inout State, _ result: inout WorkflowItemResult) async throws {590 let folder = options.defaultExportFolder ?? source.deletingLastPathComponent()591 let sameFolder = folder.standardizedFileURL.path == source.deletingLastPathComponent().standardizedFileURL.path592 if !state.converted, sameFolder, state.template == nil {593 result.log.append("Nothing to export: the file is unchanged.")594 return595 }596 try export(to: folder, policy: options.defaultConflictPolicy, &state, &result)597 }598}599600// MARK: - Library601602/// The user's saved workflows (JSON in Application Support, written atomically).603public actor WorkflowLibrary {604 private struct File: Codable {605 var version = 1606 var workflows: [Workflow]607 }608609 public nonisolated let fileURL: URL610 private var workflows: [Workflow] = []611 /// Why the stored file could not be loaded, if it could not.612 public private(set) var loadError: String?613614 public init(fileURL: URL = AppPaths.workflowsFile) {615 self.fileURL = fileURL616 if let data = try? Data(contentsOf: fileURL) {617 do { workflows = try JSONDecoder().decode(File.self, from: data).workflows.map { $0.redactingSecrets() } } catch { loadError = error.localizedDescription }618 }619 }620621 public var all: [Workflow] { workflows }622623 public func workflow(id: UUID) -> Workflow? { workflows.first { $0.id == id } }624625 /// Adds or replaces (same identifier) a workflow. Secret option values are never stored (see626 /// `Workflow.redactingSecrets`).627 public func save(_ workflow: Workflow) throws {628 let workflow = workflow.redactingSecrets()629 if let index = workflows.firstIndex(where: { $0.id == workflow.id }) { workflows[index] = workflow } else { workflows.append(workflow) }630 try persist()631 }632633 public func delete(id: UUID) throws {634 guard let index = workflows.firstIndex(where: { $0.id == id }) else { throw WorkflowError.notFound }635 workflows.remove(at: index)636 try persist()637 }638639 @discardableResult640 public func duplicate(id: UUID, name: String? = nil) throws -> Workflow {641 guard var copy = workflow(id: id) else { throw WorkflowError.notFound }642 copy.id = UUID()643 copy.name = name ?? copy.name + " copy"644 workflows.append(copy)645 try persist()646 return copy647 }648649 /// JSON for the given workflows (all when `ids` is `nil`).650 public func exportData(ids: [UUID]? = nil) throws -> Data {651 let selected = ids.map { wanted in workflows.filter { wanted.contains($0.id) } } ?? workflows652 let encoder = JSONEncoder()653 encoder.outputFormatting = [.prettyPrinted, .sortedKeys]654 do { return try encoder.encode(File(workflows: selected)) } catch { throw WorkflowError.storage(error.localizedDescription) }655 }656657 /// Imports workflows from exported JSON with new identifiers.658 @discardableResult659 public func importData(_ data: Data) throws -> [Workflow] {660 let file: File661 do { file = try JSONDecoder().decode(File.self, from: data) } catch { throw WorkflowError.storage("The file is not a workflow export: \(error.localizedDescription)") }662 let imported = file.workflows.prefix(10_000).map { workflow -> Workflow in663 var copy = workflow.redactingSecrets()664 copy.id = UUID()665 return copy666 }667 workflows += imported668 try persist()669 return imported670 }671672 private func persist() throws {673 do {674 try FileManager.default.createDirectory(at: fileURL.deletingLastPathComponent(), withIntermediateDirectories: true)675 let encoder = JSONEncoder()676 encoder.outputFormatting = [.prettyPrinted, .sortedKeys]677 try encoder.encode(File(workflows: workflows)).write(to: fileURL, options: .atomic)678 loadError = nil679 } catch {680 throw WorkflowError.storage(error.localizedDescription)681 }682 }683}684