@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/render/ws-bridge.ts

@@ -0,0 +1,315 @@
+import type { Server as HttpServer } from "node:http"
+import { WebSocketServer, type WebSocket } from "ws"
+import type pino from "pino"
+
+import type { DeviceDescriptor } from "@/device/registry"
+import { createLogger } from "@/util/logger"
+import type { DeckTreeMessage } from "@/api/protocol-internal"
+import {
+  PROTOCOL_VERSION,
+  helloAckMessageSchema,
+  helloMessageSchema,
+  helloMessageStrictSchema,
+  wsMessageSchema,
+  type WsMessage,
+} from "./protocol"
+import type { AddonsInventoryMessage } from "@/api/protocol-internal"
+
+const HANDSHAKE_TIMEOUT_MS = 5000
+const TOKEN_MISMATCH_CLOSE_CODE = 4001
+
+export interface WsBridgeOptions {
+  port?: number
+  /** Bind address for the WebSocket server. Defaults to "127.0.0.1". */
+  host?: string
+  /**
+   * Advertised host for the URL returned by the bridge. Use when the server
+   * binds to 0.0.0.0 but clients must connect via a specific LAN/VPN IP.
+   */
+  lanHost?: string
+  expectedToken: string
+  handshakeTimeoutMs?: number
+  activeTheme?: { name: string; version?: number }
+  logger?: pino.Logger
+  // ponytail: when provided, sent as a follow-up to hello-ack so the
+  // emulator's Addons tab can render without needing a separate HTTP
+  // fetch (which doesn't exist in --emulator mode).
+  addonInventory?: AddonsInventoryMessage["addons"]
+}
+
+export interface WsBridge {
+  readonly port: number
+  readonly url: string
+  setDevice(device: DeviceDescriptor): void
+  // ponytail: late-bound so callers can ship addon inventory after
+  // external addons register (e.g. buildExternalScannedAddons runs
+  // after the bridge starts in runPipeline). Subsequent connects get
+  // the new value; already-connected clients aren't resent (would be
+  // redundant — the page is mounting fresh anyway).
+  setAddonInventory(inventory: AddonsInventoryMessage["addons"]): void
+  setActiveTheme?(theme: { name: string; version?: number }): void
+  setDeckTree(tree: Omit<DeckTreeMessage, "type">): void
+  broadcast(message: WsMessage): void
+  registerCacheablePoller(
+    channel: string,
+    pollFn: () => unknown | Promise<unknown>,
+  ): void
+  onMessage(handler: (message: WsMessage, socket: WebSocket) => void): void
+  onConnection(handler: (socket: WebSocket) => void): void
+  close(): Promise<void>
+}
+
+export const startWsBridge = (options: WsBridgeOptions): Promise<WsBridge> => {
+  const {
+    port = 0,
+    host = "127.0.0.1",
+    lanHost,
+    expectedToken,
+    handshakeTimeoutMs = HANDSHAKE_TIMEOUT_MS,
+    activeTheme,
+    logger = createLogger({ level: "warn", component: "ws-bridge" }),
+  } = options
+  let { addonInventory } = options
+  let currentTheme = activeTheme
+  let deckTree: Omit<DeckTreeMessage, "type"> | undefined
+
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer({ port, host })
+
+    const messageHandlers: Array<
+      (message: WsMessage, socket: WebSocket) => void
+    > = []
+    const connectionHandlers: Array<(socket: WebSocket) => void> = []
+    const lastChannels: Record<string, unknown> = {}
+    const cacheablePollers = new Map<string, () => unknown | Promise<unknown>>()
+    const pendingChannelSubs = new Map<string, Set<WebSocket>>()
+    let currentDevice: DeviceDescriptor | null = null
+
+    const sendToSocket = (socket: WebSocket, message: WsMessage): void => {
+      if (socket.readyState === socket.OPEN) {
+        socket.send(JSON.stringify(message))
+      }
+    }
+
+    wss.on("connection", (socket: WebSocket) => {
+      let handshakeDone = false
+
+      const handshakeTimer = setTimeout(() => {
+        if (!handshakeDone) {
+          logger.warn(
+            {
+              peer:
+                (
+                  socket as unknown as {
+                    _socket: { remoteAddress?: string }
+                  }
+                )._socket.remoteAddress ?? "unknown",
+            },
+            "ws handshake timed out",
+          )
+          socket.close(4000, "handshake timeout")
+        }
+      }, handshakeTimeoutMs)
+
+      socket.on("message", (raw) => {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(raw.toString())
+        } catch (err) {
+          logger.warn(
+            { reason: err instanceof Error ? err.message : String(err) },
+            "ws message: invalid json",
+          )
+          clearTimeout(handshakeTimer)
+          socket.close(4002, "invalid json")
+          return
+        }
+        const result = wsMessageSchema.safeParse(parsed)
+        if (!result.success) {
+          logger.warn(
+            { issues: result.error.issues },
+            "ws message: schema mismatch",
+          )
+          clearTimeout(handshakeTimer)
+          socket.close(4003, "invalid message")
+          return
+        }
+        const message = result.data
+        if (!handshakeDone) {
+          if (message.type !== "hello") {
+            clearTimeout(handshakeTimer)
+            socket.close(4004, "expected hello")
+            return
+          }
+          const helloSchema = expectedToken
+            ? helloMessageStrictSchema
+            : helloMessageSchema
+          const helloResult = helloSchema.safeParse(message)
+          if (!helloResult.success) {
+            clearTimeout(handshakeTimer)
+            socket.close(4001, "invalid hello")
+            return
+          }
+          if (expectedToken && helloResult.data.token !== expectedToken) {
+            clearTimeout(handshakeTimer)
+            socket.close(TOKEN_MISMATCH_CLOSE_CODE, "token mismatch")
+            return
+          }
+          handshakeDone = true
+          clearTimeout(handshakeTimer)
+          const ack = helloAckMessageSchema.parse({
+            type: "hello-ack",
+            version: PROTOCOL_VERSION,
+            ...(currentDevice !== null ? { device: currentDevice } : {}),
+            config:
+              currentTheme !== undefined ? { theme: currentTheme.name } : {},
+          })
+          socket.send(JSON.stringify(ack))
+          if (currentDevice !== null) {
+            sendToSocket(socket, { type: "device-info", device: currentDevice })
+          }
+          if (addonInventory !== undefined) {
+            sendToSocket(socket, {
+              type: "addons-inventory",
+              addons: addonInventory,
+            })
+          }
+          if (deckTree !== undefined) {
+            sendToSocket(socket, { type: "deck-tree", ...deckTree })
+          }
+          for (const handler of connectionHandlers) handler(socket)
+          return
+        }
+
+        if (message.type === "subscribe-channels") {
+          const cached: Record<string, unknown> = {}
+          const uncached: string[] = []
+          for (const channel of message.channels) {
+            if (channel in lastChannels) {
+              cached[channel] = lastChannels[channel]
+            } else if (cacheablePollers.has(channel)) {
+              uncached.push(channel)
+            } else {
+              let waiting = pendingChannelSubs.get(channel)
+              if (waiting === undefined) {
+                waiting = new Set()
+                pendingChannelSubs.set(channel, waiting)
+              }
+              waiting.add(socket)
+            }
+          }
+          if (Object.keys(cached).length > 0) {
+            sendToSocket(socket, { type: "state", channels: cached })
+          }
+          for (const channel of uncached) {
+            const pollFn = cacheablePollers.get(channel)
+            if (pollFn === undefined) continue
+            void Promise.resolve(pollFn())
+              .then((value) => {
+                const msg: WsMessage = {
+                  type: "state",
+                  channels: { [channel]: value },
+                }
+                const payload = JSON.stringify(msg)
+                for (const client of wss.clients) {
+                  if (client.readyState === client.OPEN) client.send(payload)
+                }
+              })
+              .catch(() => {
+                // poll on demand failed — ignore, next interval will retry
+              })
+          }
+          return
+        }
+
+        for (const handler of messageHandlers) handler(message, socket)
+      })
+
+      socket.on("error", () => {
+        clearTimeout(handshakeTimer)
+      })
+
+      socket.on("close", () => {
+        for (const subs of pendingChannelSubs.values()) {
+          subs.delete(socket)
+        }
+      })
+    })
+
+    wss.on("listening", () => {
+      const addr = wss.address()
+      if (addr === null || typeof addr === "string") {
+        reject(new Error("ws bridge: invalid address"))
+        return
+      }
+      const port = addr.port
+      const urlHost = lanHost ?? host
+      const url = `ws://${urlHost}:${port}`
+      const bridge: WsBridge = {
+        port,
+        url,
+        setDevice: (device) => {
+          currentDevice = device
+          const msg: WsMessage = { type: "device-info", device }
+          const payload = JSON.stringify(msg)
+          for (const client of wss.clients) {
+            if (client.readyState === client.OPEN) client.send(payload)
+          }
+        },
+        setAddonInventory: (inventory) => {
+          addonInventory = inventory
+        },
+        setActiveTheme: (theme) => {
+          currentTheme = theme
+        },
+        setDeckTree: (tree) => {
+          deckTree = tree
+        },
+        broadcast: (message) => {
+          if (message.type === "state") {
+            Object.assign(lastChannels, message.channels)
+          }
+          const payload = JSON.stringify(message)
+          for (const client of wss.clients) {
+            if (client.readyState === client.OPEN) client.send(payload)
+          }
+        },
+        registerCacheablePoller: (channel, pollFn) => {
+          cacheablePollers.set(channel, pollFn)
+          const waiting = pendingChannelSubs.get(channel)
+          if (waiting !== undefined) {
+            pendingChannelSubs.delete(channel)
+            // ponytail: poll once and broadcast to every waiting socket. The
+            // legacy loop fired the probe N times for N sockets — the cache
+            // exists to avoid that exact amplification.
+            void Promise.resolve(pollFn())
+              .then((value) => {
+                const msg: WsMessage = {
+                  type: "state",
+                  channels: { [channel]: value },
+                }
+                for (const sock of waiting) sendToSocket(sock, msg)
+                lastChannels[channel] = value
+              })
+              .catch(() => {
+                // poll on demand failed — ignore, next interval will retry
+              })
+          }
+        },
+        onMessage: (handler) => messageHandlers.push(handler),
+        onConnection: (handler) => connectionHandlers.push(handler),
+        close: () =>
+          new Promise<void>((res) => {
+            pendingChannelSubs.clear()
+            for (const client of wss.clients) client.close(1000)
+            wss.close(() => res())
+          }),
+      }
+      resolve(bridge)
+    })
+
+    wss.on("error", (err) => reject(err))
+  })
+}
+
+export type WsBridgeHttpServer = HttpServer

