@alivelabs/expo-orchestrator-schemas 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@alivelabs/expo-orchestrator-schemas",
+  "version": "0.1.0",
+  "description": "Shared Zod schemas for the Expo CI Orchestrator wire contract.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alive-home/alive-expo-orchestrator.git",
+    "directory": "packages/schemas"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./common": "./src/common.ts",
+    "./session": "./src/session.ts",
+    "./simulator": "./src/simulator.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/src/common.ts

@@ -0,0 +1,16 @@
+import * as z from "zod";
+
+/** `:sessionId` route parameter, shared by every session-scoped route. */
+export const SessionIdParamSchema = z.object({
+  sessionId: z.string().min(1),
+});
+export type SessionIdParam = z.infer<typeof SessionIdParamSchema>;
+
+/** Uniform error body returned by the Fastify error handler. */
+export const ErrorResponseSchema = z.object({
+  error: z.string(),
+  code: z.string(),
+  message: z.string(),
+  details: z.unknown().optional(),
+});
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./common";
+export * from "./session";
+export * from "./simulator";

package/src/session.ts

@@ -0,0 +1,191 @@
+import * as z from "zod";
+
+export const PlatformSchema = z.enum(["ios", "android"]);
+export type Platform = z.infer<typeof PlatformSchema>;
+
+export const SessionStatusSchema = z.enum([
+  "created",
+  "running",
+  "completed",
+  "failed",
+  "timeout",
+  "deleted",
+]);
+export type SessionStatus = z.infer<typeof SessionStatusSchema>;
+
+export const SourceTypeSchema = z.enum(["git", "local", "tarball"]);
+export type SourceType = z.infer<typeof SourceTypeSchema>;
+
+export const LogLevelSchema = z.enum(["stdout", "stderr", "system"]);
+export type LogLevel = z.infer<typeof LogLevelSchema>;
+
+/** A single captured log line. */
+export const LogSchema = z.object({
+  timestamp: z.string(),
+  level: LogLevelSchema,
+  message: z.string(),
+});
+export type Log = z.infer<typeof LogSchema>;
+
+/** Optional build secrets — accepted on input, never echoed back. */
+export const SessionSecretsSchema = z.strictObject({
+  npmToken: z.string().min(1).optional(),
+  appleDeveloperTeam: z.string().min(1).optional(),
+  signingCertificate: z.string().min(1).optional(),
+});
+
+/** Only http(s) git URLs are accepted — no file://, git://, ssh, etc. */
+const RepoUrlSchema = z
+  .string()
+  .min(1)
+  .refine((value) => {
+    try {
+      const { protocol } = new URL(value);
+      return protocol === "https:" || protocol === "http:";
+    } catch {
+      return false;
+    }
+  }, "repoUrl must be an http or https URL");
+
+/**
+ * Where a build's source code comes from:
+ *  - `git`     — cloned from a public http(s) repo inside the sandbox
+ *  - `local`   — a directory on the orchestrator host (within LOCAL_SOURCE_ROOT)
+ *  - `tarball` — a gzip tar archive uploaded to POST /api/sessions/:id/source
+ */
+export const SessionSourceSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    type: z.literal("git"),
+    repoUrl: RepoUrlSchema,
+    branch: z.string().min(1).max(255).default("main"),
+  }),
+  z.strictObject({
+    type: z.literal("local"),
+    path: z.string().min(1).max(4096),
+  }),
+  z.strictObject({
+    type: z.literal("tarball"),
+  }),
+]);
+
+/**
+ * Where the launched dev-client app should attach for HMR / JS bundle. Must be
+ * an http(s) URL reachable from the simulator host. When set, the build is a
+ * Debug dev-client pointed at this URL; when omitted, a Release build with the
+ * JS bundle embedded is produced instead.
+ */
+const DevServerUrlSchema = z
+  .string()
+  .min(1)
+  .max(2048)
+  .refine((value) => {
+    try {
+      const { protocol } = new URL(value);
+      return protocol === "https:" || protocol === "http:";
+    } catch {
+      return false;
+    }
+  }, "devServerUrl must be an http or https URL");
+
+/**
+ * Relative path to the Expo app within the source, for monorepos — e.g.
+ * `apps/mobile`. Dependencies install at the workspace root (wherever the
+ * lockfile lives); `expo prebuild` and the iOS build run here. Defaults to the
+ * source root. Must stay inside the source tree (no leading `/`, no `..`).
+ */
+const AppRootSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .refine(
+    (value) =>
+      !value.startsWith("/") &&
+      !value.includes("\\") &&
+      !value.includes("\0") &&
+      !value.split("/").includes(".."),
+    "appRoot must be a relative path within the source (no leading '/', no '..')",
+  );
+
+export const CreateSessionBodySchema = z.strictObject({
+  source: SessionSourceSchema,
+  platform: PlatformSchema,
+  simulatorName: z.string().min(1).max(255).optional(),
+  devServerUrl: DevServerUrlSchema.optional(),
+  appRoot: AppRootSchema.optional(),
+  timeout: z.number().int().min(60).max(3600).default(1800),
+  secrets: SessionSecretsSchema.optional(),
+});
+export type CreateSessionBody = z.infer<typeof CreateSessionBodySchema>;
+
+export const CreateSessionResponseSchema = z.object({
+  sessionId: z.string(),
+  status: z.literal("created"),
+  buildUser: z.string(),
+  wsUrl: z.string(),
+  createdAt: z.string(),
+});
+export type CreateSessionResponse = z.infer<typeof CreateSessionResponseSchema>;
+
+export const StartSessionResponseSchema = z.object({
+  sessionId: z.string(),
+  status: z.literal("running"),
+  pid: z.number().int(),
+  startedAt: z.string(),
+});
+export type StartSessionResponse = z.infer<typeof StartSessionResponseSchema>;
+
+export const UploadSourceResponseSchema = z.object({
+  sessionId: z.string(),
+  sourceStored: z.boolean(),
+  bytes: z.number().int(),
+});
+export type UploadSourceResponse = z.infer<typeof UploadSourceResponseSchema>;
+
+export const SessionDetailSchema = z.object({
+  sessionId: z.string(),
+  status: SessionStatusSchema,
+  buildUser: z.string(),
+  platform: PlatformSchema,
+  sourceType: SourceTypeSchema,
+  repoUrl: z.string().optional(),
+  branch: z.string().optional(),
+  sourcePath: z.string().optional(),
+  simulatorName: z.string().optional(),
+  createdAt: z.string(),
+  startTime: z.string().optional(),
+  endTime: z.string().optional(),
+  duration: z.number().optional(),
+  exitCode: z.number().optional(),
+  error: z.string().optional(),
+});
+export type SessionDetail = z.infer<typeof SessionDetailSchema>;
+
+export const DeleteSessionResponseSchema = z.object({
+  sessionId: z.string(),
+  status: z.literal("deleted"),
+  logsArchived: z.boolean(),
+  cleanupDuration: z.number(),
+});
+export type DeleteSessionResponse = z.infer<typeof DeleteSessionResponseSchema>;
+
+export const LogsResponseSchema = z.object({
+  sessionId: z.string(),
+  logs: z.array(LogSchema),
+});
+
+// A session-scoped access token: the master-token holder mints one of these to
+// hand an end user, granting them only that session's video stream, input, and
+// screenshots — not session creation, deletion, or access to other sessions.
+export const SessionTokenBodySchema = z.strictObject({
+  // Lifetime in seconds; defaults server-side to the session's remaining budget.
+  ttlSeconds: z.number().int().min(60).max(3600).optional(),
+});
+export type SessionTokenBody = z.infer<typeof SessionTokenBodySchema>;
+
+export const SessionTokenResponseSchema = z.object({
+  sessionId: z.string(),
+  token: z.string(),
+  expiresAt: z.string(),
+  wsUrl: z.string(),
+});
+export type SessionTokenResponse = z.infer<typeof SessionTokenResponseSchema>;

