@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/outputClient/real.ts

@@ -0,0 +1,393 @@
+import { fileURLToPath } from "node:url"
+
+import type pino from "pino"
+
+import { createGestureDetector } from "@/core/gesture-state"
+import { pushBlackFrame } from "@/device/black-frame"
+import type { DeviceDescriptor } from "@/device/registry"
+import { createReconnectingDevice } from "@/device/reconnecting"
+import { connectStreamDeck, type StreamDeckDevice } from "@/device/stream-deck"
+import { BrowserRenderer } from "@/render/browser-renderer"
+import { pushRawImage } from "@/render/push-raw-image"
+import { NoStreamDeckFoundError, selectDevice } from "@/system/device-selection"
+import { saveDeviceConfig } from "@/util/device-config"
+
+import {
+  DEFAULT_FRONTEND_PORT,
+  killChild,
+  resolveConfigUiCwd,
+  resolveFrontendCwd,
+  spawnConfigUiVite,
+  spawnFrontendVite,
+} from "../cli/commands/emulator-mode"
+import {
+  DEFAULT_VITE_RETRY_SCHEDULE_MS,
+  supervise,
+  type SuperviseHandle,
+} from "../cli/commands/subprocess-supervisor"
+
+import type { InitOptions, OutputClient, OutputHandle } from "./types"
+import { writeRuntimeState, type RuntimeState } from "@/util/daemon"
+
+export interface RealOutputClientOptions {
+  readonly xdgConfigHome: string
+}
+
+export class RealOutputClient implements OutputClient {
+  readonly kind = "real" as const
+
+  private readonly xdgConfigHome: string
+  private device: StreamDeckDevice | null = null
+  // ponytail: the Stream Deck SDK exposes setBrightness but no getter, so we
+  // track the last value we set to skip redundant hardware writes.
+  private deviceBrightness: number | null = null
+  private descriptor: DeviceDescriptor | null = null
+
+  constructor(options: RealOutputClientOptions) {
+    this.xdgConfigHome = options.xdgConfigHome
+  }
+
+  async validateReady(): Promise<void> {
+    const devices = await this.listDevices()
+    if (devices.length === 0) {
+      throw new Error(
+        "No Stream Deck devices found. Connect a device and try again. On Linux, udev rules for vendor 0fd9 may be required — see packages/cli/src/device/linux-udev.ts for the rule file template.",
+      )
+    }
+  }
+
+  async listDevices(): Promise<ReadonlyArray<DeviceDescriptor>> {
+    return (await import("@/device/registry")).listDevices()
+  }
+
+  async selectDevice(
+    devices: ReadonlyArray<DeviceDescriptor>,
+    savedId: string | null,
+    logger: pino.Logger,
+  ): Promise<DeviceDescriptor> {
+    try {
+      const selection = await selectDevice({
+        devices,
+        ...(savedId !== null
+          ? {
+              current: {
+                serial: savedId,
+                path: "",
+                model: "",
+              },
+            }
+          : {}),
+        logger,
+      })
+      this.descriptor = selection.descriptor
+      return selection.descriptor
+    } catch (err) {
+      if (err instanceof NoStreamDeckFoundError) {
+        throw new Error(
+          "No Stream Deck devices found. Connect a device and try again. On Linux, udev rules may be required — see sireno install-udev.",
+        )
+      }
+      throw err
+    }
+  }
+
+  async storeSelection(descriptor: DeviceDescriptor): Promise<void> {
+    saveDeviceConfig({
+      xdgConfigHome: this.xdgConfigHome,
+      config: {
+        serial: descriptor.id,
+        path: descriptor.id,
+        model: descriptor.model,
+      },
+    })
+  }
+
+  async init(opts: InitOptions): Promise<OutputHandle> {
+    if (this.descriptor === null) {
+      throw new Error("RealOutputClient.init: selectDevice() must run first")
+    }
+    const descriptor = this.descriptor
+    const logger = opts.logger.child({ component: "real" })
+
+    let hardware: StreamDeckDevice
+    try {
+      hardware = await connectStreamDeck({ serial: descriptor.id })
+    } catch {
+      throw new Error(
+        `Saved device ${descriptor.id} is no longer connected. Re-run with --config to pick another.`,
+      )
+    }
+
+    // ponytail: from here on the pipeline talks to a wrapper, not the raw
+    // handle. A KVM switching hosts removes the USB device, the SDK emits
+    // `error`, and with nothing subscribed that unhandled event threw straight
+    // into the daemon's uncaughtException guard — the service died with no
+    // recovery. Nothing else in the pipeline cares about USB, so only the
+    // device handle is swapped; writes are dropped while the deck is away and
+    // the keys are repainted when it returns.
+    let renderer: BrowserRenderer | null = null
+    const device = createReconnectingDevice(hardware, {
+      serial: descriptor.id,
+      connect: connectStreamDeck,
+      logger,
+      onReconnect: async (fresh) => {
+        if (this.deviceBrightness !== null) {
+          await fresh.setBrightness(this.deviceBrightness)
+        }
+        renderer?.forceRedraw()
+      },
+    })
+    this.device = device
+
+    let shuttingDown = false
+    let frontendSupervisor: SuperviseHandle | null = null
+    let configUiSupervisor: SuperviseHandle | null = null
+
+    try {
+      // ponytail: hardware-only splash — push the logo immediately after the
+      // device is connected and before Playwright/Vite takes over. pushRawImage
+      // swallows errors (non-fatal). Skipped on emulator (no pushRawImage method).
+      const splashPath = fileURLToPath(
+        new URL("../assets/logoFull.png", import.meta.url),
+      )
+      try {
+        await pushRawImage({
+          imagePath: splashPath,
+          device,
+          logger,
+        })
+      } catch (err) {
+        logger.warn(
+          { err: (err as Error).message, splashPath },
+          "real: splash push failed (non-fatal)",
+        )
+      }
+
+      opts.bridge.setDevice(descriptor)
+
+      const unsubscribeBrightness = opts.pubSub.subscribe<{
+        deckId: string
+        position: number
+        durationMs: number
+      }>("runtime:buttonError", () => {})
+      void unsubscribeBrightness
+
+      const unsubAdjust = opts.pubSub.subscribe<{
+        direction: "up" | "down"
+        value: number
+      }>("methods:adjustBrightness", ({ value }) => {
+        if (this.device === null) return
+        const current = this.deviceBrightness
+        if (value === current) return
+        this.deviceBrightness = value
+        void this.device.setBrightness(value)
+        logger.info(
+          { from: current, to: value },
+          "real mode: hardware brightness adjusted",
+        )
+        opts.pubSub.publish("sireno:settings:brightness", { value })
+      })
+
+      const mainDeck = opts.decks.find((d) => d.isMain) ?? opts.decks[0]
+
+      const gestureDetector = createGestureDetector({
+        onGesture: (result) => {
+          const keyIndex = result.keyIndex ?? -1
+          const activeDeck = opts.runtime.getActiveDeck()
+          const button = activeDeck.buttons.find((b) => {
+            if (b.position === keyIndex) return true
+            const parsed = Number.parseInt(b.id, 10)
+            return Number.isFinite(parsed) && parsed === keyIndex
+          })
+          const position = button?.position ?? -1
+          logger.debug(
+            {
+              keyIndex,
+              gesture: result.kind,
+              position,
+              activeDeckId: activeDeck.id,
+              buttonId: button?.id ?? null,
+            },
+            "real mode: gesture detected",
+          )
+          if (button === undefined) {
+            logger.warn(
+              { keyIndex, activeDeckId: activeDeck.id },
+              "real mode: keyIndex not mapped to any button on active deck",
+            )
+            return
+          }
+          void opts.runtime.dispatchGesture(
+            `${activeDeck.id}:${button.id}`,
+            result.kind,
+          )
+        },
+      })
+
+      const gestureUnsubscribe = device.onKeyEvent((event) => {
+        logger.debug(
+          { keyIndex: event.keyIndex, type: event.type },
+          "real mode: key event received",
+        )
+        gestureDetector.detect({
+          type: event.type,
+          timestamp: event.timestamp,
+          keyIndex: event.keyIndex,
+        })
+      })
+      void mainDeck
+
+      let frontendUrl =
+        opts.frontendUrl ??
+        `http://127.0.0.1:${opts.port ?? DEFAULT_FRONTEND_PORT}`
+      if (opts.frontendUrl === undefined) {
+        frontendSupervisor = await supervise({
+          label: "frontend vite",
+          kill: killChild,
+          delayScheduleMs: DEFAULT_VITE_RETRY_SCHEDULE_MS,
+          spawn: async () => {
+            const r = await spawnFrontendVite({
+              port: opts.port ?? DEFAULT_FRONTEND_PORT,
+              cwd: resolveFrontendCwd(),
+              pnpmCommand: "pnpm",
+              readyTimeoutMs: 30_000,
+              wsUrl: `ws://127.0.0.1:${opts.bridge.port}`,
+              logger,
+              themeDir: opts.themeDir,
+              configPath: opts.configPath,
+              emulatorMode: false,
+              ...(opts.onChildPid !== undefined
+                ? { onPid: opts.onChildPid }
+                : {}),
+            })
+            frontendUrl = r.url
+            return r.process
+          },
+          onGiveUp: () => opts.onChildCrash?.(),
+          isShuttingDown: () => shuttingDown,
+          logger,
+        })
+      }
+
+      let configUiUrl = `http://127.0.0.1:${DEFAULT_FRONTEND_PORT + 1}`
+      configUiSupervisor = await supervise({
+        label: "config ui vite",
+        kill: killChild,
+        delayScheduleMs: DEFAULT_VITE_RETRY_SCHEDULE_MS,
+        spawn: async () => {
+          const r = await spawnConfigUiVite({
+            port: DEFAULT_FRONTEND_PORT + 1,
+            cwd: resolveConfigUiCwd(),
+            pnpmCommand: "pnpm",
+            readyTimeoutMs: 30_000,
+            logger,
+            wsUrl: `ws://127.0.0.1:${opts.bridge.port}`,
+            frontendUrl,
+            configPath: opts.configPath,
+            emulatorMode: false,
+            onPid: opts.onChildPid,
+          })
+          configUiUrl = r.url
+          return r.process
+        },
+        onGiveUp: () => opts.onChildCrash?.(),
+        isShuttingDown: () => shuttingDown,
+        logger,
+      })
+
+      logger.info({ frontendUrl }, "real mode: frontend URL")
+
+      renderer = new BrowserRenderer({
+        frontendUrl: `${frontendUrl}${frontendUrl.includes("?") ? "&" : "?"}compact=1`,
+        device,
+        logger,
+        ...(opts.intervalMs !== undefined
+          ? { intervalMs: opts.intervalMs }
+          : {}),
+        pubSub: opts.pubSub,
+      })
+      await renderer.start()
+
+      const frontendVitePid = frontendSupervisor?.process.pid ?? 0
+      const configUiPid = configUiSupervisor.process.pid ?? 0
+      const childPids = [frontendVitePid, configUiPid].filter((pid) => pid > 0)
+
+      const state: RuntimeState = {
+        configUiUrl,
+        wsUrl: opts.bridge.url,
+        frontendUrl,
+        lanHost: opts.lanHost ?? "127.0.0.1",
+        addresses: opts.lanAddresses ?? [],
+        emulatorMode: false,
+        remote: false,
+        startedAt: Date.now(),
+        theme: opts.theme.name,
+      }
+      writeRuntimeState(state)
+      logger.info({ frontendUrl }, "real mode: runtime state written")
+
+      return {
+        descriptor,
+        frontendUrl,
+        configUiUrl,
+        wsUrl: opts.bridge.url,
+        childPids,
+        async pushBlackFrame(): Promise<void> {
+          await pushBlackFrame(device, logger)
+        },
+        async pushRawImage(filePath: string): Promise<void> {
+          try {
+            await pushRawImage({
+              imagePath: filePath,
+              device,
+              logger,
+            })
+          } catch (err) {
+            logger.warn(
+              { err: (err as Error).message, filePath },
+              "real: pushRawImage failed (non-fatal)",
+            )
+          }
+        },
+        stop: async (): Promise<void> => {
+          gestureUnsubscribe()
+          try {
+            await renderer?.stop()
+          } finally {
+            try {
+              await device.close()
+            } catch {
+              void 0
+            } finally {
+              this.device = null
+            }
+          }
+          if (frontendSupervisor !== null) {
+            shuttingDown = true
+            // supervisor.stop() SIGTERMs the live child (respawn-aware) and
+            // falls back to SIGKILL. The previous killChild(handle.process)
+            // captured the initial child and leaked the respawned vite.
+            await frontendSupervisor.stop()
+          }
+          await configUiSupervisor?.stop()
+        },
+      }
+    } catch (err) {
+      shuttingDown = true
+      await Promise.allSettled([
+        renderer?.stop() ?? Promise.resolve(),
+        frontendSupervisor?.stop() ?? Promise.resolve(),
+        configUiSupervisor?.stop() ?? Promise.resolve(),
+      ])
+      await pushBlackFrame(device, logger)
+      try {
+        await device.close()
+      } catch {
+        void 0
+      } finally {
+        this.device = null
+      }
+      throw err
+    }
+  }
+}