package/src/system/device-selection.ts

@@ -0,0 +1,80 @@
+import { select as clackSelect } from "@/cli/prompt"
+import type pino from "pino"
+
+import type { DeviceDescriptor } from "@/device/registry"
+import type { DeviceConfig } from "@/util/device-config"
+
+export class NoStreamDeckFoundError extends Error {
+  constructor() {
+    super("No Stream Deck devices found")
+    this.name = "NoStreamDeckFoundError"
+  }
+}
+
+export interface SelectDeviceResult {
+  readonly descriptor: DeviceDescriptor
+  readonly savedButStale: boolean
+}
+
+export interface SelectDeviceOptions {
+  readonly devices: ReadonlyArray<DeviceDescriptor>
+  readonly current?: DeviceConfig | null
+  readonly logger: pino.Logger
+}
+
+const formatChoice = (
+  descriptor: DeviceDescriptor,
+  hint: string | undefined,
+): { label: string; value: string; hint?: string } => ({
+  label: descriptor.label,
+  value: descriptor.id,
+  ...(hint !== undefined ? { hint } : {}),
+})
+
+export const selectDevice = async (
+  options: SelectDeviceOptions,
+): Promise<SelectDeviceResult> => {
+  if (options.devices.length === 0) {
+    throw new NoStreamDeckFoundError()
+  }
+  if (options.devices.length === 1) {
+    return { descriptor: options.devices[0]!, savedButStale: false }
+  }
+
+  const currentMatches = options.current
+    ? options.devices.find((d) => d.id === options.current!.serial) !==
+      undefined
+    : false
+  if (options.current && currentMatches) {
+    const match = options.devices.find((d) => d.id === options.current!.serial)!
+    options.logger.debug({ id: match.id }, "using saved device selection")
+    return { descriptor: match, savedButStale: false }
+  }
+
+  const savedButStale =
+    options.current !== null && options.current !== undefined && !currentMatches
+  const choices = options.devices.map((d) =>
+    formatChoice(
+      d,
+      savedButStale && d.id === options.current!.serial
+        ? "(saved, disconnected)"
+        : undefined,
+    ),
+  )
+  choices.sort((a, b) => {
+    const aStale = a.hint === "(saved, disconnected)"
+    const bStale = b.hint === "(saved, disconnected)"
+    if (aStale && !bStale) return -1
+    if (bStale && !aStale) return 1
+    return 0
+  })
+
+  const selected = await clackSelect({
+    message: "Select a Stream Deck:",
+    options: choices,
+  })
+
+  const descriptor = options.devices.find((d) => d.id === selected)
+  if (!descriptor) throw new NoStreamDeckFoundError()
+  return { descriptor, savedButStale }
+}