package/src/simulator.ts

@@ -0,0 +1,180 @@
+import * as z from "zod";
+
+/**
+ * Shapes mirror baguette's wire-protocol gestures one-for-one
+ * (`.claude/skills/baguette/references/wire-protocol.md`). The orchestrator
+ * is a pass-through: it serialises the payload as the JSON line baguette
+ * expects, and for pointer types (`tap`, `swipe`) it injects the simulator
+ * frame's `width`/`height` server-side so the client doesn't have to know
+ * the device dimensions.
+ *
+ * Pointer coordinates are in the same units as the streamed frame
+ * (screenshot pixels) — baguette normalises by `x / width` internally.
+ *
+ * Gestures intentionally omitted for now (add as needed):
+ *   touch1-down/move/up, touch2-down/move/up, pinch, pan.
+ */
+
+const Coord = z.number();
+const Duration = z.number().min(0).max(10).optional();
+
+export const TapInputSchema = z.strictObject({
+  type: z.literal("tap"),
+  x: Coord,
+  y: Coord,
+  duration: Duration,
+});
+
+export const SwipeInputSchema = z.strictObject({
+  type: z.literal("swipe"),
+  startX: Coord,
+  startY: Coord,
+  endX: Coord,
+  endY: Coord,
+  duration: Duration,
+});
+
+export const ScrollInputSchema = z.strictObject({
+  type: z.literal("scroll"),
+  deltaX: z.number(),
+  deltaY: z.number(),
+});
+
+/** Hardware + virtual buttons. `siri` is intentionally excluded (crashes backboardd). */
+export const ButtonNameSchema = z.enum([
+  "home",
+  "lock",
+  "power",
+  "volume-up",
+  "volume-down",
+  "action",
+  "app-switcher",
+  "swipe-to-app-switcher",
+  "swipe-to-home",
+  "pull-down-to-lock-screen",
+  "pull-down-to-notification-center",
+]);
+
+export const ButtonInputSchema = z.strictObject({
+  type: z.literal("button"),
+  button: ButtonNameSchema,
+  duration: Duration,
+});
+
+/** W3C `KeyboardEvent.code` — baguette's supported set. */
+export const KeyCodeSchema = z.enum([
+  "KeyA",
+  "KeyB",
+  "KeyC",
+  "KeyD",
+  "KeyE",
+  "KeyF",
+  "KeyG",
+  "KeyH",
+  "KeyI",
+  "KeyJ",
+  "KeyK",
+  "KeyL",
+  "KeyM",
+  "KeyN",
+  "KeyO",
+  "KeyP",
+  "KeyQ",
+  "KeyR",
+  "KeyS",
+  "KeyT",
+  "KeyU",
+  "KeyV",
+  "KeyW",
+  "KeyX",
+  "KeyY",
+  "KeyZ",
+  "Digit0",
+  "Digit1",
+  "Digit2",
+  "Digit3",
+  "Digit4",
+  "Digit5",
+  "Digit6",
+  "Digit7",
+  "Digit8",
+  "Digit9",
+  "Enter",
+  "Escape",
+  "Backspace",
+  "Tab",
+  "Space",
+  "ArrowUp",
+  "ArrowDown",
+  "ArrowLeft",
+  "ArrowRight",
+  "Minus",
+  "Equal",
+  "BracketLeft",
+  "BracketRight",
+  "Backslash",
+  "Semicolon",
+  "Quote",
+  "Backquote",
+  "Comma",
+  "Period",
+  "Slash",
+]);
+
+export const KeyModifierSchema = z.enum(["shift", "control", "option", "command"]);
+
+export const KeyInputSchema = z.strictObject({
+  type: z.literal("key"),
+  code: KeyCodeSchema,
+  modifiers: z.array(KeyModifierSchema).optional(),
+  duration: Duration,
+});
+
+export const TypeInputSchema = z.strictObject({
+  type: z.literal("type"),
+  text: z.string().min(1).max(1000),
+});
+
+/** Discriminated union of every supported simulator interaction. */
+export const SimulatorInputSchema = z.discriminatedUnion("type", [
+  TapInputSchema,
+  SwipeInputSchema,
+  ScrollInputSchema,
+  ButtonInputSchema,
+  KeyInputSchema,
+  TypeInputSchema,
+]);
+export type SimulatorInput = z.infer<typeof SimulatorInputSchema>;
+
+export type SimulatorButton = z.infer<typeof ButtonNameSchema>;
+export type SimulatorKeyCode = z.infer<typeof KeyCodeSchema>;
+export type SimulatorKeyModifier = z.infer<typeof KeyModifierSchema>;
+
+export const SimulatorInputResponseSchema = z.object({
+  sessionId: z.string(),
+  inputType: z.string(),
+  processed: z.boolean(),
+  screenshotUrl: z.string(),
+});
+export type SimulatorInputResponse = z.infer<typeof SimulatorInputResponseSchema>;
+
+// ── Host-level: available simulators ─────────────────────────────────────────
+// `GET /api/simulators` returns every simulator the host can boot, plus a
+// recommended default name the Launcher pre-selects. Shape mirrors what
+// `baguette list --json` emits per device.
+
+export const SimulatorDeviceSchema = z.object({
+  udid: z.string(),
+  name: z.string(),
+  runtime: z.string(),
+  state: z.string(),
+});
+export type SimulatorDevice = z.infer<typeof SimulatorDeviceSchema>;
+
+export const ListSimulatorsResponseSchema = z.object({
+  devices: z.array(SimulatorDeviceSchema),
+  /** Name of the simulator the Launcher should pre-select. `null` when the
+   *  host has no available device (`devices` is empty too in that case). */
+  recommended: z.string().nullable(),
+});
+export type ListSimulatorsResponse = z.infer<typeof ListSimulatorsResponseSchema>;