@swmansion/argent 0.23.0 → 0.23.1-next.0

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/RunnerHTTPServer.swift

@@ -0,0 +1,267 @@
+import Foundation
+import Network
+
+/// Minimal single-purpose HTTP/1.1 endpoint on NWListener: each connection
+/// carries one POSTed JSON command and receives one JSON reply, then closes.
+///
+/// The listener is unauthenticated, so it binds loopback-only. The host
+/// reaches the runner through a usbmux forwarded stream that terminates on
+/// the device's own loopback. Bodies are opaque bytes handed to the
+/// dispatch closure.
+final class RunnerHTTPServer {
+    struct Reply {
+        let status: Int
+        let body: Data
+        /// When set, the server invokes `onFinish` after this reply has been
+        /// flushed. The shutdown acknowledgement must reach the client before
+        /// the session ends.
+        let finishAfterSend: Bool
+
+        init(status: Int, body: Data, finishAfterSend: Bool = false) {
+            self.status = status
+            self.body = body
+            self.finishAfterSend = finishAfterSend
+        }
+    }
+
+    /// Upper bound on the size of one request. Each request carries a single
+    /// command, so a larger body indicates a client bug.
+    private static let maxRequestBytes = 2 * 1024 * 1024
+    private let queue = DispatchQueue(label: "argent.runner.transport")
+    private let dispatch: (Data, @escaping (Reply) -> Void) -> Void
+    /// The clean end of the session, after a shutdown reply has been flushed.
+    private let onFinish: () -> Void
+    /// The listener can no longer accept connections (the port is in use, the
+    /// interface is unavailable). Carries the failure description.
+    private let onListenerFailure: (String) -> Void
+    private var listener: NWListener?
+
+    init(
+        dispatch: @escaping (Data, @escaping (Reply) -> Void) -> Void,
+        onFinish: @escaping () -> Void,
+        onListenerFailure: @escaping (String) -> Void
+    ) {
+        self.dispatch = dispatch
+        self.onFinish = onFinish
+        self.onListenerFailure = onListenerFailure
+    }
+
+    /// Starts listening on loopback, on the given port or a system-assigned
+    /// one when the port is 0.
+    func start(port: UInt16) throws {
+        // Restrict to the loopback interface rather than pinning a 127.0.0.1
+        // endpoint. The interface restriction admits either address family and
+        // keeps port-0 auto-assignment and the .port readback working.
+        let parameters = NWParameters.tcp
+        parameters.requiredInterfaceType = .loopback
+        let listener: NWListener
+
+        if port > 0, let nwPort = NWEndpoint.Port(rawValue: port) {
+            listener = try NWListener(using: parameters, on: nwPort)
+        } else {
+            listener = try NWListener(using: parameters)
+        }
+
+        listener.stateUpdateHandler = { [weak self] state in
+            switch state {
+            case .ready:
+                NSLog(
+                    "ARGENT_RUNNER_LISTENING port=%d",
+                    Int(self?.listener?.port?.rawValue ?? 0)
+                )
+            case .failed(let error):
+                // A failed listener can never receive another command. Hand the
+                // failure to the session so it ends as a failed test, and the
+                // host observes a failing exit instead of a silent hang or a
+                // green run that never served.
+                let description = String(describing: error)
+                NSLog("ARGENT_RUNNER_LISTENER_FAILED error=%@", description)
+                self?.onListenerFailure(description)
+            default:
+                break
+            }
+        }
+
+        listener.newConnectionHandler = { [weak self] connection in
+            guard let self else { return }
+            connection.start(queue: self.queue)
+            self.receive(on: connection, buffered: Data())
+        }
+
+        self.listener = listener
+        listener.start(queue: queue)
+    }
+
+    /// Stops accepting connections.
+    func stop() {
+        listener?.cancel()
+        listener = nil
+    }
+
+    /// Accumulates bytes from one connection until the buffered request is
+    /// complete, then dispatches its body.
+    private func receive(on connection: NWConnection, buffered: Data) {
+        connection.receive(minimumIncompleteLength: 1, maximumLength: 1 << 20) {
+            [weak self] data, _, _, _ in
+
+            guard let self, let data, !data.isEmpty else {
+                connection.cancel()
+                return
+            }
+
+            var buffer = buffered
+            buffer.append(data)
+
+            if buffer.count > Self.maxRequestBytes {
+                self.send(
+                    Reply(
+                        status: 413,
+                        body: Self.oversizedRequestBody(
+                            limit: Self.maxRequestBytes
+                        )
+                    ),
+                    over: connection
+                )
+                return
+            }
+
+            switch Self.requestVerdict(in: buffer) {
+            case .complete(let body):
+                self.dispatch(body) { reply in
+                    self.send(reply, over: connection)
+                }
+            case .incomplete:
+                self.receive(on: connection, buffered: buffer)
+            case .malformed:
+                self.send(
+                    Reply(status: 400, body: Self.malformedRequestBody()),
+                    over: connection
+                )
+            case .oversized:
+                self.send(
+                    Reply(
+                        status: 413,
+                        body: Self.oversizedRequestBody(
+                            limit: Self.maxRequestBytes
+                        )
+                    ),
+                    over: connection
+                )
+            }
+        }
+    }
+
+    /// Writes the HTTP reply, closes the connection, and triggers `onFinish`
+    /// for a reply marked `finishAfterSend`.
+    private func send(_ reply: Reply, over connection: NWConnection) {
+        let head = [
+            "HTTP/1.1 \(reply.status) \(reply.status == 200 ? "OK" : "Error")",
+            "Content-Type: application/json",
+            "Content-Length: \(reply.body.count)",
+            "Connection: close",
+            "",
+            "",
+        ].joined(separator: "\r\n")
+
+        var payload = Data(head.utf8)
+        payload.append(reply.body)
+
+        connection.send(
+            content: payload,
+            isComplete: true,
+            completion: .contentProcessed { [weak self] error in
+                if let error {
+                    NSLog(
+                        "ARGENT_RUNNER_SEND_FAILED error=%@",
+                        String(describing: error)
+                    )
+                }
+
+                connection.cancel()
+
+                if reply.finishAfterSend {
+                    self?.onFinish()
+                }
+            }
+        )
+    }
+
+    /// Verdict on the bytes buffered so far for one request.
+    enum RequestVerdict: Equatable {
+        /// The header block or declared body has not fully arrived. Keep
+        /// receiving.
+        case incomplete
+        /// A full request. The payload is the raw body bytes.
+        case complete(Data)
+        /// The header block ended without a usable Content-Length. Later bytes
+        /// cannot repair a finished header block, so waiting for more would
+        /// hang the connection.
+        case malformed
+        /// The declared Content-Length exceeds `maxRequestBytes`. The request
+        /// is rejected before its body arrives.
+        case oversized
+    }
+
+    /// Classifies the buffered bytes as an incomplete, complete, malformed,
+    /// or oversized request.
+    static func requestVerdict(in buffer: Data) -> RequestVerdict {
+        guard let headEnd = buffer.range(of: Data("\r\n\r\n".utf8)) else {
+            return .incomplete
+        }
+
+        let head = String(
+            decoding: buffer.subdata(
+                in: buffer.startIndex..<headEnd.lowerBound
+            ),
+            as: UTF8.self
+        )
+
+        var contentLength: Int?
+
+        for line in head.split(separator: "\r\n") {
+            let parts = line.split(separator: ":", maxSplits: 1)
+            guard parts.count == 2 else { continue }
+
+            if parts[0].trimmingCharacters(in: .whitespaces).lowercased()
+                == "content-length"
+            {
+                contentLength = Int(
+                    parts[1].trimmingCharacters(in: .whitespaces)
+                )
+            }
+        }
+
+        guard let contentLength, contentLength >= 0 else { return .malformed }
+        guard contentLength <= maxRequestBytes else { return .oversized }
+
+        let bodyStart = headEnd.upperBound
+
+        guard
+            buffer.distance(from: bodyStart, to: buffer.endIndex)
+                >= contentLength
+        else { return .incomplete }
+
+        return .complete(
+            buffer.subdata(
+                in: bodyStart..<buffer.index(bodyStart, offsetBy: contentLength)
+            )
+        )
+    }
+
+    /// The INVALID_REQUEST body for a request that exceeds the size limit.
+    private static func oversizedRequestBody(limit: Int) -> Data {
+        Data(
+            #"{"ok":false,"error":{"code":"INVALID_REQUEST","message":"request body exceeds \#(limit) bytes"}}"#
+                .utf8
+        )
+    }
+
+    /// The INVALID_REQUEST body for a header block without a usable
+    /// Content-Length.
+    private static func malformedRequestBody() -> Data {
+        Data(
+            #"{"ok":false,"error":{"code":"INVALID_REQUEST","message":"request headers lack a usable Content-Length"}}"#
+                .utf8
+        )
+    }
+}