package/src/outputClient/types.ts

@@ -0,0 +1,83 @@
+import type pino from "pino"
+
+import type { PubSub, Runtime, RuntimeDeck, Store } from "@/deck"
+import type { DeviceDescriptor } from "@/device/registry"
+import type { WsBridge } from "@/render/ws-bridge"
+
+export type OutputKind = "real" | "emulator"
+
+export interface OutputClient {
+  readonly kind: OutputKind
+  validateReady(): Promise<void>
+  listDevices(): Promise<ReadonlyArray<DeviceDescriptor>>
+  selectDevice(
+    devices: ReadonlyArray<DeviceDescriptor>,
+    savedId: string | null,
+    logger: pino.Logger,
+  ): Promise<DeviceDescriptor>
+  storeSelection(descriptor: DeviceDescriptor): Promise<void>
+  init(opts: InitOptions): Promise<OutputHandle>
+}
+
+export interface InitOptions {
+  readonly bridge: WsBridge
+  readonly runtime: Runtime
+  readonly pubSub: PubSub
+  readonly store: Store
+  readonly decks: ReadonlyArray<RuntimeDeck>
+  readonly theme: { name: string; apiVersion: number }
+  readonly themeDir: string
+  readonly configPath?: string
+  readonly logger: pino.Logger
+  readonly frontendUrl?: string
+  readonly port?: number
+  readonly intervalMs?: number
+  /**
+   * --remote: bind WS bridge and Vite to 0.0.0.0 and token-gate the HTTP
+   * servers. The CLI prints a LAN-accessible QR code. Default false.
+   */
+  readonly remote?: boolean
+  /**
+   * --no-autoopen: do not launch the config UI URL in the system browser.
+   * Useful for capture tooling and headless runs. Default false.
+   */
+  readonly noAutoOpen?: boolean
+  /**
+   * The resolved LAN IP to use in the runtime-state.json. Only set when
+   * remote is true or --emulator is set.
+   */
+  readonly lanHost?: string
+  /**
+   * All discovered LAN addresses, used in runtime-state.json so the CLI can
+   * enumerate them in the QR banner.
+   */
+  readonly lanAddresses?: ReadonlyArray<string>
+  /**
+   * Rebuild the runtime deck set for a new device keyCount. The bridge then
+   * re-broadcasts a fresh deck-config so the frontend re-renders into the
+   * correct grid. Optional — emulator-only callers provide this; real
+   * devices have a fixed keyCount and skip the rebuild.
+   */
+  readonly rebuildDecksForKeyCount?: (
+    keyCount: number,
+  ) => ReadonlyArray<RuntimeDeck>
+  readonly onChildPid?: (pid: number) => void
+  /**
+   * Called when a supervised child (frontend/config UI vite) gives up after
+   * exhausting its retry budget. The pipeline uses this to resolve `done` and
+   * trigger the full shutdown sequence. ponytail: kept optional so existing
+   * tests that don't simulate subprocess crashes don't have to wire it.
+   */
+  readonly onChildCrash?: () => void
+}
+
+export interface OutputHandle {
+  readonly descriptor: DeviceDescriptor
+  readonly frontendUrl: string
+  readonly configUiUrl?: string
+  readonly wsUrl?: string
+  readonly childPids: ReadonlyArray<number>
+  pushBlackFrame?(): Promise<void>
+  pushRawImage?(filePath: string): Promise<void>
+  stop(): Promise<void>
+}