@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/cli/commands/emulator-mode.ts

@@ -0,0 +1,289 @@
+import { spawn, type ChildProcess } from "node:child_process"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve as resolvePath } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import type pino from "pino"
+
+import {
+  BUILT_IN_THEMES,
+  buildThemeCssFromManifest,
+  copyThemeAssets,
+  readAndValidateManifest,
+} from "@/themes/loader"
+
+export const DEFAULT_FRONTEND_PORT = 5180
+export const DEFAULT_CONFIG_UI_PORT = 52938
+const DEFAULT_TIMEOUT_MS = 30_000
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\u001b\[[0-9;]*m/g
+// Matches Vite's Local: line — localhost binding
+const LOCAL_URL_REGEX =
+  /(?:Local|➜\s*Local)[^\n]*?(https?):\/\/([0-9.]+|[^:\s]+)(?::(\d+))?/
+// Matches Vite's Network: line — 0.0.0.0 binding
+const NETWORK_URL_REGEX =
+  /(?:Network)[^\n]*?(https?):\/\/([0-9.]+|[^:\s]+)(?::(\d+))?/
+
+export const findWorkspaceRoot = (): string => {
+  const here = dirname(fileURLToPath(import.meta.url))
+  let dir = here
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(resolvePath(dir, "pnpm-workspace.yaml"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return here
+}
+
+export const resolveConfigUiCwd = (override?: string): string => {
+  if (override !== undefined) return override
+  return resolvePath(findWorkspaceRoot(), "packages", "cli", "config-ui")
+}
+
+export const resolveFrontendCwd = (): string =>
+  resolvePath(findWorkspaceRoot(), "packages", "cli", "frontend")
+
+interface ViteSpawnOptions {
+  port: number
+  cwd: string
+  pnpmCommand: string
+  readyTimeoutMs: number
+  logger: pino.Logger
+  wsUrl?: string
+  frontendUrl?: string
+  themeDir?: string
+  configPath?: string
+  host?: string
+  requireToken?: string
+  emulatorMode?: boolean
+  childLabel: "frontend vite" | "config ui vite"
+  exitFatalMessage: string
+  onPid?: (pid: number) => void
+}
+
+const spawnViteAndWaitForReady = (
+  options: ViteSpawnOptions,
+): Promise<{ process: ChildProcess; url: string }> => {
+  const {
+    port,
+    cwd,
+    readyTimeoutMs,
+    logger,
+    wsUrl,
+    frontendUrl,
+    themeDir,
+    configPath,
+    host,
+    requireToken,
+    emulatorMode,
+    childLabel,
+    exitFatalMessage,
+    onPid,
+  } = options
+
+  return new Promise((resolve, reject) => {
+    if (!existsSync(cwd)) {
+      reject(new Error(`${childLabel} workspace not found at ${cwd}`))
+      return
+    }
+    const env: Record<string, string> = { ...process.env, FORCE_COLOR: "0" }
+    if (wsUrl !== undefined) {
+      env["SIRENO_WS_URL"] = wsUrl
+    }
+    if (frontendUrl !== undefined) {
+      env["SIRENO_FRONTEND_URL"] = frontendUrl
+    }
+    if (themeDir !== undefined) {
+      env["SIRENO_THEME_DIR"] = themeDir
+    }
+    if (configPath !== undefined) {
+      env["SIRENO_CONFIG_PATH"] = configPath
+    }
+    if (host !== undefined) {
+      env["SIRENO_VITE_HOST"] = host
+    }
+    if (requireToken !== undefined) {
+      env["SIRENO_REQUIRE_TOKEN"] = requireToken
+    }
+    if (emulatorMode !== undefined) {
+      env["SIRENO_EMULATOR_MODE"] = String(emulatorMode)
+    }
+    const viteBin = findWorkspaceRoot() + "/node_modules/.bin/vite"
+    const viteArgs = [
+      "--config",
+      resolvePath(cwd, "vite.config.ts"),
+      "--port",
+      String(port),
+    ]
+    if (host !== undefined) {
+      viteArgs.push("--host", host)
+    }
+    const child = spawn(viteBin, viteArgs, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+    const spawnedPid = child.pid
+    if (spawnedPid !== undefined) onPid?.(spawnedPid)
+
+    const stdoutChunks: string[] = []
+    const stderrChunks: string[] = []
+    let settled = false
+    let settledUrl: string | null = null
+
+    const collectOutput = (text: string, label: "stdout" | "stderr"): void => {
+      const stripped = text.replace(ANSI_REGEX, "").trimEnd()
+      if (stripped.length === 0) return
+      const formatted = `${label}:\n${stripped}`
+      if (label === "stdout") stdoutChunks.push(formatted)
+      else stderrChunks.push(formatted)
+      if (label === "stderr") logger.warn(formatted)
+      else logger.info(formatted)
+    }
+
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM")
+      const output = stdoutChunks.join("") + stderrChunks.join("")
+      const detail = output.length > 0 ? `\n  output:\n${output}` : ""
+      reject(
+        new Error(
+          `${childLabel} did not become ready within ${readyTimeoutMs}ms${detail}`,
+        ),
+      )
+    }, readyTimeoutMs)
+
+    const onData = (chunk: Buffer): void => {
+      const text = chunk.toString()
+      collectOutput(text, "stdout")
+      const stripped = text.replace(ANSI_REGEX, "")
+      const regex = host === "0.0.0.0" ? NETWORK_URL_REGEX : LOCAL_URL_REGEX
+      const match = stripped.match(regex)
+      if (match && match[1] && match[2] && match[3]) {
+        clearTimeout(timer)
+        const resolvedHost = host ?? "127.0.0.1"
+        const url = `${match[1]}://${resolvedHost}:${match[3]}`
+        if (childLabel === "frontend vite") {
+          setTimeout(() => {
+            settled = true
+            settledUrl = url
+            resolve({ process: child, url })
+          }, 1000)
+        } else {
+          settled = true
+          settledUrl = url
+          resolve({ process: child, url })
+        }
+      }
+    }
+
+    child.stdout?.on("data", onData)
+    child.stderr?.on("data", (chunk: Buffer) => {
+      collectOutput(chunk.toString(), "stderr")
+    })
+    child.on("exit", (code) => {
+      clearTimeout(timer)
+      if (settled) {
+        // ponytail: this logs as a warn, not a fatal. The supervisor (which
+        // owns this child) already decides whether to respawn or give up
+        // and emits its own warn + fatal as appropriate. Logging fatal here
+        // is redundant and clutters `p dev restart`, which legitimately
+        // kills the previous vite as part of the stop→start cycle.
+        logger.warn({ code, url: settledUrl }, exitFatalMessage)
+        return
+      }
+      const output = stdoutChunks.join("") + stderrChunks.join("")
+      const detail = output.length > 0 ? `\n  output:\n${output}` : ""
+      reject(
+        new Error(
+          `${childLabel} exited (code=${code}) before becoming ready${detail}`,
+        ),
+      )
+    })
+    child.on("error", (err) => {
+      clearTimeout(timer)
+      reject(err)
+    })
+  })
+}
+
+export const spawnFrontendVite = (options: {
+  port: number
+  cwd: string
+  pnpmCommand: string
+  readyTimeoutMs: number
+  logger: pino.Logger
+  wsUrl?: string
+  themeDir?: string
+  configPath?: string
+  host?: string
+  requireToken?: string
+  emulatorMode?: boolean
+  onPid?: (pid: number) => void
+}): Promise<{ process: ChildProcess; url: string }> =>
+  spawnViteAndWaitForReady({
+    ...options,
+    emulatorMode: options.emulatorMode ?? false,
+    childLabel: "frontend vite",
+    exitFatalMessage:
+      "frontend vite exited after becoming ready — emulator will show a blank deck until the frontend is restarted",
+  })
+
+export const spawnConfigUiVite = (options: {
+  port: number
+  cwd: string
+  pnpmCommand: string
+  readyTimeoutMs: number
+  logger: pino.Logger
+  wsUrl?: string
+  frontendUrl?: string
+  configPath?: string
+  host?: string
+  requireToken?: string
+  emulatorMode?: boolean
+  onPid?: (pid: number) => void
+}): Promise<{ process: ChildProcess; url: string }> =>
+  spawnViteAndWaitForReady({
+    ...options,
+    emulatorMode: options.emulatorMode ?? true,
+    childLabel: "config ui vite",
+    exitFatalMessage:
+      "config ui vite exited after becoming ready — commands from buttons will no longer be received",
+  })
+
+export const killChild = (child: ChildProcess): Promise<void> =>
+  new Promise<void>((resolve) => {
+    if (child.exitCode !== null) {
+      resolve()
+      return
+    }
+    child.once("exit", () => resolve())
+    child.kill("SIGTERM")
+    setTimeout(() => {
+      if (child.exitCode === null) child.kill("SIGKILL")
+    }, 2_000)
+  })
+
+export const ensureDefaultThemeEnv = (frontendCwd: string): void => {
+  if (
+    process.env["SIRENO_THEME"] !== undefined &&
+    process.env["SIRENO_THEME"].length > 0
+  ) {
+    return
+  }
+  const defaultSpec = BUILT_IN_THEMES[0]
+  if (defaultSpec === undefined) return
+  const manifestPath = resolvePath(defaultSpec.dir, "sirenodeck.json")
+  process.env["SIRENO_THEME"] = JSON.stringify({
+    name: defaultSpec.name,
+    manifestPath,
+    uiOverridesPath: null,
+  })
+  process.env["SIRENO_THEME_DIR"] = frontendCwd
+  const cssDir = join(frontendCwd, ".sirenodeck")
+  if (!existsSync(cssDir)) mkdirSync(cssDir, { recursive: true })
+  const manifest = readAndValidateManifest(manifestPath, defaultSpec.name)
+  const cssContent = buildThemeCssFromManifest(manifest, defaultSpec.dir)
+  writeFileSync(join(cssDir, "theme.css"), cssContent, "utf8")
+  copyThemeAssets(defaultSpec.dir, cssDir)
+}

package/src/cli/commands/install.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve as resolvePath } from "node:path"
+
+import { execa } from "execa"
+import { parse, stringify } from "yaml"
+
+import { resolveConfigPath, type ConfigSource } from "./pipeline/helpers"
+import { loadConfig } from "@/config/loader"
+import {
+  assertPackageManager,
+  detectPackageManager,
+  globalPackageRoot,
+  packageManagerArgs,
+  type PackageManager,
+} from "../package-manager"
+
+export interface InstallOptions {
+  readonly packageName: string
+  readonly config?: string
+  readonly global?: boolean
+  readonly packageManager?: PackageManager
+  readonly homeDir?: string
+  readonly xdgConfigHome?: string
+  readonly configure?: boolean
+}
+
+const configPathFor = (
+  options: InstallOptions,
+): { path: string; source: ConfigSource } =>
+  resolveConfigPath({
+    config: options.config,
+    homeDir: options.homeDir,
+    xdgConfigHome: options.xdgConfigHome,
+    logger: console as never,
+  })
+
+export const installPackage = async (
+  options: InstallOptions,
+): Promise<void> => {
+  const resolved = configPathFor(options)
+  const configPath = resolvePath(resolved.path)
+  const configDir = dirname(configPath)
+  loadConfig({ configPath })
+  const manager = options.packageManager ?? detectPackageManager(configDir)
+  assertPackageManager(manager)
+  await execa(
+    manager,
+    packageManagerArgs(manager, options.packageName, options.global === true),
+    {
+      cwd: options.global === true ? undefined : configDir,
+      stdio: "inherit",
+    },
+  )
+
+  const packageRoot = options.global === true ? undefined : configDir
+  const manifestPath = await resolveManifest(
+    options.packageName,
+    packageRoot,
+    options.global === true
+      ? (globalPackageRoot(manager) ?? undefined)
+      : undefined,
+  )
+  if (manifestPath === null)
+    throw new Error(
+      `Installed package '${options.packageName}' has no valid sirenodeck.json manifest.`,
+    )
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    kind?: string
+  }
+  const raw = parse(readFileSync(configPath, "utf8")) as Record<string, unknown>
+  if (options.configure === false) return
+  if (manifest.kind === "theme") {
+    raw.theme =
+      options.global === true
+        ? { src: options.packageName, global: true }
+        : options.packageName
+  } else if (manifest.kind === "addon") {
+    const addons = Array.isArray(raw.addons) ? raw.addons : []
+    if (
+      !addons.some((entry) =>
+        typeof entry === "string"
+          ? entry === options.packageName
+          : entry !== null &&
+            typeof entry === "object" &&
+            (entry as { src?: string }).src === options.packageName,
+      )
+    ) {
+      addons.push(
+        options.global === true
+          ? { src: options.packageName, global: true }
+          : options.packageName,
+      )
+    }
+    raw.addons = addons
+  } else {
+    throw new Error(
+      `Package '${options.packageName}' is neither an addon nor a theme.`,
+    )
+  }
+  writeFileSync(configPath, stringify(raw), "utf8")
+}
+
+const resolveManifest = async (
+  name: string,
+  projectDir?: string,
+  globalRoot?: string,
+): Promise<string | null> => {
+  const packageName = name.startsWith("@")
+    ? name.slice(
+        0,
+        name.indexOf("@", 1) > 0 ? name.indexOf("@", 1) : name.length,
+      )
+    : name.split("@")[0]!
+  if (globalRoot !== undefined) {
+    const path = join(globalRoot, packageName, "sirenodeck.json")
+    return existsSync(path) ? path : null
+  }
+  const { createRequire } = await import("node:module")
+  const require = createRequire(
+    resolvePath(projectDir ?? process.cwd(), "package.json"),
+  )
+  try {
+    const packageJson = require.resolve(`${packageName}/package.json`)
+    return resolvePath(dirname(packageJson), "sirenodeck.json")
+  } catch {
+    return null
+  }
+}