package/src/system/glob-match.ts

@@ -0,0 +1,74 @@
+import type { ActiveAppSnapshot } from "@/system/providers/active-app"
+
+const escapeRegex = (raw: string): string =>
+  raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+const hasGlobMeta = (pattern: string): boolean => /[*?\\|]/.test(pattern)
+
+const globToRegex = (pattern: string): RegExp => {
+  let source = ""
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i]
+    if (c === "*") source += ".*"
+    else if (c === "?") source += "."
+    else if (c === "\\" && i + 1 < pattern.length) {
+      source += escapeRegex(pattern[i + 1] ?? "")
+      i += 1
+    } else {
+      source += escapeRegex(c ?? "")
+    }
+  }
+  return new RegExp(`^(?:${source})$`, "i")
+}
+
+const compileOne = (raw: string): RegExp => {
+  const trimmed = raw.trim()
+  if (trimmed.length === 0) return /^.*/i
+  if (trimmed.includes("|")) {
+    const branches = trimmed.split("|").map((s) => {
+      const t = s.trim()
+      if (t.length === 0) return ".*"
+      if (!hasGlobMeta(t)) return escapeRegex(t)
+      return globToRegex(t).source
+    })
+    return new RegExp(`^(?:${branches.join("|")})$`, "i")
+  }
+  if (!hasGlobMeta(trimmed)) {
+    return new RegExp(escapeRegex(trimmed), "i")
+  }
+  return globToRegex(trimmed)
+}
+
+export const matchesPattern = (name: string, pattern: string): boolean => {
+  if (name.length === 0) return false
+  return compileOne(pattern).test(name)
+}
+
+export interface DeckMatcherFields {
+  processNames?: ReadonlyArray<string>
+  windowNames?: ReadonlyArray<string>
+}
+
+const matchGroup = (
+  compiled: ReadonlyArray<RegExp>,
+  value: string,
+): boolean => {
+  if (compiled.length === 0) return true
+  for (const re of compiled) {
+    if (re.test(value)) return true
+  }
+  return false
+}
+
+export const compileDeckMatcher = (
+  fields: DeckMatcherFields,
+): ((snapshot: ActiveAppSnapshot) => boolean) => {
+  const processCompiled = (fields.processNames ?? []).map(compileOne)
+  const windowCompiled = (fields.windowNames ?? []).map(compileOne)
+  if (processCompiled.length === 0 && windowCompiled.length === 0) {
+    return () => false
+  }
+  return (snapshot: ActiveAppSnapshot): boolean =>
+    matchGroup(processCompiled, snapshot.name) &&
+    matchGroup(windowCompiled, snapshot.windowTitle ?? "")
+}

