@stim-cli/server 1.14.0 → 1.16.0

package/dist/protocol.d.mts

@@ -1,501 +1,7 @@
-import { BuildPlanPayload, NdjsonRecord, StatusPayload } from "@stim-cli/core/state";
+export * from "@stim-cli/core/protocol";
 //#region src/protocol.d.ts
-declare const PROTOCOL_VERSION = 1;
-declare const PROTOCOL_SCHEMA_FILE = "protocol.schema.json";
-/** `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", "frames.keyframe", "build.plan", "machine.get", "machine.history", "unsubscribe", "action", "control.begin", "control.end", "input.touch", "input.text", "input.button", "input.rotate", "input.posture", "push.register", "push.unregister"];
-type Method = (typeof METHODS)[number];
-declare const PUSH_TOKEN_PATTERN = "^(Expo|Exponent)PushToken\\[[^\\]\\s]{1,256}\\]$";
-/**
- * `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", "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. */
-interface PairingAuth {
-  pairingToken: string;
-  deviceName: string;
-}
-/** Presents the device token a previous pairing returned. */
-interface DeviceAuth {
-  deviceToken: string;
-}
-interface HelloParams {
-  protocol: number;
-  client: {
-    name: string;
-    version: string;
-  };
-  auth: PairingAuth | DeviceAuth;
-}
-interface HelloResult {
-  protocol: number;
-  /**
-   * 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;
-    name: string;
-  };
-  /** Present only when the hello spent a pairing token. The server keeps only its hash. */
-  deviceToken?: string;
-}
-interface SubscribeResult {
-  subscription: string;
-}
-interface UnsubscribeParams {
-  subscription: string;
-}
-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];
-declare const MAX_LOG_TAIL = 5e3;
-/**
- * The Stim Desktop log viewer's filters, passed to `stim logs`. `workspace` is an environment `path` from a
- * status payload. Without `sources`, `errors` keeps the CLI's default error scope. `tail` defaults to
- * {@link MAX_LOG_TAIL}, which is also its maximum.
- */
-interface LogFilter {
-  workspace: string;
-  sources?: LogSource[];
-  level?: LogLevel;
-  slot?: string;
-  grep?: string;
-  errors?: boolean;
-  tail?: number;
-}
-/** One record as `stim logs --json` prints it. */
-type LogRecord = NdjsonRecord;
-interface LogsQueryResult {
-  records: LogRecord[];
-}
-/** Without `workspace`, stats and settings cover the machine only. */
-interface WorkspaceParams {
-  workspace?: string;
-}
-/** `stim stats --json`. */
-type StatsResult = Record<string, unknown>;
-/** `stim settings --json`; the CLI masks sensitive values. */
-type SettingsResult = Record<string, unknown>;
-type Platform = "ios" | "android";
-/** `reload` also reaches the workspace's Stim-owned Chrome page. */
-declare const RELOAD_PLATFORMS: readonly ["ios", "android", "web"];
-type ReloadPlatform = (typeof RELOAD_PLATFORMS)[number];
-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. `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 falls back to screenshots 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 flag bits of a {@link VideoPacket} that carry an iPhone Duo's posture, as `posture` on a `frame` event. */
-declare const VIDEO_FOLDED = 2;
-declare const VIDEO_UNFOLDED = 4;
-/**
- * The layout of a binary video message, big-endian: u8 version ({@link VIDEO_HEADER_VERSION}), u8 flags
- * ({@link VIDEO_KEYFRAME}, and on an iPhone Duo {@link VIDEO_FOLDED} or {@link VIDEO_UNFOLDED}), 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;
-  posture?: "folded" | "unfolded";
-  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 more than one platform is live; `stop` runs
- * `stim stop --json`. `workspace` is an environment `path` from a status payload. Needs `control`.
- */
-type ActionParams = {
-  action: "reload";
-  workspace: string;
-  platform?: ReloadPlatform;
-} | {
-  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[];
-}
-/** The attention events stim-server can push, named like the phone's notification settings. */
-declare const PUSH_EVENTS: readonly ["build-failed", "log-errors", "disk", "app-stopped", "slow-build"];
-type PushEvent = (typeof PUSH_EVENTS)[number];
-/**
- * Asks the server to push this device's attention notifications through the Expo push service to `token`, an
- * Expo push token, for at least one event. Registering again replaces the previous registration. `ref` is echoed as `data.ref` in every
- * push, so the phone can tell which Mac sent it.
- */
-interface PushRegisterParams {
-  token: string;
-  events: PushEvent[];
-  agentOnly?: boolean;
-  ref: string;
-}
-interface Methods {
-  hello: {
-    params: HelloParams;
-    result: HelloResult;
-  };
-  "status.subscribe": {
-    params?: Record<string, never>;
-    result: SubscribeResult;
-  };
-  "logs.query": {
-    params: LogFilter;
-    result: LogsQueryResult;
-  };
-  "logs.subscribe": {
-    params: LogFilter;
-    result: SubscribeResult;
-  };
-  "stats.get": {
-    params?: WorkspaceParams;
-    result: StatsResult;
-  };
-  "settings.get": {
-    params?: WorkspaceParams;
-    result: SettingsResult;
-  };
-  "frames.subscribe": {
-    params: FrameTarget;
-    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>;
-  };
-  "push.register": {
-    params: PushRegisterParams;
-    result: Record<string, never>;
-  };
-  "push.unregister": {
-    params?: Record<string, never>;
-    result: Record<string, never>;
-  };
-}
-type ClientRequest = { [M in Method]: {
-  id: RequestId;
-  method: M;
-} & Pick<Methods[M], "params">; }[Method];
-interface ProtocolError {
-  code: ErrorCode;
-  message: string;
-}
-type ServerResponse = {
-  id: RequestId;
-  result: Methods[Method]["result"];
-} | {
-  id: RequestId | null;
-  error: ProtocolError;
-};
-/** A full status payload, as `stim status --watch --json` prints it. */
-interface StatusEvent {
-  event: "status";
-  subscription: string;
-  payload: StatusPayload;
-}
-/**
- * Records for a `logs.subscribe` subscription: first the last `tail` matching records, then new ones as
- * they arrive.
- */
-interface LogsEvent {
-  event: "logs";
-  subscription: string;
-  records: LogRecord[];
-}
-/** A subscription ended because its source failed or the client fell behind; the client may resubscribe. */
-interface ErrorEvent {
-  event: "error";
-  subscription: string;
-  error: ProtocolError;
-}
-/** A frame of the device's screen, sent when the screen changed, at most `fps` times a second. */
-interface FrameEvent {
-  event: "frame";
-  subscription: string;
-  platform: Platform;
-  slot: string;
-  mime: "image/jpeg";
-  width: number;
-  height: number;
-  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
- * client keeps showing its last frame. Followed by `delayed: false` once captures recover.
- */
-interface FrameDelayedEvent {
-  event: "frame-delayed";
-  subscription: string;
-  delayed: boolean;
-}
-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 { 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, PUSH_EVENTS, PUSH_TOKEN_PATTERN, PairingAuth, Platform, ProtocolError, PushEvent, PushRegisterParams, RELOAD_PLATFORMS, ROTATE_DIRECTIONS, ReloadPlatform, RequestId, RotateDirection, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, TOUCH_PHASES, TouchPhase, UnsubscribeParams, UsageSample, VIDEO_CODECS, VIDEO_FOLDED, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VIDEO_UNFOLDED, VideoCodec, VideoPacket, WorkspaceParams, protocolJsonSchema };
+export { protocolJsonSchema };

package/dist/protocol.mjs

@@ -1,2 +1,3 @@
-import { C as VIDEO_HEADER_VERSION, E as protocolJsonSchema, S as VIDEO_FOLDED, T as VIDEO_UNFOLDED, _ as PUSH_TOKEN_PATTERN, a as ERROR_CODES, b as TOUCH_PHASES, c as INPUT_BUTTONS, d as MAX_INPUT_TEXT, f as MAX_LOG_TAIL, g as PUSH_EVENTS, 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 RELOAD_PLATFORMS, w as VIDEO_KEYFRAME, x as VIDEO_CODECS, y as ROTATE_DIRECTIONS } from "./protocol-IroIg8Td.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, PUSH_EVENTS, PUSH_TOKEN_PATTERN, RELOAD_PLATFORMS, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS, VIDEO_FOLDED, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VIDEO_UNFOLDED, protocolJsonSchema };
+import { t as protocolJsonSchema } from "./protocol-BHSl7bQ_.mjs";
+export * from "@stim-cli/core/protocol";
+export { protocolJsonSchema };