package/src/cli/commands/logs.ts

@@ -0,0 +1,74 @@
+import { existsSync } from "node:fs"
+import type { CommandModule } from "yargs"
+
+import type { Logger } from "pino"
+
+import { resolveDaemonPaths } from "@/util/daemon"
+import { tailLogs } from "@/util/log-tail"
+
+export interface LogsOptions {
+  readonly follow?: boolean
+  readonly lines?: number
+  readonly timestamps?: boolean
+  readonly logger: Logger
+}
+
+export const logs = async (options: LogsOptions): Promise<void> => {
+  const { logger, follow = true, lines = 50, timestamps = true } = options
+  const paths = resolveDaemonPaths()
+  const logPath = `${paths.runtimeDir}/service.log`
+
+  if (!existsSync(logPath)) {
+    logger.error(
+      { logPath },
+      "logs: file does not exist (is the daemon running?)",
+    )
+    process.exitCode = 1
+    return
+  }
+
+  logger.info({ logPath, follow, lines }, "logs: tailing")
+  await tailLogs({ logPath, follow, lines, timestamps })
+}
+
+interface LogsArgs {
+  follow?: boolean
+  lines?: number
+  timestamps?: boolean
+}
+
+export const logsCommand: CommandModule<object, LogsArgs> = {
+  command: "logs",
+  aliases: ["log"],
+  describe: "Tail the daemon service log (Ctrl+C to exit)",
+  builder: (yargs) =>
+    yargs
+      .option("follow", {
+        alias: "f",
+        type: "boolean",
+        default: true,
+        description: "Follow log output (default: true)",
+      })
+      .option("lines", {
+        alias: "n",
+        type: "number",
+        default: 50,
+        description: "Initial lines to print when following",
+      })
+      .option("timestamps", {
+        alias: "t",
+        type: "boolean",
+        default: true,
+        description: "Show when each entry was logged",
+      }),
+  handler: async (argv) => {
+    const { createLogger } = await import("@/util/logger")
+    const logger = createLogger({ verbose: false })
+    await logs({
+      logger,
+      follow: argv.follow !== false,
+      timestamps: argv.timestamps !== false,
+      ...(argv.lines !== undefined ? { lines: argv.lines } : {}),
+    })
+  },
+}

