@limrun/ui 0.9.0-rc.5 → 0.9.0-rc.7

package/src/core/device-install/operations/limbuild-client.ts

@@ -0,0 +1,104 @@
+import type { BuildLogLine, DeviceInstallBuildStatus } from '../types';
+
+export type LimbuildInfo = {
+  homeDir?: string;
+  lastBuildConfig?: {
+    bundleId?: string;
+    sdk?: string;
+  };
+};
+
+export type StartSignedDeviceBuildOptions = {
+  limbuildApiUrl: string;
+  token?: string;
+  certificateP12Base64: string;
+  certificatePassword: string;
+  provisioningProfileBase64: string;
+};
+
+export type BuildLogEventsOptions = {
+  limbuildApiUrl: string;
+  execId: string;
+  token?: string;
+  onLine: (line: BuildLogLine) => void;
+  onStatus: (status: DeviceInstallBuildStatus) => void;
+  onError?: (error: Error) => void;
+};
+
+export async function fetchLimbuildInfo(limbuildApiUrl: string, token?: string) {
+  const url = new URL(`${limbuildApiUrl}/info`);
+  if (token) {
+    url.searchParams.set('token', token);
+  }
+  const response = await fetch(url.toString(), {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Info request failed: HTTP ${response.status} ${body}`);
+  }
+  return (await response.json()) as LimbuildInfo;
+}
+
+export async function startSignedDeviceBuild({
+  limbuildApiUrl,
+  token,
+  certificateP12Base64,
+  certificatePassword,
+  provisioningProfileBase64,
+}: StartSignedDeviceBuildOptions) {
+  const url = new URL(`${limbuildApiUrl}/exec`);
+  if (token) {
+    url.searchParams.set('token', token);
+  }
+  const response = await fetch(url.toString(), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify({
+      command: 'xcodebuild',
+      xcodebuild: { sdk: 'iphoneos' },
+      signing: {
+        certificateP12Base64,
+        certificatePassword,
+        provisioningProfileBase64,
+      },
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Build request failed: HTTP ${response.status} ${body}`);
+  }
+  return (await response.json()) as { execId?: string };
+}
+
+export function watchBuildLogEvents({
+  limbuildApiUrl,
+  execId,
+  token,
+  onLine,
+  onStatus,
+  onError,
+}: BuildLogEventsOptions) {
+  const url = new URL(`${limbuildApiUrl}/exec/${execId}/events`);
+  if (token) {
+    url.searchParams.set('token', token);
+  }
+  const events = new EventSource(url.toString());
+  onStatus('running');
+  events.addEventListener('command', (event) => onLine({ type: 'command', data: event.data }));
+  events.addEventListener('stdout', (event) => onLine({ type: 'stdout', data: event.data }));
+  events.addEventListener('stderr', (event) => onLine({ type: 'stderr', data: event.data }));
+  events.addEventListener('exitCode', (event) => {
+    const code = parseInt(event.data, 10);
+    onStatus(code === 0 ? 'succeeded' : code < 0 ? 'cancelled' : 'failed');
+    events.close();
+  });
+  events.onerror = () => {
+    events.close();
+    onError?.(new Error('Build log stream closed before completion.'));
+  };
+  return () => events.close();
+}

package/src/core/device-install/operations/operations.ts

