@stim-cli/server 1.10.1 → 1.12.0

package/dist/protocol-BElQc2vm.mjs

@@ -0,0 +1,808 @@
+//#region src/protocol.ts
+const PROTOCOL_VERSION = 1;
+const PROTOCOL_SCHEMA_FILE = "protocol.schema.json";
+/** `read` serves state. `control` also runs {@link ACTIONS}; only the Mac grants it. */
+const CAPABILITIES = ["read", "control"];
+const METHODS = [
+	"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"
+];
+/**
+* `unauthorized`, `pairing-expired` and `protocol-unsupported` refuse the client until it pairs again or
+* updates; clients retry the others.
+*/
+const ERROR_CODES = [
+	"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"
+];
+const LOG_SOURCES = [
+	"metro",
+	"client",
+	"device",
+	"build",
+	"agent"
+];
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+];
+const MAX_LOG_TAIL = 5e3;
+const FRAME_FPS = {
+	default: 5,
+	max: 30,
+	video: 60
+};
+const FRAME_EDGE = {
+	min: 240,
+	default: 1280,
+	max: 2048
+};
+const VIDEO_CODECS = ["h264"];
+const VIDEO_HEADER_VERSION = 1;
+/** The keyframe bit of a {@link VideoPacket}'s flags. */
+const VIDEO_KEYFRAME = 1;
+/** Each action runs one fixed `stim` command in the workspace. */
+const ACTIONS = ["reload", "stop"];
+const TOUCH_PHASES = [
+	"down",
+	"move",
+	"up"
+];
+const MAX_INPUT_TEXT = 256;
+/** `home` and `lock` on both platforms; `back` and `app-switch` on Android only. */
+const INPUT_BUTTONS = [
+	"home",
+	"lock",
+	"back",
+	"app-switch"
+];
+/** `left` turns the device a quarter turn counterclockwise, `right` clockwise. */
+const ROTATE_DIRECTIONS = ["left", "right"];
+const DEVICE_POSTURES = [
+	"folded",
+	"half-open",
+	"unfolded"
+];
+const CONTROL_END_REASONS = [
+	"idle",
+	"taken-over",
+	"device-gone",
+	"forbidden",
+	"failed"
+];
+const requestId = { type: ["integer", "string"] };
+const protocolError = {
+	type: "object",
+	required: ["code", "message"],
+	additionalProperties: false,
+	properties: {
+		code: { enum: [...ERROR_CODES] },
+		message: { type: "string" }
+	}
+};
+function request(method, params) {
+	return {
+		type: "object",
+		required: params ? [
+			"id",
+			"method",
+			"params"
+		] : ["id", "method"],
+		additionalProperties: false,
+		properties: {
+			id: requestId,
+			method: { const: method },
+			params: params ?? {
+				type: "object",
+				maxProperties: 0
+			}
+		}
+	};
+}
+function session(properties, required = []) {
+	return {
+		type: "object",
+		required: ["session", ...required],
+		additionalProperties: false,
+		properties: {
+			session: { type: "string" },
+			...properties
+		}
+	};
+}
+function optionalParams(method, params) {
+	return {
+		type: "object",
+		required: ["id", "method"],
+		additionalProperties: false,
+		properties: {
+			id: requestId,
+			method: { const: method },
+			params
+		}
+	};
+}
+/** The JSON Schema of every message on the wire, written to `dist/protocol.schema.json` at build time. */
+function protocolJsonSchema() {
+	return {
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		title: "Stim server protocol",
+		description: `Messages exchanged over the stim-server WebSocket, protocol version 1.`,
+		"x-stim-protocol": 1,
+		$defs: {
+			ProtocolError: protocolError,
+			HelloParams: {
+				type: "object",
+				required: [
+					"protocol",
+					"client",
+					"auth"
+				],
+				additionalProperties: false,
+				properties: {
+					protocol: { type: "integer" },
+					client: {
+						type: "object",
+						required: ["name", "version"],
+						properties: {
+							name: { type: "string" },
+							version: { type: "string" }
+						}
+					},
+					auth: { oneOf: [{
+						type: "object",
+						required: ["pairingToken", "deviceName"],
+						additionalProperties: false,
+						properties: {
+							pairingToken: { type: "string" },
+							deviceName: {
+								type: "string",
+								minLength: 1
+							}
+						}
+					}, {
+						type: "object",
+						required: ["deviceToken"],
+						additionalProperties: false,
+						properties: { deviceToken: { type: "string" } }
+					}] }
+				}
+			},
+			HelloResult: {
+				type: "object",
+				required: [
+					"protocol",
+					"server",
+					"capabilities",
+					"actions",
+					"device"
+				],
+				additionalProperties: false,
+				properties: {
+					protocol: { type: "integer" },
+					server: {
+						type: "object",
+						required: [
+							"name",
+							"version",
+							"stim",
+							"home"
+						],
+						additionalProperties: false,
+						properties: {
+							name: { type: "string" },
+							version: { type: "string" },
+							stim: { type: "string" },
+							home: { type: "string" }
+						}
+					},
+					capabilities: {
+						type: "array",
+						items: { enum: [...CAPABILITIES] }
+					},
+					actions: {
+						type: "array",
+						items: { enum: [...ACTIONS] }
+					},
+					device: {
+						type: "object",
+						required: ["id", "name"],
+						additionalProperties: false,
+						properties: {
+							id: { type: "string" },
+							name: { type: "string" }
+						}
+					},
+					deviceToken: { type: "string" }
+				}
+			},
+			LogRecord: {
+				type: "object",
+				description: "One record as `stim logs --json` prints it.",
+				properties: {
+					ts: { type: "number" },
+					src: { type: "string" },
+					level: { type: "string" },
+					msg: { type: "string" }
+				}
+			},
+			LogFilter: {
+				type: "object",
+				required: ["workspace"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					sources: {
+						type: "array",
+						minItems: 1,
+						items: { enum: [...LOG_SOURCES] }
+					},
+					level: { enum: [...LOG_LEVELS] },
+					slot: {
+						type: "string",
+						pattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
+					},
+					grep: {
+						type: "string",
+						pattern: "^[^\\u0000]*$",
+						description: "A regular expression matched against each message."
+					},
+					errors: { type: "boolean" },
+					tail: {
+						type: "integer",
+						minimum: 1,
+						maximum: MAX_LOG_TAIL,
+						default: MAX_LOG_TAIL
+					}
+				}
+			},
+			FrameTarget: {
+				type: "object",
+				required: ["workspace", "platform"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					platform: { enum: ["ios", "android"] },
+					slot: {
+						type: "string",
+						minLength: 1,
+						default: "default"
+					},
+					fps: {
+						type: "integer",
+						minimum: 1,
+						maximum: FRAME_FPS.video,
+						default: FRAME_FPS.default,
+						description: `At most ${FRAME_FPS.max} unless the result offers video.`
+					},
+					maxEdge: {
+						type: "integer",
+						minimum: FRAME_EDGE.min,
+						maximum: FRAME_EDGE.max,
+						default: FRAME_EDGE.default
+					},
+					video: {
+						type: "array",
+						items: { enum: [...VIDEO_CODECS] }
+					}
+				}
+			},
+			ActionParams: { oneOf: [{
+				type: "object",
+				required: ["action", "workspace"],
+				additionalProperties: false,
+				properties: {
+					action: { const: "reload" },
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					platform: { enum: ["ios", "android"] }
+				}
+			}, {
+				type: "object",
+				required: ["action", "workspace"],
+				additionalProperties: false,
+				properties: {
+					action: { const: "stop" },
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					}
+				}
+			}] },
+			ActionResult: {
+				type: "object",
+				required: [
+					"action",
+					"workspace",
+					"output"
+				],
+				additionalProperties: false,
+				properties: {
+					action: { enum: [...ACTIONS] },
+					workspace: { type: "string" },
+					output: {
+						type: "object",
+						description: "The JSON the command printed."
+					}
+				}
+			},
+			ControlBeginParams: {
+				type: "object",
+				required: ["workspace", "platform"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					platform: { enum: ["ios", "android"] },
+					slot: {
+						type: "string",
+						minLength: 1,
+						default: "default"
+					},
+					takeOver: {
+						type: "boolean",
+						default: false
+					}
+				}
+			},
+			ControlBeginResult: {
+				type: "object",
+				required: [
+					"session",
+					"platform",
+					"lease",
+					"postures"
+				],
+				additionalProperties: false,
+				properties: {
+					session: { type: "string" },
+					platform: { enum: ["ios", "android"] },
+					lease: { oneOf: [{ type: "null" }, {
+						type: "object",
+						required: ["grantedAt", "expiresAt"],
+						additionalProperties: false,
+						properties: {
+							grantedAt: {
+								type: ["string", "null"],
+								format: "date-time"
+							},
+							expiresAt: {
+								type: "string",
+								format: "date-time"
+							}
+						}
+					}] },
+					postures: {
+						type: "array",
+						items: { enum: [...DEVICE_POSTURES] },
+						uniqueItems: true
+					}
+				}
+			},
+			BuildPlanParams: {
+				type: "object",
+				required: ["workspace", "platform"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					platform: { enum: ["ios", "android"] },
+					slot: {
+						type: "string",
+						pattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$",
+						default: "default"
+					}
+				}
+			},
+			WorkspaceParams: {
+				type: "object",
+				additionalProperties: false,
+				properties: { workspace: {
+					type: "string",
+					description: "An environment path from a status payload."
+				} }
+			},
+			MachineHistory: {
+				type: "object",
+				required: ["intervalMs", "samples"],
+				additionalProperties: false,
+				properties: {
+					intervalMs: { type: "integer" },
+					samples: {
+						type: "array",
+						items: {
+							type: "object",
+							required: [
+								"at",
+								"cpu",
+								"memoryUsedBytes",
+								"memoryPressure",
+								"diskFreeBytes"
+							],
+							additionalProperties: false,
+							properties: {
+								at: { type: "integer" },
+								cpu: { type: ["number", "null"] },
+								memoryUsedBytes: { type: ["number", "null"] },
+								memoryPressure: { enum: [
+									0,
+									1,
+									2,
+									null
+								] },
+								diskFreeBytes: { type: ["number", "null"] }
+							}
+						}
+					}
+				}
+			},
+			MachineUsage: {
+				type: "object",
+				required: [
+					"volumes",
+					"memory",
+					"load",
+					"cpu",
+					"sampledAt"
+				],
+				additionalProperties: false,
+				properties: {
+					volumes: {
+						type: "array",
+						items: {
+							type: "object",
+							required: [
+								"mount",
+								"holds",
+								"freeBytes",
+								"totalBytes"
+							],
+							additionalProperties: false,
+							properties: {
+								mount: { type: "string" },
+								holds: {
+									type: "array",
+									items: { type: "string" }
+								},
+								freeBytes: { type: "number" },
+								totalBytes: { type: "number" }
+							}
+						}
+					},
+					memory: {
+						type: "object",
+						required: [
+							"totalBytes",
+							"usedBytes",
+							"pressure"
+						],
+						additionalProperties: false,
+						properties: {
+							totalBytes: { type: "number" },
+							usedBytes: { type: ["number", "null"] },
+							pressure: { enum: [
+								"normal",
+								"warning",
+								"critical",
+								null
+							] }
+						}
+					},
+					load: {
+						type: "object",
+						required: [
+							"avg1",
+							"avg5",
+							"avg15",
+							"cpus"
+						],
+						additionalProperties: false,
+						properties: {
+							avg1: { type: "number" },
+							avg5: { type: "number" },
+							avg15: { type: "number" },
+							cpus: { type: "integer" }
+						}
+					},
+					cpu: {
+						type: "object",
+						required: ["usage", "cores"],
+						additionalProperties: false,
+						properties: {
+							usage: { type: ["number", "null"] },
+							cores: { type: "integer" }
+						}
+					},
+					sampledAt: {
+						type: "string",
+						format: "date-time"
+					}
+				}
+			},
+			ClientRequest: { oneOf: [
+				request("hello", { $ref: "#/$defs/HelloParams" }),
+				request("status.subscribe"),
+				request("logs.query", { $ref: "#/$defs/LogFilter" }),
+				request("logs.subscribe", { $ref: "#/$defs/LogFilter" }),
+				request("frames.subscribe", { $ref: "#/$defs/FrameTarget" }),
+				request("frames.keyframe", {
+					type: "object",
+					required: ["subscription"],
+					additionalProperties: false,
+					properties: { subscription: { type: "string" } }
+				}),
+				request("build.plan", { $ref: "#/$defs/BuildPlanParams" }),
+				request("machine.get"),
+				optionalParams("machine.history", {
+					type: "object",
+					additionalProperties: false,
+					properties: { sinceMs: { type: "number" } }
+				}),
+				optionalParams("stats.get", { $ref: "#/$defs/WorkspaceParams" }),
+				optionalParams("settings.get", { $ref: "#/$defs/WorkspaceParams" }),
+				request("unsubscribe", {
+					type: "object",
+					required: ["subscription"],
+					additionalProperties: false,
+					properties: { subscription: { type: "string" } }
+				}),
+				request("action", { $ref: "#/$defs/ActionParams" }),
+				request("control.begin", { $ref: "#/$defs/ControlBeginParams" }),
+				request("control.end", session({})),
+				request("input.touch", session({
+					phase: { enum: [...TOUCH_PHASES] },
+					x: {
+						type: "number",
+						minimum: 0,
+						maximum: 1
+					},
+					y: {
+						type: "number",
+						minimum: 0,
+						maximum: 1
+					},
+					display: {
+						type: "integer",
+						minimum: 0,
+						maximum: 3,
+						default: 0
+					}
+				}, [
+					"phase",
+					"x",
+					"y"
+				])),
+				request("input.text", session({ text: {
+					type: "string",
+					minLength: 1,
+					maxLength: 256,
+					pattern: "^[\\x20-\\x7e\\n\\t\\b]+$"
+				} }, ["text"])),
+				request("input.button", session({ button: { enum: [...INPUT_BUTTONS] } }, ["button"])),
+				request("input.rotate", session({ direction: { enum: [...ROTATE_DIRECTIONS] } }, ["direction"])),
+				request("input.posture", session({ posture: { enum: [...DEVICE_POSTURES] } }, ["posture"]))
+			] },
+			ServerResponse: { oneOf: [{
+				type: "object",
+				required: ["id", "result"],
+				additionalProperties: false,
+				properties: {
+					id: requestId,
+					result: { anyOf: [
+						{ $ref: "#/$defs/HelloResult" },
+						{ $ref: "#/$defs/ControlBeginResult" },
+						{ $ref: "#/$defs/ActionResult" },
+						{ $ref: "#/$defs/MachineUsage" },
+						{ $ref: "#/$defs/MachineHistory" },
+						{
+							type: "object",
+							required: ["subscription"],
+							additionalProperties: false,
+							properties: {
+								subscription: { type: "string" },
+								video: { enum: [...VIDEO_CODECS] }
+							}
+						},
+						{
+							type: "object",
+							required: ["records"],
+							additionalProperties: false,
+							properties: { records: {
+								type: "array",
+								items: { $ref: "#/$defs/LogRecord" }
+							} }
+						},
+						{
+							type: "object",
+							description: "The payload of `stim stats --json`, `stim settings --json` or `stim ios|android --plan --json`, or {} for unsubscribe."
+						}
+					] }
+				}
+			}, {
+				type: "object",
+				required: ["id", "error"],
+				additionalProperties: false,
+				properties: {
+					id: { type: [
+						"integer",
+						"string",
+						"null"
+					] },
+					error: { $ref: "#/$defs/ProtocolError" }
+				}
+			}] },
+			ServerEvent: { oneOf: [
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"payload"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "status" },
+						subscription: { type: "string" },
+						payload: {
+							type: "object",
+							description: "A full payload, as `stim status --watch --json` prints it."
+						}
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"records"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "logs" },
+						subscription: { type: "string" },
+						records: {
+							type: "array",
+							items: { $ref: "#/$defs/LogRecord" }
+						}
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"platform",
+						"slot",
+						"mime",
+						"width",
+						"height",
+						"capturedAt",
+						"data"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "frame" },
+						subscription: { type: "string" },
+						platform: { enum: ["ios", "android"] },
+						slot: { type: "string" },
+						mime: { const: "image/jpeg" },
+						width: { type: "integer" },
+						height: { type: "integer" },
+						capturedAt: {
+							type: "string",
+							format: "date-time"
+						},
+						data: {
+							type: "string",
+							contentEncoding: "base64"
+						},
+						posture: { enum: ["folded", "unfolded"] }
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"delayed"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "frame-delayed" },
+						subscription: { type: "string" },
+						delayed: { type: "boolean" }
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"session",
+						"reason",
+						"message"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "control-ended" },
+						session: { type: "string" },
+						reason: { enum: [...CONTROL_END_REASONS] },
+						message: { type: "string" }
+					}
+				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"subscription",
+						"error"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "error" },
+						subscription: { type: "string" },
+						error: { $ref: "#/$defs/ProtocolError" }
+					}
+				}
+			] }
+		},
+		oneOf: [
+			{ $ref: "#/$defs/ClientRequest" },
+			{ $ref: "#/$defs/ServerResponse" },
+			{ $ref: "#/$defs/ServerEvent" }
+		]
+	};
+}
+//#endregion
+export { TOUCH_PHASES as _, ERROR_CODES as a, VIDEO_KEYFRAME as b, INPUT_BUTTONS as c, MAX_INPUT_TEXT as d, MAX_LOG_TAIL as f, ROTATE_DIRECTIONS as g, PROTOCOL_VERSION as h, DEVICE_POSTURES as i, LOG_LEVELS as l, PROTOCOL_SCHEMA_FILE as m, CAPABILITIES as n, FRAME_EDGE as o, METHODS as p, CONTROL_END_REASONS as r, FRAME_FPS as s, ACTIONS as t, LOG_SOURCES as u, VIDEO_CODECS as v, protocolJsonSchema as x, VIDEO_HEADER_VERSION as y };