package/src/cli/commands/network-bind.ts

@@ -0,0 +1,111 @@
+import { networkInterfaces, type NetworkInterfaceInfo } from "node:os"
+
+export interface LanAddress {
+  readonly address: string
+  readonly interfaceName: string
+}
+
+export interface NetworkInterfacesMap {
+  readonly [interfaceName: string]:
+    | ReadonlyArray<NetworkInterfaceInfo>
+    | undefined
+}
+
+export interface SelectLanAddressesOptions {
+  readonly interfaces?: NetworkInterfacesMap
+  readonly networkInterfaces?: typeof networkInterfaces
+}
+
+export const TUNNEL_INTERFACE_PATTERN = /^(utun|tun|tap|vpn|tailscale|wg)/i
+export const PHYSICAL_ETHERNET_PATTERN = /^en/i
+export const PHYSICAL_LINUX_ETHERNET_PATTERN = /^eth/i
+export const NON_TUNNEL_WIRELESS_PATTERN = /^wlan/i
+
+const LAN_INTERFACE_PRIORITY: ReadonlyArray<{
+  readonly pattern: RegExp
+  readonly score: number
+}> = [
+  { pattern: PHYSICAL_ETHERNET_PATTERN, score: 0 },
+  { pattern: PHYSICAL_LINUX_ETHERNET_PATTERN, score: 0 },
+  { pattern: NON_TUNNEL_WIRELESS_PATTERN, score: 1 },
+  { pattern: TUNNEL_INTERFACE_PATTERN, score: 3 },
+]
+
+const computePriority = (interfaceName: string): number => {
+  for (const { pattern, score } of LAN_INTERFACE_PRIORITY) {
+    if (pattern.test(interfaceName)) return score
+  }
+  return 2
+}
+
+const isValidIPv4LanAddress = (info: NetworkInterfaceInfo): boolean => {
+  if (info.family !== "IPv4") return false
+  if (info.internal) return false
+  if (info.address.startsWith("127.")) return false
+  if (info.address.startsWith("169.254.")) return false
+  return true
+}
+
+export const selectLanAddresses = (
+  options: SelectLanAddressesOptions = {},
+): ReadonlyArray<LanAddress> => {
+  const fetchInterfaces = options.networkInterfaces ?? networkInterfaces
+  const interfaces =
+    options.interfaces ?? (fetchInterfaces() as unknown as NetworkInterfacesMap)
+
+  const candidates: LanAddress[] = []
+  for (const interfaceName of Object.keys(interfaces)) {
+    const list = interfaces[interfaceName]
+    if (list === undefined) continue
+    const first = list[0]
+    if (first === undefined) continue
+    if (!isValidIPv4LanAddress(first)) continue
+    candidates.push({ address: first.address, interfaceName })
+  }
+
+  return candidates.sort(
+    (a, b) =>
+      computePriority(a.interfaceName) - computePriority(b.interfaceName),
+  )
+}
+
+export interface PrintConfigUiBannerOptions {
+  readonly configUiUrlFn: (lanAddress: string) => string
+  readonly lanAddresses: ReadonlyArray<LanAddress>
+  readonly securityWarning: string
+  readonly output: (text: string) => void
+  readonly qrGenerate?: (text: string) => string | Promise<string>
+}
+
+const formatInterfaceLabel = (name: string): string => name
+
+export async function printConfigUiBanner(
+  options: PrintConfigUiBannerOptions,
+): Promise<void> {
+  const { configUiUrlFn, lanAddresses, securityWarning, output, qrGenerate } =
+    options
+
+  if (lanAddresses.length === 0) {
+    output("\n  Config UI:  http://127.0.0.1:52938\n")
+    output(
+      "\x1b[33m  warning: no LAN interfaces detected — QR may not reach your phone.\x1b[0m\n\n",
+    )
+    output(`\x1b[33m  ${securityWarning}\x1b[0m\n\n`)
+    return
+  }
+
+  output("\n  Config UI (LAN):\n")
+  for (const entry of lanAddresses) {
+    const url = configUiUrlFn(entry.address)
+    if (qrGenerate !== undefined) {
+      output("\n")
+      const qr = await qrGenerate(url)
+      output(qr)
+      output(`  ${url}  ← ${formatInterfaceLabel(entry.interfaceName)}\n`)
+    } else {
+      output(`  ${url}  ← ${formatInterfaceLabel(entry.interfaceName)}\n`)
+    }
+  }
+  output("\n")
+  output(`\x1b[33m  ${securityWarning}\x1b[0m\n\n`)
+}

