Add CLI calibration and automation for beta.18

.github/workflows/ci.yml

@@ -33,6 +33,8 @@ jobs:
       - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable 2026-08-05
         with:
           toolchain: '1.97.1'
+      - name: Install ExifTool for metadata-copy tests
+        run: brew install exiftool
       - name: Verify exact Rust toolchain
         run: python3 -I -S -B scripts/verify_pinned_rust.py
       - name: Test Swift app and Rust engine

app/ScanStudio/Sources/ScanStudio/BatchInspectorView.swift

@@ -10,6 +10,13 @@ struct BatchInspectorView: View {
     @State private var rawSettingsExpanded = false
     @State private var positiveTiffSettingsExpanded = false
     @State private var positiveJPEGSettingsExpanded = false
+    @State private var namedPresetNames: [String] = []
+    @State private var presetError: String?
+    @State private var reportError: String?
+    @State private var renderError: String?
+    @State private var metadataCopyPreview: ControlMetadataApplyResult?
+    @State private var metadataCopyResult: ControlMetadataApplyResult?
+    @State private var renderProfile = "sRGB"
     @FocusState private var focusedGearField: GearField?
     @State private var presentedRecentGear: GearField?
 
@@ -56,6 +63,7 @@ struct BatchInspectorView: View {
         // project) so `sessionModel.exifToolDetection` is already populated
         // before the user ever opens a frame detail view's ExifTool panel.
         .task { await sessionModel.detectExifTool() }
+        .task { refreshNamedPresets() }
         .alert("Saved file unavailable", isPresented: Binding(
             get: { missingSavedOutput != nil },
             set: { if !$0 { missingSavedOutput = nil } }
@@ -64,6 +72,30 @@ struct BatchInspectorView: View {
         } message: {
             Text("The recorded file is no longer at this location. It may have been moved or deleted.\n\(missingSavedOutput ?? "")")
         }
+        .alert("Preset unavailable", isPresented: Binding(
+            get: { presetError != nil },
+            set: { if !$0 { presetError = nil } }
+        )) {
+            Button("OK", role: .cancel) { presetError = nil }
+        } message: {
+            Text(presetError ?? "The preset could not be loaded.")
+        }
+        .alert("Roll report unavailable", isPresented: Binding(
+            get: { reportError != nil },
+            set: { if !$0 { reportError = nil } }
+        )) {
+            Button("OK", role: .cancel) { reportError = nil }
+        } message: {
+            Text(reportError ?? "The HTML report could not be written.")
+        }
+        .alert("Re-render unavailable", isPresented: Binding(
+            get: { renderError != nil },
+            set: { if !$0 { renderError = nil } }
+        )) {
+            Button("OK", role: .cancel) { renderError = nil }
+        } message: {
+            Text(renderError ?? "The retained master could not be rendered.")
+        }
     }
 
     @ViewBuilder
@@ -81,6 +113,26 @@ struct BatchInspectorView: View {
                     revealSavedFile(URL(fileURLWithPath: directory))
                 }
                 .controlSize(.small)
+                Button("Generate HTML Report") {
+                    generateRollReport(directory: directory)
+                }
+                .controlSize(.small)
+                if let frameIndex = sessionModel.detailFrameIndex ?? sessionModel.frameTransformTargetIndex {
+                    HStack(spacing: 6) {
+                        Menu {
+                            ForEach(["sRGB", "AdobeRGB1998", "ProPhotoRGB"], id: \.self) { profile in
+                                Button(profile) { renderProfile = profile }
+                            }
+                        } label: {
+                            Label("Profile: \(renderProfile)", systemImage: "paintpalette")
+                        }
+                        .controlSize(.small)
+                        Button("Re-render selected") {
+                            renderSelected(frameIndex: frameIndex, projectDirectory: directory)
+                        }
+                        .controlSize(.small)
+                    }
+                }
                 if let frameIndex = sessionModel.detailFrameIndex ?? sessionModel.frameTransformTargetIndex {
                     let receipt = sessionModel.receipts.last(where: { $0.frameIndex == frameIndex })
                         ?? sessionModel.project?.frames.first(where: { $0.index == frameIndex })?.receipts.last
@@ -115,6 +167,50 @@ struct BatchInspectorView: View {
         NSWorkspace.shared.activateFileViewerSelecting([url])
     }
 
+    private func generateRollReport(directory: String) {
+        Task {
+            do {
+                let result = try await Task.detached(priority: .userInitiated) {
+                    try RollHTMLReport.write(projectDirectory: URL(fileURLWithPath: directory))
+                }.value
+                NSWorkspace.shared.open(URL(fileURLWithPath: result.path))
+            } catch {
+                reportError = error.localizedDescription
+            }
+        }
+    }
+
+    private func renderSelected(frameIndex: Int, projectDirectory: String) {
+        let output = URL(fileURLWithPath: projectDirectory).appendingPathComponent("Rendered-\(renderProfile)")
+        Task {
+            guard let result = await sessionModel.renderRoll(ControlRollRenderParams(
+                frames: [frameIndex], profile: renderProfile, output: output.path
+            )) else {
+                renderError = sessionModel.lastErrorMessage ?? "The retained master could not be rendered."
+                return
+            }
+            if let first = result.files.first {
+                NSWorkspace.shared.activateFileViewerSelecting([URL(fileURLWithPath: first.path)])
+            }
+        }
+    }
+
+    private func refreshNamedPresets() {
+        namedPresetNames = (try? ScanRecipePresetStore().list()) ?? []
+    }
+
+    private func applyNamedPreset(_ name: String) {
+        do {
+            let preset = try ScanRecipePresetStore().load(named: name)
+            // The shared SessionModel path applies capture settings while
+            // retaining the project's persisted exposure lock.
+            sessionModel.applySettingsRecipes(capture: preset.capture, processing: preset.processing)
+            sessionModel.applyOutputRecipe(preset.output)
+        } catch {
+            presetError = String(describing: error)
+        }
+    }
+
     private var setupInspector: some View {
         Group {
             InspectorSection(title: "Scan Settings") {
@@ -129,6 +225,21 @@ struct BatchInspectorView: View {
                         }
                     }
                 }
+                InspectorSettingRow(label: "Saved preset") {
+                    Menu {
+                        if namedPresetNames.isEmpty {
+                            Text("No saved presets")
+                        } else {
+                            ForEach(namedPresetNames, id: \.self) { name in
+                                Button(name) { applyNamedPreset(name) }
+                            }
+                        }
+                        Divider()
+                        Button("Refresh") { refreshNamedPresets() }
+                    } label: {
+                        Label("Choose…", systemImage: "bookmark")
+                    }
+                }
                 if sessionModel.scanRecipePreset == .custom {
                     Label("This recipe has manual changes.", systemImage: "slider.horizontal.3")
                         .font(.system(size: 10))
@@ -304,6 +415,32 @@ struct BatchInspectorView: View {
                 .padding(.bottom, 6)
 
                 InspectorRow(label: "ExifTool", value: exifToolStatusSummary)
+                HStack(spacing: 8) {
+                    Button("Preview copy metadata") {
+                        Task { metadataCopyPreview = await sessionModel.applyMetadataCopies(metadataCopyParams(dryRun: true)) }
+                    }
+                    .buttonStyle(.bordered)
+                    .controlSize(.small)
+                    .disabled(sessionModel.exifToolDetection?.available != true || metadataCopyFrames.isEmpty)
+                    Button("Apply to new copies") {
+                        Task { metadataCopyResult = await sessionModel.applyMetadataCopies(metadataCopyParams(dryRun: false)) }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .tint(.scanStudioAmber)
+                    .controlSize(.small)
+                    .disabled(metadataCopyPreview == nil)
+                }
+                if let preview = metadataCopyPreview {
+                    Text(preview.arguments.isEmpty ? "No metadata fields are set." : preview.arguments.joined(separator: " "))
+                        .font(.system(size: 10, design: .monospaced))
+                        .foregroundStyle(Color.scanStudioSecondaryText)
+                        .textSelection(.enabled)
+                }
+                if let result = metadataCopyResult {
+                    Text("Created \(result.files.count) metadata cop\(result.files.count == 1 ? "y" : "ies") in a new directory.")
+                        .font(.system(size: 10))
+                        .foregroundStyle(Color.scanStudioCyan)
+                }
             }
             InspectorSection(title: "Estimated Size") {
                 InspectorRow(
@@ -361,6 +498,24 @@ struct BatchInspectorView: View {
         }
     }
 
+    private var metadataCopyFrames: [Int] {
+        sessionModel.project?.frames.filter { !$0.receipts.isEmpty }.map(\.index) ?? []
+    }
+
+    private func metadataCopyParams(dryRun: Bool) -> ControlRollMetadataApplyParams {
+        let destination = URL(fileURLWithPath: sessionModel.positiveDestination)
+            .appendingPathComponent("Metadata Copies", isDirectory: true)
+            .standardizedFileURL.path
+        return ControlRollMetadataApplyParams(
+            frames: metadataCopyFrames,
+            to: destination,
+            template: sessionModel.positiveFilenameTemplate,
+            kind: "positive",
+            metadata: sessionModel.rollMetadataDraft,
+            dryRun: dryRun
+        )
+    }
+
     private var saveOutputsSection: some View {
         InspectorSection(title: "Outputs for next scan") {
             Label(

app/ScanStudio/Sources/ScanStudioKit/CalibrationWireProtocol.swift

@@ -0,0 +1,102 @@
+import Foundation
+
+public struct ControlRollVerifyParams: Codable, Equatable, Sendable {
+    public var pass: String?
+    public var exposureIdentical: Bool
+    public var noClipping: Bool
+
+    public init(pass: String? = nil, exposureIdentical: Bool = false, noClipping: Bool = false) {
+        self.pass = pass
+        self.exposureIdentical = exposureIdentical
+        self.noClipping = noClipping
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case pass, exposureIdentical, noClipping
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        pass = try container.decodeIfPresent(String.self, forKey: .pass)
+        exposureIdentical = try container.decodeIfPresent(Bool.self, forKey: .exposureIdentical) ?? false
+        noClipping = try container.decodeIfPresent(Bool.self, forKey: .noClipping) ?? false
+    }
+}
+
+public struct CalibrationVerificationIssue: Codable, Equatable, Sendable {
+    public var status: String
+    public var jobId: String?
+    public var frameIndex: Int?
+    public var field: String
+    public var detail: String
+}
+
+public struct CalibrationVerificationReport: Codable, Equatable, Sendable {
+    public var status: String
+    public var exposureIdentical: Bool
+    public var noClipping: Bool
+    public var checkedReceipts: Int
+    public var issues: [CalibrationVerificationIssue]
+}
+
+public struct CalibrationCollectionMetadata: Codable, Equatable, Sendable {
+    public var stock: String
+    public var pass: String
+    public var slotMap: [String: Int]
+    public var firmware: String?
+    public var adapter: String?
+    public var host: String?
+    public var operatorName: String?
+    public var appVersion: String?
+    public var driverVersion: String?
+
+    enum CodingKeys: String, CodingKey {
+        case stock, pass, slotMap, firmware, adapter, host, appVersion, driverVersion
+        case operatorName = "operator"
+    }
+
+    public init(
+        stock: String,
+        pass: String,
+        slotMap: [String: Int],
+        firmware: String? = nil,
+        adapter: String? = nil,
+        host: String? = nil,
+        operatorName: String? = nil,
+        appVersion: String? = nil,
+        driverVersion: String? = nil
+    ) {
+        self.stock = stock
+        self.pass = pass
+        self.slotMap = slotMap
+        self.firmware = firmware
+        self.adapter = adapter
+        self.host = host
+        self.operatorName = operatorName
+        self.appVersion = appVersion
+        self.driverVersion = driverVersion
+    }
+}
+
+public struct ControlRollCollectParams: Codable, Equatable, Sendable {
+    public var to: String
+    public var metadata: CalibrationCollectionMetadata
+
+    public init(to: String, metadata: CalibrationCollectionMetadata) {
+        self.to = to
+        self.metadata = metadata
+    }
+}
+
+public struct CalibrationCollectedFile: Codable, Equatable, Sendable {
+    public var path: String
+    public var byteLength: UInt64
+    public var sha256: String
+}
+
+public struct CalibrationCollectionResult: Codable, Equatable, Sendable {
+    public var destination: String
+    public var files: [CalibrationCollectedFile]
+    public var metadataPath: String
+    public var hashesPath: String
+}

app/ScanStudio/Sources/ScanStudioKit/ControlCLISupport.swift

@@ -26,8 +26,10 @@ public enum ControlCLIExitCode: Int32, Sendable {
     case noHostReachable = 69
     case internalError = 70
     case busy = 75
+    case hostExited = 76
     case confirmationRequired = 77
     case schemaVersionMismatch = 78
+    case waitTimedOut = 124
 
     /// Maps a wire-level error `code` (either `ControlErrorPayload.code`
     /// from the channel, or one of `ControlCLIErrorCode`'s own strings) onto
@@ -55,6 +57,8 @@ public enum ControlCLIExitCode: Int32, Sendable {
         case ControlErrorCode.schemaVersionMismatch.rawValue,
              ControlErrorCode.helloRequired.rawValue:
             return .schemaVersionMismatch
+        case ControlCLIErrorCode.waitTimeout.rawValue:
+            return .waitTimedOut
         default:
             // GATE_REFUSED, JOB_NOT_FOUND, and every engine/bridge
             // passthrough code land here (65) -- see the doc comment above.
@@ -75,6 +79,7 @@ public enum ControlCLIErrorCode: String, Sendable {
     case jobNotFound = "JOB_NOT_FOUND"
     case internalCode = "INTERNAL"
     case hostAlreadyRunning = "HOST_ALREADY_RUNNING"
+    case waitTimeout = "WAIT_TIMEOUT"
 }
 
 // MARK: - Output envelope (D-09/OUT-01)
@@ -445,6 +450,7 @@ public struct ControlRunReceipt: Codable, Equatable, Sendable {
     /// attempted or the write failed, so a caller can tell "no project
     /// directory yet" and "write failed" apart from "here is the file."
     public var receiptPath: String?
+    public var approvedJobPath: String?
 
     public init() {}