@stim-cli/server 1.10.1 → 1.12.0

package/dist/protocol.d.mts

@@ -1,16 +1,17 @@
-import { NdjsonRecord, StatusPayload } from "@stim-cli/core/state";
+import { BuildPlanPayload, NdjsonRecord, StatusPayload } from "@stim-cli/core/state";
 //#region src/protocol.d.ts
 declare const PROTOCOL_VERSION = 1;
 declare const PROTOCOL_SCHEMA_FILE = "protocol.schema.json";
-declare const CAPABILITIES: readonly ["read"];
+/** `read` serves state. `control` also runs {@link ACTIONS}; only the Mac grants it. */
+declare const CAPABILITIES: readonly ["read", "control"];
 type Capability = (typeof CAPABILITIES)[number];
-declare const METHODS: readonly ["hello", "status.subscribe", "logs.query", "logs.subscribe", "stats.get", "settings.get", "frames.subscribe", "unsubscribe"];
+declare const METHODS: readonly ["hello", "status.subscribe", "logs.query", "logs.subscribe", "stats.get", "settings.get", "frames.subscribe", "frames.keyframe", "build.plan", "machine.get", "machine.history", "unsubscribe", "action", "control.begin", "control.end", "input.touch", "input.text", "input.button", "input.rotate", "input.posture"];
 type Method = (typeof METHODS)[number];
 /**
  * `unauthorized`, `pairing-expired` and `protocol-unsupported` refuse the client until it pairs again or
  * updates; clients retry the others.
  */