package/dist/ios-device-runner/ArgentRunner/ArgentRunnerUITests/RunnerProtocol.swift

@@ -0,0 +1,331 @@
+import Foundation
+
+// MARK: - Argent iOS runner wire protocol (v1)
+//
+// One HTTP POST per command: the request body is a JSON `CommandRequest`, the
+// reply a JSON `Envelope`. PROTOCOL.md at the package root documents the
+// contract. The TypeScript client under
+// packages/tool-server/src/utils/ios-device mirrors these shapes.
+
+enum CommandKind: String, Codable {
+    case status
+    case viewport
+    case tap
+    case longPress
+    case drag
+    case type
+    case keyboardReturn
+    case keyboardDelete
+    case button
+    case snapshot
+    case screenshot
+    case shutdown
+}
+
+extension CommandKind {
+    /// Commands that read state without side effects. The client retries these
+    /// freely. Mutating commands are sent exactly once and recovered through
+    /// the journal via `status` with `statusCommandId`.
+    var isReadOnly: Bool {
+        switch self {
+        case .status, .viewport, .snapshot, .screenshot:
+            return true
+        case .tap, .longPress, .drag, .type, .keyboardReturn, .keyboardDelete,
+            .button, .shutdown:
+            return false
+        }
+    }
+
+    /// Commands that target an app and therefore require `appBundleId`. A
+    /// missing target is treated as a caller error, never redirected to the
+    /// runner's own host app.
+    var requiresAppBundleId: Bool {
+        switch self {
+        case .viewport, .tap, .longPress, .drag, .type, .keyboardReturn,
+            .keyboardDelete, .snapshot:
+            return true
+        case .status, .button, .screenshot, .shutdown:
+            return false
+        }
+    }
+
+    /// Whether the journal keeps the full response JSON for `status` recovery.
+    var retainsResponseInJournal: Bool {
+        switch self {
+        // Snapshot and screenshot replies are large and read-only. The client
+        // reruns them instead of recovering them from the journal, which keeps
+        // them from evicting journaled mutation results.
+        case .snapshot, .screenshot:
+            return false
+        default:
+            return true
+        }
+    }
+
+    /// Main-thread watchdog budget for one command execution. PROTOCOL.md's
+    /// "Timeout budgets" table is the authoritative pairing with the client
+    /// windows.
+    var executionTimeout: TimeInterval {
+        switch self {
+        // XCTest types long strings in real time, so typing needs extra room.
+        case .type: return 55
+        // Gestures must outlast XCTest's ~60s pre-event idle wait. A screen that
+        // never reports quiescent stalls the wait until XCTest gives up and
+        // synthesizes the event anyway, and a shorter budget would abandon a
+        // command that still completes.
+        case .tap, .longPress, .drag: return 75
+        default: return 30
+        }
+    }
+}
+
+/// Hardware buttons the `button` command accepts, mapped onto
+/// `XCUIDevice.Button` in ArgentRunnerSession+Commands.swift so this file
+/// needs no XCTest import. The power/lock button and the app switcher have no
+/// public XCUIDevice API, and `camera` would pin the runner to a newer Xcode.
+enum DeviceButton: String, Codable {
+    case home
+    case volumeUp
+    case volumeDown
+    case actionButton
+}
+
+struct CommandRequest: Codable {
+    let command: CommandKind
+    let commandId: String?
+    /// `status` only: the commandId whose journaled fate is requested.
+    let statusCommandId: String?
+    /// The app the command targets. Required when `command.requiresAppBundleId`.
+    let appBundleId: String?
+    /// `tap`/`longPress`: absolute point (in points) in the app's coordinate space.
+    let x: Double?
+    let y: Double?
+    /// `tap`: number of taps. Defaults to 1; 2 is the native double-tap.
+    /// Higher counts loop single taps on the device: there is no native N-tap
+    /// API, so they land as separate taps, not one multi-tap gesture.
+    let numberOfTaps: Int?
+    /// `drag`: absolute start and end points.
+    let fromX: Double?
+    let fromY: Double?
+    let toX: Double?
+    let toY: Double?
+    /// `longPress`: press duration. `drag`: duration of the movement.
+    let durationMs: Double?
+    /// `drag`: how long the touch rests at the start point before it moves
+    /// (default 50 ms). A long-press pickup, the way a list item is lifted for
+    /// reordering, needs about 500 ms or more.
+    let holdMs: Double?
+    /// `drag`: rest the touch at the destination before lifting so the release
+    /// velocity is near zero and the scroll view does not fling. Mirrors the
+    /// simulator's ease-out `settle` swipe.
+    let settle: Bool?
+    /// `type`: the text delivered to the focused input.
+    let text: String?
+    /// `button`: which hardware button to press.
+    let button: DeviceButton?
+
+    /// The trimmed commandId, nil when absent or blank.
+    var normalizedCommandId: String? {
+        guard
+            let trimmed = commandId?.trimmingCharacters(
+                in: .whitespacesAndNewlines
+            ),
+            !trimmed.isEmpty
+        else { return nil }
+        return trimmed
+    }
+
+    /// The trimmed appBundleId, nil when absent or blank.
+    var normalizedAppBundleId: String? {
+        guard
+            let trimmed = appBundleId?.trimmingCharacters(
+                in: .whitespacesAndNewlines
+            ),
+            !trimmed.isEmpty
+        else { return nil }
+        return trimmed
+    }
+}
+
+/// Stable error codes shared with the TypeScript client. Only RUNNER_BUSY is
+/// client-retryable. RUNNER_WEDGED tells the host to recycle the session.
+enum RunnerErrorCode: String {
+    case invalidRequest = "INVALID_REQUEST"
+    case appBundleIdRequired = "APP_BUNDLE_ID_REQUIRED"
+    case appNotAvailable = "APP_NOT_AVAILABLE"
+    case appBackgrounded = "APP_BACKGROUNDED"
+    case textInputNotFocused = "TEXT_INPUT_NOT_FOCUSED"
+    /// Hardware or an API this device lacks: an absent button, a tap count
+    /// XCUICoordinate cannot execute as one gesture. An XCTest call that
+    /// throws mid-command is COMMAND_FAILED, never this.
+    case unsupportedOperation = "UNSUPPORTED_OPERATION"
+    case runnerBusy = "RUNNER_BUSY"
+    case runnerWedged = "RUNNER_WEDGED"
+    case xctestRecordedFailure = "XCTEST_RECORDED_FAILURE"
+    case snapshotFailed = "SNAPSHOT_FAILED"
+    case commandTimedOut = "COMMAND_TIMED_OUT"
+    case commandFailed = "COMMAND_FAILED"
+}
+
+struct ErrorPayload: Encodable {
+    let code: String
+    let message: String
+    let hint: String?
+}
+
+/// Type-erased Encodable wrapper that lets `Envelope` carry any per-command
+/// payload.
+struct AnyEncodable: Encodable {
+    private let encodeInto: (Encoder) throws -> Void
+    init<T: Encodable>(_ value: T) { self.encodeInto = value.encode(to:) }
+    func encode(to encoder: Encoder) throws { try encodeInto(encoder) }
+}
+
+struct Envelope: Encodable {
+    let ok: Bool
+    let data: AnyEncodable?
+    let error: ErrorPayload?
+    /// True only when the runner re-fronted a backgrounded target app before
+    /// executing the command (see `foregroundTarget`), on ok and error
+    /// envelopes alike: the re-front precedes the command, so a command that
+    /// then failed changed the foreground screen too. nil is omitted from the
+    /// encoded JSON.
+    let reactivated: Bool?
+    /// Advisory on an otherwise-ok reply: set when a mutating command succeeded
+    /// while the suppressed-issue counter grew, meaning the gesture may have
+    /// missed. nil is omitted from the encoded JSON.
+    let warning: String?
+
+    /// An ok envelope carrying the payload.
+    static func success<T: Encodable>(_ payload: T) -> Envelope {
+        Envelope(
+            ok: true,
+            data: AnyEncodable(payload),
+            error: nil,
+            reactivated: nil,
+            warning: nil
+        )
+    }
+
+    /// An error envelope with a stable code, a message, and an optional hint.
+    static func failure(
+        _ code: RunnerErrorCode,
+        _ message: String,
+        hint: String? = nil
+    ) -> Envelope {
+        Envelope(
+            ok: false,
+            data: nil,
+            error: ErrorPayload(
+                code: code.rawValue,
+                message: message,
+                hint: hint
+            ),
+            reactivated: nil,
+            warning: nil
+        )
+    }
+
+    /// A copy of this reply with `reactivated: true`, marking that the target
+    /// app was backgrounded and had to be re-fronted before the command ran.
+    func withReactivated() -> Envelope {
+        Envelope(
+            ok: ok,
+            data: data,
+            error: error,
+            reactivated: true,
+            warning: warning
+        )
+    }
+
+    /// A copy of this reply carrying an advisory `warning`. Composes with
+    /// `withReactivated()`, so a reply can carry both markers.
+    func withWarning(_ warning: String) -> Envelope {
+        Envelope(
+            ok: ok,
+            data: data,
+            error: error,
+            reactivated: reactivated,
+            warning: warning
+        )
+    }
+}
+
+// MARK: - Per-command payloads
+
+struct MessagePayload: Encodable {
+    let message: String
+}
+
+struct HealthPayload: Encodable {
+    let uptimeMs: Double
+    /// "idle" | "busy" | "wedged", the main-thread gate's view of the runner.
+    let state: String
+    /// XCTIssues muted as accessibility noise since launch. Suppression matches
+    /// Apple-owned wording in `ArgentRunnerSession.SuppressedIssueWording`, so
+    /// a count stuck at zero while `recordedFailures` climbs means an Xcode
+    /// release reworded the strings.
+    let suppressedIssues: Int
+    /// XCTest's cumulative recorded-failure count for the session, read from
+    /// `testRun.totalFailureCount`. A failure that gets past suppression turns
+    /// a successful mutation into XCTEST_RECORDED_FAILURE.
+    let recordedFailures: Int
+}
+
+struct CommandStatusPayload: Encodable {
+    let commandId: String
+    /// "notAccepted" | "accepted" | "started" | "completed" | "failed"
+    let state: String
+    let command: String?
+    let responseOk: Bool?
+    /// The completed command's full JSON envelope, when retained.
+    let responseJson: String?
+    let errorCode: String?
+    let errorMessage: String?
+    let errorHint: String?
+}
+
+struct ViewportPayload: Encodable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+}
+
+struct ScreenshotPayload: Encodable {
+    let imageBase64: String
+}
+
+struct SnapshotRect: Encodable {
+    let x: Double
+    let y: Double
+    let width: Double
+    let height: Double
+}
+
+struct SnapshotNodePayload: Encodable {
+    let index: Int
+    let type: String
+    let label: String?
+    let identifier: String?
+    let value: String?
+    let rect: SnapshotRect
+    let enabled: Bool
+    let focused: Bool?
+    let selected: Bool?
+    let depth: Int
+    let parentIndex: Int?
+}
+
+struct SnapshotQualityPayload: Encodable {
+    /// "healthy" | "degraded"
+    let state: String
+    let backend: String
+    let reason: String?
+    let reasonCode: String?
+}
+
+struct SnapshotPayload: Encodable {
+    let nodes: [SnapshotNodePayload]
+    let quality: SnapshotQualityPayload
+}