package/src/system/providers/active-app/darwin.ts

@@ -0,0 +1,117 @@
+import type pino from "pino"
+
+import type { ActiveAppProvider, ActiveAppSnapshot } from "../active-app"
+import type { CommandExecutor } from "../shared"
+
+export interface DarwinActiveAppDeps {
+  readonly executor: CommandExecutor
+  readonly logger: pino.Logger
+  readonly pollIntervalMs?: number
+}
+
+const DEFAULT_POLL_MS = 1_000
+
+// ponytail: the old one-liner asked for `{name, name of window 1 of ..., unix
+// id of ...}` and had three separate faults. A bare `name` inside `tell
+// application "System Events"` resolves to System Events ITSELF, so the app
+// name was always "System Events". The result was then split on ",", so any
+// window title containing a comma shifted every field. And reading `window 1`
+// needs an Accessibility (TCC) grant — without it the whole script errors out,
+// losing the app name and pid too, even though neither needs that permission.
+//
+// Now: one script, newline-delimited, with the window title in its own `try`
+// so a missing Accessibility grant (or a window-less app) costs only the title.
+// Name and pid are lines 1 and 2; everything after is the title, so a title
+// containing the delimiter can't corrupt the fields that matter.
+const APPLE_SCRIPT_GET_ACTIVE = `tell application "System Events"
+  set p to first process whose frontmost is true
+  set n to name of p
+  set u to unix id of p
+  try
+    set w to name of window 1 of p
+  on error
+    set w to ""
+  end try
+  return n & linefeed & u & linefeed & w
+end tell`
+
+const parseOutput = (
+  raw: string,
+): { name: string; title: string; pid: number | null } | null => {
+  if (raw.trim().length === 0) return null
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n")
+  const name = (lines[0] ?? "").trim()
+  if (name.length === 0) return null
+  const pid = Number.parseInt((lines[1] ?? "").trim(), 10)
+  const title = lines.slice(2).join("\n").trim()
+  return { name, title, pid: Number.isFinite(pid) ? pid : null }
+}
+
+export const createDarwinActiveAppProvider = async (
+  deps: DarwinActiveAppDeps,
+): Promise<ActiveAppProvider> => {
+  const pollMs = deps.pollIntervalMs ?? DEFAULT_POLL_MS
+  const subscribers = new Set<(s: ActiveAppSnapshot | null) => void>()
+  let last: ActiveAppSnapshot | null = null
+  let stopped = false
+
+  const snapshot = async (): Promise<ActiveAppSnapshot | null> => {
+    try {
+      const result = await deps.executor.run(
+        "osascript",
+        ["-e", APPLE_SCRIPT_GET_ACTIVE],
+        {
+          timeoutMs: 3_000,
+        },
+      )
+      if (result.exitCode !== 0) return last
+      const parsed = parseOutput(result.stdout)
+      if (parsed === null) return last
+      return {
+        name: parsed.name,
+        windowTitle: parsed.title || null,
+        processId: parsed.pid,
+      }
+    } catch (err) {
+      deps.logger.warn({ err }, "active-app: osascript failed")
+      return last
+    }
+  }
+
+  let interval: ReturnType<typeof setInterval> | null = null
+  interval = setInterval(() => {
+    if (stopped) return
+    void snapshot().then((s) => {
+      if (stopped) return
+      const same =
+        last !== null &&
+        s !== null &&
+        last.name === s.name &&
+        last.windowTitle === s.windowTitle &&
+        last.processId === s.processId
+      if (!same) {
+        last = s
+        for (const h of subscribers) h(s)
+      }
+    })
+  }, pollMs)
+
+  return {
+    async getActive() {
+      return snapshot()
+    },
+    subscribe(handler) {
+      subscribers.add(handler)
+      return () => {
+        subscribers.delete(handler)
+      }
+    },
+    async stop() {
+      stopped = true
+      if (interval !== null) {
+        clearInterval(interval)
+        interval = null
+      }
+    },
+  }
+}