@goliapkg/smix 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goliapkg/smix",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Playwright-shape iOS Simulator / Android emulator UI automation SDK for React Native + Expo + Detox-compatible TypeScript test runners.",
   "type": "module",
   "license": "Apache-2.0 OR MIT",

package/src/HttpRunner.ts

@@ -46,7 +46,14 @@ import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
 export type HttpFetch = (
   input: string,
   init: { method: 'POST'; headers: Record<string, string>; body: string },
-) => Promise<{ ok: boolean; status: number; json(): Promise<unknown>; text(): Promise<string> }>
+) => Promise<{
+  ok: boolean
+  status: number
+  json(): Promise<unknown>
+  text(): Promise<string>
+  /** v1.0.4 §D7 — optional; used to parse `X-Sim-Health` response header. */
+  headers?: { get(name: string): string | null }
+}>
 
 /**
  * SmixSimRuntime + SelectorResolver wrapper around the smix-runner HTTP
@@ -71,6 +78,14 @@ export class HttpSimRuntime implements SmixSimRuntime {
    */
   private sessionId: string | null = null
 
+  /**
+   * v1.0.4 §D7 — setter installed by {@link Session.open} so this
+   * client can push `X-Sim-Health` header transitions back to the
+   * session's state machine. `null` when no session is open (legacy
+   * per-request path).
+   */
+  private sessionStateSetter: ((state: SessionState) => void) | null = null
+
   /**
    * v1.0.3 — public alias for the wrapped fetch implementation.
    * Consumed by the {@link Session} class which drives `/session/*`
@@ -103,6 +118,15 @@ export class HttpSimRuntime implements SmixSimRuntime {
     this.sessionId = id
   }
 
+  /**
+   * v1.0.4 §D7 — register a callback the client invokes on every
+   * response that carries `X-Sim-Health`. Session.open() wires this
+   * so consumers can subscribe via `session.on('state', ...)`.
+   */
+  attachSessionState(setter: (state: SessionState) => void): void {
+    this.sessionStateSetter = setter
+  }
+
   /**
    * v7.7 c1 — direct match-count via dedicated FFI fn (avoid allocating
    * the full ids list when callers only need count). Mirrors Rust
@@ -193,6 +217,21 @@ export class HttpSimRuntime implements SmixSimRuntime {
       headers,
       body: JSON.stringify(body),
     })
+    // v1.0.4 §D7 — parse X-Sim-Health header and forward to the
+    // attached session state setter (if any). Runs BEFORE the
+    // ok-check so state transitions are visible on error paths too.
+    const simHealthHeader = resp.headers?.get?.('x-sim-health')
+    if (simHealthHeader && this.sessionStateSetter) {
+      const normalized = simHealthHeader.trim().toLowerCase()
+      if (
+        normalized === 'healthy' ||
+        normalized === 'degraded' ||
+        normalized === 'cycling' ||
+        normalized === 'dead'
+      ) {
+        this.sessionStateSetter(normalized as SessionState)
+      }
+    }
     if (!resp.ok) {
       const text = await resp.text()
       throw new Error(`smix-runner ${path} → HTTP ${resp.status}: ${text}`)
@@ -206,6 +245,9 @@ export class HttpSimRuntime implements SmixSimRuntime {
   }
 }
 
+/** v1.0.4 §D7 — re-export from Session.ts so this file's use compiles. */
+export type SessionState = 'healthy' | 'degraded' | 'cycling' | 'dead'
+
 function base64ToBytes(b64: string): Uint8Array {
   if (typeof globalThis.atob === 'function') {
     const bin = globalThis.atob(b64)

package/src/Session.ts

@@ -31,6 +31,10 @@ interface HttpRunnerLike {
   readonly baseUrl: string
   readonly fetch: HttpFetch
   setSessionId(id: string | null): void
+  /** v1.0.4 §D7 — optional hook so the client can push state
+   * transitions parsed from `X-Sim-Health` headers back to the
+   * Session. Legacy runners omit the header; state stays `healthy`. */
+  attachSessionState?(setter: (state: SessionState) => void): void
 }
 
 export interface SessionOpenOptions {
@@ -38,6 +42,15 @@ export interface SessionOpenOptions {
   activate?: boolean
 }
 
+/**
+ * v1.0.4 §D7 — session-scoped sim health classification observed via
+ * the runner's `X-Sim-Health` response header. Consumers subscribe
+ * via {@link Session.on}.
+ */
+export type SessionState = 'healthy' | 'degraded' | 'cycling' | 'dead'
+
+type StateListener = (state: SessionState) => void
+
 /**
  * Runner-side session guard. Use `Session.open()` to acquire, always
  * pair with `session.close()` in a `finally` block.
@@ -48,6 +61,11 @@ export interface SessionOpenOptions {
  * cached binding.
  */
 export class Session {
+  /** v1.0.4 §D7 — current classification; updated on every response
+   * that carries `X-Sim-Health`. */
+  private _state: SessionState = 'healthy'
+  private readonly listeners = new Set<StateListener>()
+
   private constructor(
     private readonly runner: HttpRunnerLike,
     public readonly sessionId: string,
@@ -79,12 +97,84 @@ export class Session {
       throw new Error(`Session.open ${bundleId}: response missing sessionId`)
     }
     runner.setSessionId(json.sessionId)
-    return new Session(
+    const session = new Session(
       runner,
       json.sessionId,
       json.activatedOnce ?? false,
       json.serverTimeMs ?? 0,
     )
+    // v1.0.4 §D7 — wire the runner's X-Sim-Health parse into this
+    // session's state machine. Legacy runner-clients without the
+    // attachSessionState hook keep working; the session's state stays
+    // 'healthy'.
+    runner.attachSessionState?.((next) => session.updateState(next))
+    return session
+  }
+
+  /** v1.0.4 §D7 — current sim-health classification. */
+  get state(): SessionState {
+    return this._state
+  }
+
+  /** v1.0.4 §D7 — subscribe to state transitions. Returns an
+   * unsubscribe function. */
+  on(_event: 'state', listener: StateListener): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  /** v1.0.5 §D1 — probe `/session/list` and return `true` iff this
+   * session's id is still known to the runner. Consumers wire this
+   * after a state transition to `cycling`/`dead` to decide whether
+   * to keep the session or reopen. */
+  async stillValid(): Promise<boolean> {
+    const res = await this.runner.fetch(
+      `${this.runner.baseUrl}/session/list`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: '{}',
+      },
+    )
+    if (!res.ok) return false
+    const json = (await res.json()) as {
+      sessions?: Array<{ sessionId?: string }>
+    }
+    return (json.sessions ?? []).some((s) => s.sessionId === this.sessionId)
+  }
+
+  /** v1.0.4 §D14 — instruct the runner to `terminate()` + `launch()`
+   * the session's cached `XCUIApplication` in place. Preserves the
+   * session id and XCUITest binding. Returns wall-clock ms. */
+  async relaunchApp(): Promise<number> {
+    const res = await this.runner.fetch(
+      `${this.runner.baseUrl}/session/relaunch-app`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId: this.sessionId }),
+      },
+    )
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(
+        `Session.relaunchApp ${this.sessionId}: HTTP ${res.status}: ${body}`,
+      )
+    }
+    const json = (await res.json()) as { ok?: boolean; wallMs?: number }
+    return json.wallMs ?? 0
+  }
+
+  private updateState(next: SessionState) {
+    if (next === this._state) return
+    this._state = next
+    for (const listener of this.listeners) {
+      try {
+        listener(next)
+      } catch {
+        // Consumer callbacks must not break the runner-response path.
+      }
+    }
   }
 
   /**