package/src/cli/commands/pipeline/helpers.ts

@@ -0,0 +1,75 @@
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { resolve as resolvePath } from "node:path"
+
+import { findConfigPath, XDG_CONFIG_SUBDIR } from "@/config/discovery"
+import { getOriginalCwd, resolveUserPath } from "@/cli/cwd"
+
+import type { RunOptions } from "../run"
+
+export const resolveXdgConfigHome = (options: RunOptions): string =>
+  options.xdgConfigHome ??
+  process.env["XDG_CONFIG_HOME"] ??
+  `${options.homeDir ?? homedir()}/.config`
+
+export const resolveXdgConfigPath = (options: RunOptions): string =>
+  resolvePath(resolveXdgConfigHome(options), XDG_CONFIG_SUBDIR, "config.yml")
+
+export const resolveRunFolderConfigPath = (): string =>
+  resolvePath(getOriginalCwd(), "config.yml")
+
+export type ConfigSource = "cli" | "xdg" | "run-folder"
+
+export interface ResolveConfigPathResult {
+  readonly path: string
+  readonly source: ConfigSource
+}
+
+// ponytail: precedence is cli arg → ~/.config/sirenodeck/config.yml →
+// ./config.yml (run folder). The cli arg is validated eagerly so the
+// failure mode is obvious at startup; the other two come from
+// findConfigPath which walks XDG first, then the run folder.
+export const resolveConfigPath = (
+  options: RunOptions,
+): ResolveConfigPathResult => {
+  if (options.config !== undefined) {
+    const explicit = resolveUserPath(options.config)
+    if (!existsSync(explicit)) {
+      throw new Error(
+        `Config file not found: ${explicit}\n` +
+          `  Fix: pass a valid --config path, or remove --config to let sirenodeck auto-discover config.yml.`,
+      )
+    }
+    return { path: explicit, source: "cli" }
+  }
+  const cwd = getOriginalCwd()
+  const home = options.homeDir ?? homedir()
+  const xdgPath = resolveXdgConfigPath(options)
+  if (existsSync(xdgPath)) {
+    return { path: xdgPath, source: "xdg" }
+  }
+  const cwdPath = resolvePath(cwd, "config.yml")
+  if (existsSync(cwdPath)) {
+    return { path: cwdPath, source: "run-folder" }
+  }
+  // ponytail: re-use findConfigPath to keep the search algorithm in one
+  // place — this branch is hit when neither the XDG nor the cwd file
+  // exists but a discovery-side option (envVar) is set or the user has
+  // a non-default xdgConfigHome. The result is the same XDG-first lookup.
+  const found = findConfigPath({
+    cwd,
+    homeDir: home,
+    ...(options.xdgConfigHome !== undefined
+      ? { xdgConfigHome: options.xdgConfigHome }
+      : {}),
+  })
+  if (found === null) {
+    throw new Error(
+      `Could not find config.yml.\n` +
+        `  Fix: pass --config <path>, create ./config.yml in the current directory, or create ~/.config/sirenodeck/config.yml.\n` +
+        `  Looked in: ${xdgPath} and ${cwdPath}.`,
+    )
+  }
+  const source: ConfigSource = found === xdgPath ? "xdg" : "run-folder"
+  return { path: found, source }
+}

package/src/cli/commands/pipeline/preflight.ts

@@ -0,0 +1,20 @@
+import { selectOutputClient } from "@/outputClient"
+import { resolveXdgConfigHome } from "./helpers"
+import { validateAndLoadConfig, type RunOptions } from "../run"
+
+export const preflight = async (options: RunOptions): Promise<void> => {
+  await validateAndLoadConfig(options)
+  const outputClient = selectOutputClient({
+    emulator: options.emulator === true,
+    xdgConfigHome: resolveXdgConfigHome(options),
+  })
+  if (outputClient.kind === "real") {
+    const devices = await outputClient.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.",
+      )
+    }
+  }
+  await outputClient.validateReady()
+}