-declare const ERROR_CODES: readonly ["unauthorized", "pairing-expired", "protocol-unsupported", "identity-unavailable", "bad-request", "unknown-method", "already-authenticated", "unknown-subscription", "unknown-workspace", "limit-exceeded", "slow-client", "status-failed", "logs-failed", "stim-failed", "frames-failed"];
+declare const ERROR_CODES: readonly ["unauthorized", "pairing-expired", "protocol-unsupported", "identity-unavailable", "bad-request", "unknown-method", "already-authenticated", "unknown-subscription", "unknown-workspace", "limit-exceeded", "slow-client", "status-failed", "logs-failed", "stim-failed", "frames-failed", "forbidden", "unknown-action", "action-busy", "action-failed", "device-busy", "unknown-session"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 type RequestId = number | string;
 /** Spends a single-use pairing token; the result carries the new device token. */
@@ -32,13 +33,19 @@ interface HelloParams {
 }
 interface HelloResult {
   protocol: number;
-  /** The Mac's name, this package's version, and the version of the `stim` it runs. */
+  /**
+   * The Mac's name, this package's version, the version of the `stim` it runs, and the home directory of the
+   * user it runs as, so clients can show paths under it as `~/...`.
+   */
   server: {
     name: string;
     version: string;
     stim: string;
+    home: string;
   };
   capabilities: Capability[];
+  /** The actions this device may run: every one of {@link ACTIONS} with `control`, none without. */
+  actions: ActionName[];
   /** The paired device this connection authenticated as, as `stim-server devices` lists it. */
   device: {
     id: string;
@@ -53,7 +60,7 @@ interface SubscribeResult {
 interface UnsubscribeParams {
   subscription: string;
 }
-declare const LOG_SOURCES: readonly ["metro", "client", "device", "build"];
+declare const LOG_SOURCES: readonly ["metro", "client", "device", "build", "agent"];
 type LogSource = (typeof LOG_SOURCES)[number];
 declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error", "fatal"];
 type LogLevel = (typeof LOG_LEVELS)[number];
@@ -86,14 +93,217 @@ type StatsResult = Record<string, unknown>;
 /** `stim settings --json`; the CLI masks sensitive values. */
 type SettingsResult = Record<string, unknown>;
 type Platform = "ios" | "android";
+declare const FRAME_FPS: {
+  readonly default: 5;
+  readonly max: 30;
+  readonly video: 60;
+};
+declare const FRAME_EDGE: {
+  readonly min: 240;
+  readonly default: 1280;
+  readonly max: 2048;
+};
 /**
  * A device `stim status` lists as owned by `workspace`, in `slot` (`default` when absent). Frames come only
- * from a booted simulator or a running emulator Stim created.
+ * from a booted simulator or a running emulator Stim created. `fps` caps how many frames a second this
+ * subscription gets, and `maxEdge` asks for frames scaled to fit that many pixels; the server may send smaller
+ * frames, and larger ones while another subscriber of the same device asks for more.
  */
 interface FrameTarget {
   workspace: string;
   platform: Platform;
   slot?: string;
+  fps?: number;
+  maxEdge?: number;
+  /** The codecs this client decodes. The server picks one when it can encode video; see {@link FramesSubscribeResult}. */
+  video?: VideoCodec[];
+}
+declare const VIDEO_CODECS: readonly ["h264"];
+type VideoCodec = (typeof VIDEO_CODECS)[number];
+/**
+ * With `video`, frames arrive as binary WebSocket messages, one H.264 access unit each; see {@link VideoPacket}.
+ * A subscription whose device cannot be encoded, such as an iPhone Duo, still sends JSON `frame` events.
+ */
+interface FramesSubscribeResult extends SubscribeResult {
+  video?: VideoCodec;
+}
+/** Asks for a keyframe on a video subscription, after the client lost its decoder state. */
+interface KeyframeParams {
+  subscription: string;
+}
+declare const VIDEO_HEADER_VERSION = 1;
+/** The keyframe bit of a {@link VideoPacket}'s flags. */
+declare const VIDEO_KEYFRAME = 1;
+/**
+ * The layout of a binary video message, big-endian: u8 version ({@link VIDEO_HEADER_VERSION}), u8 flags
+ * ({@link VIDEO_KEYFRAME}), u16 header length, u32 sequence number of the messages sent on this subscription, f64 capture time in milliseconds since the
+ * epoch on the Mac's clock, u16 width, u16 height, u8 subscription id length N, N bytes of ASCII subscription
+ * id. After the header comes one Annex-B H.264 access unit; a keyframe carries its SPS and PPS. The stream has
+ * no B-frames, so each access unit is shown as it arrives.
+ */
+interface VideoPacket {
+  subscription: string;
+  keyframe: boolean;
+  sequence: number;
+  capturedAt: number;
+  width: number;
+  height: number;
+  accessUnit: Uint8Array;
+}
+/** Each action runs one fixed `stim` command in the workspace. */
+declare const ACTIONS: readonly ["reload", "stop"];
+type ActionName = (typeof ACTIONS)[number];
+/**
+ * `reload` runs `stim reload --json`, with `platform` when both platforms are live; `stop` runs
+ * `stim stop --json`. `workspace` is an environment `path` from a status payload. Needs `control`.
+ */
+type ActionParams = {
+  action: "reload";
+  workspace: string;
+  platform?: Platform;
+} | {
+  action: "stop";
+  workspace: string;
+};
+/** `output` is the JSON the command printed. */
+interface ActionResult {
+  action: ActionName;
+  workspace: string;
+  output: Record<string, unknown>;
+}
+/**
+ * Starts a control session on the device `stim status` lists as owned by `workspace` in `slot`. Needs
+ * `control`. Refused with `device-busy` while an agent, a device lock or another client drives the device,
+ * unless `takeOver` is true.
+ */
+interface ControlBeginParams {
+  workspace: string;
+  platform: Platform;
+  slot?: string;
+  takeOver?: boolean;
+}
+/**
+ * `lease` is the `stim device lock` lease the server holds for the session, or null when it holds none, such
+ * as after taking over a device another workspace leases. `postures` lists what `input.posture` accepts for
+ * the device: `folded` and `unfolded` for an iPhone Duo, all three for an emulator with a hinge, and none
+ * otherwise.
+ */
+interface ControlBeginResult {
+  session: string;
+  platform: Platform;
+  lease: {
+    grantedAt: string | null;
+    expiresAt: string;
+  } | null;
+  postures: DevicePosture[];
+}
+interface ControlEndParams {
+  session: string;
+}
+declare const TOUCH_PHASES: readonly ["down", "move", "up"];
+type TouchPhase = (typeof TOUCH_PHASES)[number];
+/** `x` and `y` are fractions of the upright screen, origin top-left. `display` is 0 for the main display. */
+interface InputTouchParams {
+  session: string;
+  phase: TouchPhase;
+  x: number;
+  y: number;
+  display?: number;
+}
+declare const MAX_INPUT_TEXT = 256;
+/** Printable ASCII, where `\n` presses Return, `\t` Tab and `\b` Delete. */
+interface InputTextParams {
+  session: string;
+  text: string;
+}
+/** `home` and `lock` on both platforms; `back` and `app-switch` on Android only. */
+declare const INPUT_BUTTONS: readonly ["home", "lock", "back", "app-switch"];
+type InputButton = (typeof INPUT_BUTTONS)[number];
+interface InputButtonParams {
+  session: string;
+  button: InputButton;
+}
+/** `left` turns the device a quarter turn counterclockwise, `right` clockwise. */
+declare const ROTATE_DIRECTIONS: readonly ["left", "right"];
+type RotateDirection = (typeof ROTATE_DIRECTIONS)[number];
+interface InputRotateParams {
+  session: string;
+  direction: RotateDirection;
+}
+declare const DEVICE_POSTURES: readonly ["folded", "half-open", "unfolded"];
+type DevicePosture = (typeof DEVICE_POSTURES)[number];
+/** Moves the hinge of a device whose `control.begin` result lists `posture`. */
+interface InputPostureParams {
+  session: string;
+  posture: DevicePosture;
+}
+/** Predicts the next `ios` or `android` build of `workspace` in `slot` (`default` when absent). */
+interface BuildPlanParams {
+  workspace: string;
+  platform: Platform;
+  slot?: string;
+}
+/** `stim ios|android --plan --json`. It builds, boots and installs nothing, and writes no Stim state. */
+type BuildPlanResult = BuildPlanPayload;
+type MemoryPressure = "normal" | "warning" | "critical";
+/** A volume that holds Stim workspaces, Stim home, or the simulators. */
+interface MachineVolume {
+  /** `/`, or `/Volumes/<name>` for an external volume. */
+  mount: string;
+  /** What Stim keeps there: `Workspaces`, `Stim home`, `Simulators`. */
+  holds: string[];
+  /** Free space without purgeable space, which is what Stim's disk budget measures. */
+  freeBytes: number;
+  totalBytes: number;
+}
+/** Cheap machine usage, read in the server process without running `stim`. */
+interface MachineUsage {
+  volumes: MachineVolume[];
+  /**
+   * `usedBytes` is the Mac's memory in use, as Activity Monitor's "Memory Used" counts it: app memory, wired and
+   * compressed. `pressure` is the macOS memory pressure level. Both are null on other systems or when they cannot
+   * be read.
+   */
+  memory: {
+    totalBytes: number;
+    usedBytes: number | null;
+    pressure: MemoryPressure | null;
+  };
+  load: {
+    avg1: number;
+    avg5: number;
+    avg15: number;
+    cpus: number;
+  };
+  /**
+   * `usage` is the Mac's overall CPU busy fraction (0..1), from the tick delta between this call and the
+   * previous one. Null on the first call of a server process, since there is no previous sample yet.
+   */
+  cpu: {
+    usage: number | null;
+    cores: number;
+  };
+  sampledAt: string;
+}
+/**
+ * One `machine.history` sample. `at` is epoch milliseconds. `cpu` is the busy fraction (0..1) since the previous
+ * sample. `memoryPressure` is 0 (normal), 1 (warning) or 2 (critical). `diskFreeBytes` is the free space of the
+ * startup volume, `/`. A field is null when it could not be read.
+ */
+interface UsageSample {
+  at: number;
+  cpu: number | null;
+  memoryUsedBytes: number | null;
+  memoryPressure: 0 | 1 | 2 | null;
+  diskFreeBytes: number | null;
+}
+/** Returns only the samples taken after `sinceMs`, epoch milliseconds. */
+interface MachineHistoryParams {
+  sinceMs?: number;
+}
+interface MachineHistory {
+  intervalMs: number;
+  samples: UsageSample[];
 }
 interface Methods {
   hello: {
@@ -122,12 +332,60 @@ interface Methods {
   };
   "frames.subscribe": {
     params: FrameTarget;
-    result: SubscribeResult;
+    result: FramesSubscribeResult;
+  };
+  "frames.keyframe": {
+    params: KeyframeParams;
+    result: Record<string, never>;
+  };
+  "build.plan": {
+    params: BuildPlanParams;
+    result: BuildPlanResult;
+  };
+  "machine.get": {
+    params?: Record<string, never>;
+    result: MachineUsage;
+  };
+  "machine.history": {
+    params?: MachineHistoryParams;
+    result: MachineHistory;
   };
   unsubscribe: {
     params: UnsubscribeParams;
     result: Record<string, never>;
   };
+  action: {
+    params: ActionParams;
+    result: ActionResult;
+  };
+  "control.begin": {
+    params: ControlBeginParams;
+    result: ControlBeginResult;
+  };
+  "control.end": {
+    params: ControlEndParams;
+    result: Record<string, never>;
+  };
+  "input.touch": {
+    params: InputTouchParams;
+    result: Record<string, never>;
+  };
+  "input.text": {
+    params: InputTextParams;
+    result: Record<string, never>;
+  };
+  "input.button": {
+    params: InputButtonParams;
+    result: Record<string, never>;
+  };
+  "input.rotate": {
+    params: InputRotateParams;
+    result: Record<string, never>;
+  };
+  "input.posture": {
+    params: InputPostureParams;
+    result: Record<string, never>;
+  };
 }
 type ClientRequest = { [M in Method]: {
   id: RequestId;
@@ -165,7 +423,7 @@ interface ErrorEvent {
   subscription: string;
   error: ProtocolError;
 }
-/** A screenshot of the device, sent when the screen changed, at most 5 times a second. */
+/** A frame of the device's screen, sent when the screen changed, at most `fps` times a second. */
 interface FrameEvent {
   event: "frame";
   subscription: string;
@@ -177,6 +435,12 @@ interface FrameEvent {
   capturedAt: string;
   /** Base64-encoded image bytes. */
   data: string;
+  /**
+   * An iPhone Duo's or Android foldable emulator's posture. A Duo reports the panel it lit: the cover when
+   * folded, the inner panel when unfolded. An emulator with a hinge reports `folded` while it shows only its
+   * outer display, and `unfolded` otherwise, including half open.
+   */
+  posture?: "folded" | "unfolded";
 }
 /**
  * Captures for a `frames.subscribe` subscription are slow or a timed-out capture is being retried; the
@@ -187,10 +451,21 @@ interface FrameDelayedEvent {
   subscription: string;
   delayed: boolean;
 }
-type ServerEvent = StatusEvent | LogsEvent | FrameEvent | FrameDelayedEvent | ErrorEvent;
+declare const CONTROL_END_REASONS: readonly ["idle", "taken-over", "device-gone", "forbidden", "failed"];
+/**
+ * The server ended a control session: no input for 5 minutes, another client took the device over, the device
+ * stopped or changed owner, the device lost `control`, or input could not reach the device.
+ */
+interface ControlEndedEvent {
+  event: "control-ended";
+  session: string;
+  reason: (typeof CONTROL_END_REASONS)[number];
+  message: string;
+}
+type ServerEvent = StatusEvent | LogsEvent | FrameEvent | FrameDelayedEvent | ErrorEvent | ControlEndedEvent;
 type ServerMessage = ServerResponse | ServerEvent;
 type JsonSchema = Record<string, unknown>;
 /** The JSON Schema of every message on the wire, written to `dist/protocol.schema.json` at build time. */
 declare function protocolJsonSchema(): JsonSchema;
 //#endregion
-export { CAPABILITIES, Capability, ClientRequest, DeviceAuth, ERROR_CODES, ErrorCode, ErrorEvent, FrameDelayedEvent, FrameEvent, FrameTarget, HelloParams, HelloResult, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_LOG_TAIL, METHODS, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, RequestId, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, UnsubscribeParams, WorkspaceParams, protocolJsonSchema };
+export { ACTIONS, ActionName, ActionParams, ActionResult, BuildPlanParams, BuildPlanResult, CAPABILITIES, CONTROL_END_REASONS, Capability, ClientRequest, ControlBeginParams, ControlBeginResult, ControlEndParams, ControlEndedEvent, DEVICE_POSTURES, DeviceAuth, DevicePosture, ERROR_CODES, ErrorCode, ErrorEvent, FRAME_EDGE, FRAME_FPS, FrameDelayedEvent, FrameEvent, FrameTarget, FramesSubscribeResult, HelloParams, HelloResult, INPUT_BUTTONS, InputButton, InputButtonParams, InputPostureParams, InputRotateParams, InputTextParams, InputTouchParams, KeyframeParams, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, MachineHistory, MachineHistoryParams, MachineUsage, MachineVolume, MemoryPressure, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, ROTATE_DIRECTIONS, RequestId, RotateDirection, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, TOUCH_PHASES, TouchPhase, UnsubscribeParams, UsageSample, VIDEO_CODECS, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VideoCodec, VideoPacket, WorkspaceParams, protocolJsonSchema };

package/dist/protocol.mjs

@@ -1,2 +1,2 @@
-import { a as MAX_LOG_TAIL, c as PROTOCOL_VERSION, i as LOG_SOURCES, l as protocolJsonSchema, n as ERROR_CODES, o as METHODS, r as LOG_LEVELS, s as PROTOCOL_SCHEMA_FILE, t as CAPABILITIES } from "./protocol-B3k9Ykuu.mjs";
-export { CAPABILITIES, ERROR_CODES, LOG_LEVELS, LOG_SOURCES, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, protocolJsonSchema };
+import { _ as TOUCH_PHASES, a as ERROR_CODES, b as VIDEO_KEYFRAME, c as INPUT_BUTTONS, d as MAX_INPUT_TEXT, f as MAX_LOG_TAIL, g as ROTATE_DIRECTIONS, h as PROTOCOL_VERSION, i as DEVICE_POSTURES, l as LOG_LEVELS, m as PROTOCOL_SCHEMA_FILE, n as CAPABILITIES, o as FRAME_EDGE, p as METHODS, r as CONTROL_END_REASONS, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES, v as VIDEO_CODECS, x as protocolJsonSchema, y as VIDEO_HEADER_VERSION } from "./protocol-BElQc2vm.mjs";
+export { ACTIONS, CAPABILITIES, CONTROL_END_REASONS, DEVICE_POSTURES, ERROR_CODES, FRAME_EDGE, FRAME_FPS, INPUT_BUTTONS, LOG_LEVELS, LOG_SOURCES, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, protocolJsonSchema };