@@ -0,0 +1,217 @@
+/// <reference path="./webusb-dom.d.ts" />
+
+import type { DeviceHello, DeviceInstallLog, PairRecordPayload } from '../types';
+import { RelayClient } from './relay-client';
+import { closeUsbmuxSession, createUsbmuxSession, type UsbmuxSession } from './usbmux';
+import { claimUsbmux, findUsbmuxCandidates, requestAppleDevice, type UsbmuxCandidate } from './webusb';
+
+export type DeviceRelayTarget = {
+  device: USBDevice;
+  candidate: UsbmuxCandidate;
+  session?: UsbmuxSession;
+  claimedInterfaceNumber?: number;
+  hello: DeviceHello;
+};
+
+export type RequestUSBAccessOptions = {
+  log: DeviceInstallLog;
+};
+
+export type StartPairingRelayOptions = {
+  limbuildApiUrl: string;
+  token?: string;
+  log: DeviceInstallLog;
+  target: DeviceRelayTarget;
+};
+
+export type StartInstallRelayOptions = StartPairingRelayOptions & {
+  pairRecord: PairRecordPayload;
+};
+
+export async function requestUSBAccess({ log }: RequestUSBAccessOptions) {
+  log('Selecting USB device');
+  const device = await requestAppleDevice();
+  const target = makeDeviceRelayTarget(device);
+  log(
+    'Selected USB device',
+    `${device.manufacturerName ?? ''} ${device.productName ?? ''} ${device.serialNumber ?? ''}`.trim(),
+  );
+  return target;
+}
+
+export async function startPairingRelay({ limbuildApiUrl, token, log, target }: StartPairingRelayOptions) {
+  const deviceRelayUrl = deviceRelayWebSocketUrl(limbuildApiUrl, token);
+  let relay: RelayClient | undefined;
+  try {
+    relay = await connectRelay(deviceRelayUrl, target, log);
+    const pairRecord = await relay.startPairing();
+    return { relay, pairRecord, target };
+  } catch (error) {
+    relay?.close();
+    throw error;
+  }
+}
+
+export async function startInstallRelay({
+  limbuildApiUrl,
+  token,
+  log,
+  target,
+  pairRecord,
+}: StartInstallRelayOptions) {
+  const deviceRelayUrl = deviceRelayWebSocketUrl(limbuildApiUrl, token);
+  let relay: RelayClient | undefined;
+  try {
+    relay = await connectRelay(deviceRelayUrl, target, log);
+    await relay.startInstall(pairRecord);
+    return relay;
+  } catch (error) {
+    relay?.close();
+    throw error;
+  }
+}
+
+export async function closeDeviceRelayTarget(target: DeviceRelayTarget | undefined, log?: DeviceInstallLog) {
+  if (!target) return;
+  if (target.session) {
+    closeUsbmuxSession(target.session);
+    target.session = undefined;
+  }
+  if (target.claimedInterfaceNumber !== undefined) {
+    try {
+      await target.device.releaseInterface(target.claimedInterfaceNumber);
+      log?.('Released usbmux interface');
+    } catch (error) {
+      log?.('USB interface release failed', errorMessage(error));
+    } finally {
+      target.claimedInterfaceNumber = undefined;
+    }
+  }
+  if (target.device.opened) {
+    try {
+      await target.device.close();
+      log?.('Closed USB device');
+    } catch (error) {
+      log?.('USB device close failed', errorMessage(error));
+    }
+  }
+}
+
+async function connectRelay(deviceRelayUrl: string, target: DeviceRelayTarget, log: DeviceInstallLog) {
+  await ensureUsbmuxSession(target, log);
+  const relay = new RelayClient(deviceRelayUrl, target.session!, target.hello, log);
+  await relay.connect();
+  return relay;
+}
+
+async function ensureUsbmuxSession(target: DeviceRelayTarget, log: DeviceInstallLog) {
+  if (target.session) return;
+  try {
+    target.candidate = await claimBestUsbmuxCandidate(target, log);
+    target.session = await createUsbmuxSession(target.device, target.candidate);
+    log('Created usbmux session');
+  } catch (error) {
+    await closeDeviceRelayTarget(target, log);
+    throw error;
+  }
+}
+
+function makeDeviceRelayTarget(device: USBDevice): DeviceRelayTarget {
+  return {
+    device,
+    candidate: pickUsbmuxCandidate(device),
+    hello: {
+      serialNumber: device.serialNumber,
+      productName: device.productName,
+      manufacturerName: device.manufacturerName,
+      productId: device.productId,
+      vendorId: device.vendorId,
+    },
+  };
+}
+
+async function claimBestUsbmuxCandidate(target: DeviceRelayTarget, log: DeviceInstallLog) {
+  const candidates = orderedUsbmuxCandidates(target.device);
+  if (candidates.length === 0) throw new Error('No Apple usbmux interface found.');
+  let lastError: unknown;
+  for (const candidate of candidates) {
+    for (const attempt of [1, 2]) {
+      try {
+        if (!target.device.opened) {
+          await target.device.open();
+        }
+        log(
+          'Claiming usbmux interface',
+          `configuration ${candidate.configurationValue}, interface ${candidate.interfaceNumber}, alternate ${candidate.alternateSetting}, attempt ${attempt}`,
+        );
+        await claimUsbmux(target.device, candidate);
+        target.claimedInterfaceNumber = candidate.interfaceNumber;
+        log(
+          'Claimed usbmux interface',
+          `configuration ${candidate.configurationValue}, interface ${candidate.interfaceNumber}`,
+        );
+        return candidate;
+      } catch (error) {
+        lastError = error;
+        log(
+          'USB interface claim failed',
+          `configuration ${candidate.configurationValue}, interface ${candidate.interfaceNumber}: ${errorMessage(error)}`,
+        );
+        await resetUSBDevice(target);
+        await sleep(250);
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error('Unable to claim any Apple usbmux interface.');
+}
+
+function pickUsbmuxCandidate(device: USBDevice) {
+  const candidate = orderedUsbmuxCandidates(device)[0];
+  if (!candidate) throw new Error('No Apple usbmux interface found.');
+  return candidate;
+}
+
+function orderedUsbmuxCandidates(device: USBDevice) {
+  const candidates = findUsbmuxCandidates(device);
+  const activeConfigurationValue = device.configuration?.configurationValue;
+  return [
+    ...candidates.filter((item) => item.configurationValue === activeConfigurationValue),
+    ...candidates.filter((item) => item.configurationValue !== activeConfigurationValue),
+  ];
+}
+
+export function deviceRelayWebSocketUrl(limbuildApiUrl: string, token?: string) {
+  const url = new URL(limbuildApiUrl);
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  url.pathname = `${url.pathname.replace(/\/$/, '')}/device/ws`;
+  if (token) {
+    url.searchParams.set('token', token);
+  }
+  return url.toString();
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function resetUSBDevice(target: DeviceRelayTarget) {
+  if (target.claimedInterfaceNumber !== undefined) {
+    try {
+      await target.device.releaseInterface(target.claimedInterfaceNumber);
+    } catch {
+      // Best effort: claim failures often mean there is nothing we own to release.
+    }
+    target.claimedInterfaceNumber = undefined;
+  }
+  if (target.device.opened) {
+    try {
+      await target.device.close();
+    } catch {
+      // Best effort before reopening for the next candidate/attempt.
+    }
+  }
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/core/device-install/operations/relay-client.ts

@@ -0,0 +1,255 @@
+import type { DeviceHello, DeviceInstallLog, PairRecordPayload } from '../types';
+import { decodeFrame, decodeJson, encodeFrame, encodeJson, RelayMessageType } from './relay-protocol';
+import {
+  openStream,
+  receiveStreamData,
+  sendStreamData,
+  type UsbmuxSession,
+  type UsbmuxStream,
+} from './usbmux';
+
+type OpenStreamPayload = {
+  port: number;
+};
+
+type ProgressPayload = {
+  message: string;
+};
+
+export class RelayClient {
+  private socket?: WebSocket;
+  private streams = new Map<number, UsbmuxStream>();
+  private frameQueue = Promise.resolve();
+  private closed = false;
+  private pairRecordWaiter?: {
+    resolve: (record: PairRecordPayload) => void;
+    reject: (error: Error) => void;
+  };
+
+  constructor(
+    private readonly webSocketUrl: string,
+    private readonly session: UsbmuxSession,
+    private readonly deviceHello: DeviceHello,
+    private readonly log: DeviceInstallLog,
+  ) {}
+
+  async connect() {
+    const socket = new WebSocket(this.webSocketUrl);
+    socket.binaryType = 'arraybuffer';
+    this.socket = socket;
+    socket.onclose = () => {
+      this.closed = true;
+      this.log('Relay socket closed');
+      if (this.pairRecordWaiter) {
+        this.pairRecordWaiter.reject(new Error('Relay socket closed'));
+        this.pairRecordWaiter = undefined;
+      }
+    };
+    await new Promise<void>((resolve, reject) => {
+      socket.onopen = () => resolve();
+      socket.onerror = () => reject(new Error('WebSocket connection failed'));
+    });
+    socket.onmessage = (event) => {
+      const data = event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : new Uint8Array();
+      this.enqueueFrame(data);
+    };
+    await this.send({
+      type: RelayMessageType.DeviceHello,
+      requestId: 0,
+      streamId: 0,
+      payload: encodeJson(this.deviceHello),
+    });
+    this.log('Connected WebSocket relay');
+  }
+
+  async startPairing() {
+    const recordPromise = new Promise<PairRecordPayload>((resolve, reject) => {
+      this.pairRecordWaiter = { resolve, reject };
+    });
+    await this.send({
+      type: RelayMessageType.StartPairing,
+      requestId: 0,
+      streamId: 0,
+      payload: encodeJson({}),
+    });
+    this.log('Pairing requested');
+    return recordPromise;
+  }
+
+  async startInstall(pairRecord: PairRecordPayload) {
+    await this.send({
+      type: RelayMessageType.StartInstall,
+      requestId: 0,
+      streamId: 0,
+      payload: encodeJson(pairRecord),
+    });
+    this.log('Installation requested');
+  }
+
+  close() {
+    this.closed = true;
+    this.socket?.close();
+  }
+
+  private enqueueFrame(data: Uint8Array) {
+    this.frameQueue = this.frameQueue.then(() => this.handleFrame(decodeFrame(data))).catch((error) => {
+      this.log('Relay frame handling failed', error instanceof Error ? error.message : String(error));
+    });
+  }
+
+  private async handleFrame(frame: ReturnType<typeof decodeFrame>) {
+    switch (frame.type) {
+      case RelayMessageType.OpenStream:
+        await this.handleOpenStream(
+          frame.requestId,
+          frame.streamId,
+          decodeJson<OpenStreamPayload>(frame.payload).port,
+        );
+        break;
+      case RelayMessageType.StreamData: {
+        const stream = this.streams.get(frame.streamId);
+        if (!stream) throw new Error(`Unknown stream ${frame.streamId}`);
+        await sendStreamData(stream, frame.payload);
+        break;
+      }
+      case RelayMessageType.StreamClose:
+        this.streams.delete(frame.streamId);
+        break;
+      case RelayMessageType.InstallProgress:
+        this.log(formatInstallProgress(decodeJson<ProgressPayload>(frame.payload).message));
+        break;
+      case RelayMessageType.Error:
+        this.handleError(frame.payload);
+        break;
+      case RelayMessageType.PairRecordReady:
+        this.handlePairRecordReady(decodeJson<PairRecordPayload>(frame.payload));
+        break;
+      case RelayMessageType.Ping:
+        await this.send({
+          type: RelayMessageType.Pong,
+          requestId: frame.requestId,
+          streamId: 0,
+          payload: new Uint8Array(),
+        });
+        break;
+    }
+  }
+
+  private handleError(payload: Uint8Array) {
+    const message = decodeServerError(payload);
+    this.log('Server error', message);
+    if (this.pairRecordWaiter) {
+      this.pairRecordWaiter.reject(new Error(message));
+      this.pairRecordWaiter = undefined;
+    }
+  }
+
+  private handlePairRecordReady(record: PairRecordPayload) {
+    this.log('Pair record received', record.udid);
+    this.pairRecordWaiter?.resolve(record);
+    this.pairRecordWaiter = undefined;
+  }
+
+  private async handleOpenStream(requestId: number, streamId: number, port: number) {
+    try {
+      const stream = await openStream(this.session, port);
+      this.streams.set(streamId, stream);
+      await this.send({
+        type: RelayMessageType.OpenResult,
+        requestId,
+        streamId,
+        payload: encodeJson({ ok: true }),
+      });
+      this.log(`Opened device stream ${streamId} to port ${port}`);
+      void this.pumpDeviceToServer(streamId, stream);
+    } catch (error) {
+      this.log(`Open device stream ${streamId} failed`, error instanceof Error ? error.message : String(error));
+      await this.send({
+        type: RelayMessageType.OpenResult,
+        requestId,
+        streamId,
+        payload: encodeJson({
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      });
+    }
+  }
+
+  private async pumpDeviceToServer(streamId: number, stream: UsbmuxStream) {
+    try {
+      for (;;) {
+        const data = await receiveStreamData(stream);
+        if (this.closed) return;
+        await this.send({
+          type: RelayMessageType.StreamData,
+          requestId: 0,
+          streamId,
+          payload: data,
+        });
+      }
+    } catch (error) {
+      this.log(`Device stream ${streamId} closed`, error instanceof Error ? error.message : String(error));
+      await this.send({
+        type: RelayMessageType.StreamClose,
+        requestId: 0,
+        streamId,
+        payload: encodeJson({
+          reason: error instanceof Error ? error.message : String(error),
+        }),
+      });
+    }
+  }
+
+  private async send(frame: Parameters<typeof encodeFrame>[0]) {
+    if (this.closed) return;
+    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      this.closed = true;
+      return;
+    }
+    this.socket.send(encodeFrame(frame));
+  }
+}
+
+function decodeServerError(payload: Uint8Array) {
+  const text = new TextDecoder().decode(payload);
+  try {
+    const parsed = JSON.parse(text) as { error?: string };
+    return userFacingServerError(parsed.error ?? text);
+  } catch {
+    return userFacingServerError(text);
+  }
+}
+
+function userFacingServerError(message: string) {
+  return message.replace(/libimobiledevice/g, '').trim();
+}
+
+function formatInstallProgress(message: string) {
+  const prefix = 'install status: ';
+  if (!message.startsWith(prefix)) {
+    return message;
+  }
+  const xml = message.slice(prefix.length);
+  const doc = new DOMParser().parseFromString(xml, 'application/xml');
+  const dict = doc.querySelector('plist > dict');
+  if (!dict) {
+    return message;
+  }
+  const values = readPlistDict(dict);
+  const status = values.Status ?? 'Unknown';
+  const percent = values.PercentComplete ? `${values.PercentComplete}% ` : '';
+  return `Install progress: ${percent}${status}`;
+}
+
+function readPlistDict(dict: Element) {
+  const result: Record<string, string> = {};
+  const children = Array.from(dict.children);
+  for (let index = 0; index < children.length; index += 2) {
+    const key = children[index];
+    const value = children[index + 1];
+    if (!key || key.tagName !== 'key' || !value) continue;
+    result[key.textContent ?? ''] = value.textContent ?? '';
+  }
+  return result;
+}

package/src/core/device-install/operations/relay-protocol.ts

@@ -0,0 +1,71 @@
+export const RELAY_PROTOCOL_VERSION = 1;
+export const RELAY_HEADER_BYTES = 16;
+
+export const RelayMessageType = {
+  DeviceHello: 1,
+  OpenStream: 2,
+  OpenResult: 3,
+  StreamData: 4,
+  StreamClose: 5,
+  InstallProgress: 6,
+  Error: 7,
+  Ping: 8,
+  Pong: 9,
+  StartPairing: 10,
+  StartInstall: 11,
+  PairRecordReady: 12,
+} as const;
+
+export type RelayMessageType = (typeof RelayMessageType)[keyof typeof RelayMessageType];
+
+export type RelayFrame = {
+  type: RelayMessageType;
+  requestId: number;
+  streamId: number;
+  payload: Uint8Array;
+};
+
+export function encodeFrame(frame: RelayFrame) {
+  const result = new Uint8Array(RELAY_HEADER_BYTES + frame.payload.byteLength);
+  const view = new DataView(result.buffer);
+  view.setUint8(0, RELAY_PROTOCOL_VERSION);
+  view.setUint8(1, frame.type);
+  view.setUint8(2, 0);
+  view.setUint8(3, 0);
+  view.setUint32(4, frame.requestId);
+  view.setUint32(8, frame.streamId);
+  view.setUint32(12, frame.payload.byteLength);
+  result.set(frame.payload, RELAY_HEADER_BYTES);
+  return result;
+}
+
+export function decodeFrame(data: Uint8Array): RelayFrame {
+  if (data.byteLength < RELAY_HEADER_BYTES) {
+    throw new Error(`Relay frame too short: ${data.byteLength}`);
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const version = view.getUint8(0);
+  if (version !== RELAY_PROTOCOL_VERSION) {
+    throw new Error(`Unsupported relay protocol version ${version}`);
+  }
+  const payloadLength = view.getUint32(12);
+  if (data.byteLength !== RELAY_HEADER_BYTES + payloadLength) {
+    throw new Error(
+      `Relay frame length mismatch: got ${data.byteLength}, expected ${RELAY_HEADER_BYTES + payloadLength}`,
+    );
+  }
+  return {
+    type: view.getUint8(1) as RelayMessageType,
+    requestId: view.getUint32(4),
+    streamId: view.getUint32(8),
+    payload: data.slice(RELAY_HEADER_BYTES),
+  };
+}
+
+export function encodeJson(value: unknown) {
+  return new TextEncoder().encode(JSON.stringify(value));
+}
+
+export function decodeJson<T>(payload: Uint8Array): T {
+  return JSON.parse(new TextDecoder().decode(payload)) as T;
+}