package/dist/mcp-server.mjs

@@ -16474,6 +16474,18 @@ var FAILURE_CODES = {
   SIMULATOR_COMMAND_REJECTED: "SIMULATOR_COMMAND_REJECTED",
   SIMULATOR_COMMAND_ACK_TIMEOUT: "SIMULATOR_COMMAND_ACK_TIMEOUT",
   SIMULATOR_COMMAND_TRANSPORT_FAILED: "SIMULATOR_COMMAND_TRANSPORT_FAILED",
+  // Physical iOS devices: the XCUITest-runner blueprint lifecycle, the runner
+  // command client, and the `xcrun devicectl` subprocess wrapper (simulators
+  // use the SIMULATOR_* set).
+  IOS_DEVICE_RUNNER_FACTORY_OPTIONS_MISSING: "IOS_DEVICE_RUNNER_FACTORY_OPTIONS_MISSING",
+  IOS_DEVICE_RUNNER_NOT_READY: "IOS_DEVICE_RUNNER_NOT_READY",
+  IOS_DEVICE_RUNNER_TERMINATED: "IOS_DEVICE_RUNNER_TERMINATED",
+  IOS_DEVICE_RUNNER_EXITED: "IOS_DEVICE_RUNNER_EXITED",
+  // The runner answered a command with an ok:false envelope.
+  IOS_DEVICE_RUNNER_COMMAND_FAILED: "IOS_DEVICE_RUNNER_COMMAND_FAILED",
+  // The usbmux or HTTP exchange with a reachable runner failed.
+  IOS_DEVICE_RUNNER_TRANSPORT_FAILED: "IOS_DEVICE_RUNNER_TRANSPORT_FAILED",
+  IOS_DEVICECTL_COMMAND_FAILED: "IOS_DEVICECTL_COMMAND_FAILED",
   AX_QUERY_TIMEOUT: "AX_QUERY_TIMEOUT",
   AX_DAEMON_READY_TIMEOUT: "AX_DAEMON_READY_TIMEOUT",
   AX_DAEMON_EXITED_BEFORE_READY: "AX_DAEMON_EXITED_BEFORE_READY",
@@ -16644,6 +16656,7 @@ var FAILURE_CODES = {
   KEYBOARD_KEY_UNSUPPORTED: "KEYBOARD_KEY_UNSUPPORTED",
   KEYBOARD_CHARACTER_UNSUPPORTED: "KEYBOARD_CHARACTER_UNSUPPORTED",
   KEYBOARD_TEXT_AND_KEY_COMBINED: "KEYBOARD_TEXT_AND_KEY_COMBINED",
+  KEYBOARD_INPUT_NOT_FOCUSED: "KEYBOARD_INPUT_NOT_FOCUSED",
   SECRET_PLACEHOLDER_UNKNOWN: "SECRET_PLACEHOLDER_UNKNOWN",
   SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
   BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
@@ -16688,7 +16701,9 @@ var FAILURE_COMMANDS = [
   "electron",
   "npm",
   "npx",
-  "unknown"
+  "unknown",
+  "devicectl",
+  "xcodebuild"
 ];
 var FAILURE_SIGNAL_NAMES = [
   "SIGABRT",