@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/cli/package-manager.ts

@@ -0,0 +1,175 @@
+import { execFileSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+export type PackageManager = "pnpm" | "npm" | "yarn"
+
+const managers: PackageManager[] = ["pnpm", "npm", "yarn"]
+
+/**
+ * ponytail: every probe in this module runs a package manager we did not write,
+ * found on `PATH`, purely to ask it a question. A broken one must not be able to
+ * take the daemon down with it, so the probes are bounded on three axes:
+ *
+ * - `timeout` + `killSignal`, because a hung manager used to hang startup
+ *   forever with no output at all. A corrupt pnpm shim that re-`exec`s itself
+ *   made `pnpm root --global` never return; `execFileSync` has no timeout by
+ *   default, so the daemon simply stopped there, before it bound a port or lit
+ *   a single key. SIGTERM is not enough — a manager that is busy spawning does
+ *   not get round to handling it — so the deadline is enforced with SIGKILL.
+ * - `maxBuffer`, so a manager that writes without end fails the probe instead
+ *   of growing the daemon's heap.
+ * - no network. These probes only ask "are you there?" and "where do you keep
+ *   global packages?". Corepack reads that as licence to go and fetch the
+ *   manager first — probing for `yarn` downloaded Yarn 1.22.22 on a machine
+ *   that had never asked for it. A read-only question installs nothing.
+ */
+const DEFAULT_PROBE_TIMEOUT_MS = 10_000
+const PROBE_KILL_SIGNAL = "SIGKILL"
+
+/**
+ * `SIRENO_PACKAGE_MANAGER_TIMEOUT_MS` raises the deadline for a machine where a
+ * cold Corepack legitimately needs longer than ten seconds to answer, and lets
+ * the tests use a deadline they can wait for. Anything unparseable or
+ * non-positive falls back to the default rather than disabling the bound.
+ */
+export const packageManagerProbeTimeoutMs = (): number => {
+  const raw = process.env["SIRENO_PACKAGE_MANAGER_TIMEOUT_MS"]
+  const parsed = raw === undefined ? Number.NaN : Number.parseInt(raw, 10)
+  return Number.isFinite(parsed) && parsed > 0
+    ? parsed
+    : DEFAULT_PROBE_TIMEOUT_MS
+}
+
+const probeEnv = (): NodeJS.ProcessEnv => ({
+  ...process.env,
+  COREPACK_ENABLE_NETWORK: "0",
+  COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+})
+
+const probeOptions = () =>
+  ({
+    timeout: packageManagerProbeTimeoutMs(),
+    killSignal: PROBE_KILL_SIGNAL,
+    maxBuffer: 1024 * 1024,
+  }) as const
+
+const hasCommand = (command: string): boolean => {
+  try {
+    execFileSync(command, ["--version"], {
+      ...probeOptions(),
+      stdio: "ignore",
+      env: probeEnv(),
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const detectPackageManager = (projectDir: string): PackageManager => {
+  const lockfile = managers.find((manager) =>
+    existsSync(
+      join(
+        projectDir,
+        manager === "pnpm"
+          ? "pnpm-lock.yaml"
+          : manager === "npm"
+            ? "package-lock.json"
+            : "yarn.lock",
+      ),
+    ),
+  )
+  if (lockfile !== undefined && hasCommand(lockfile)) return lockfile
+  const available = managers.find(hasCommand)
+  if (available === undefined)
+    throw new Error(
+      "Install pnpm, npm, or yarn before installing an addon or theme.",
+    )
+  return available
+}
+
+export const assertPackageManager = (manager: PackageManager): void => {
+  if (!hasCommand(manager))
+    throw new Error(`Package manager '${manager}' is not installed.`)
+}
+
+export const packageManagerArgs = (
+  manager: PackageManager,
+  specifier: string,
+  global: boolean,
+): string[] => {
+  if (global) {
+    return manager === "pnpm"
+      ? ["add", "--global", specifier]
+      : manager === "npm"
+        ? ["install", "--global", specifier]
+        : ["global", "add", specifier]
+  }
+  return manager === "pnpm"
+    ? ["add", "--save-exact", specifier]
+    : manager === "npm"
+      ? ["install", "--save-exact", specifier]
+      : ["add", "--exact", specifier]
+}
+
+type RootProbe =
+  | { readonly kind: "root"; readonly root: string }
+  | { readonly kind: "unavailable" }
+  | { readonly kind: "timeout" }
+
+/**
+ * Only the deadline is worth reporting. A manager that is absent, that exits
+ * non-zero, or that declines the question ("the global bin directory is not in
+ * PATH", or Corepack refusing a manager this project does not pin) has answered
+ * — it simply has no root to offer, which is the ordinary case on a machine
+ * that uses one of the three. Warning about those would fire on every start.
+ *
+ * Being killed at the deadline is different: the manager never answered at all,
+ * and before the deadline existed that is precisely what hung the daemon.
+ */
+const probeRoot = (manager: PackageManager): RootProbe => {
+  try {
+    const root = execFileSync(manager, ["root", "--global"], {
+      ...probeOptions(),
+      encoding: "utf8",
+      env: probeEnv(),
+    }).trim()
+    return root.length > 0 ? { kind: "root", root } : { kind: "unavailable" }
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException & { signal?: string | null }
+    // `execFileSync` reports the deadline as the signal it killed the child
+    // with; `ETIMEDOUT` covers the platforms that surface it as an error code.
+    return err.signal === PROBE_KILL_SIGNAL || err.code === "ETIMEDOUT"
+      ? { kind: "timeout" }
+      : { kind: "unavailable" }
+  }
+}
+
+export const globalPackageRoot = (manager: PackageManager): string | null => {
+  const probe = probeRoot(manager)
+  return probe.kind === "root" ? probe.root : null
+}
+
+export interface GlobalPackageRootProbe {
+  readonly roots: ReadonlyArray<string>
+  readonly timedOut: ReadonlyArray<PackageManager>
+  readonly timeoutMs: number
+}
+
+/**
+ * Ask every package manager where it keeps its global packages, so an addon or
+ * theme installed globally can be resolved from there. Managers that cannot
+ * answer contribute nothing; the ones that ran out of time are named, because
+ * a silent ten-second stall per manager needs explaining.
+ */
+export const probeGlobalPackageRoots = (): GlobalPackageRootProbe => {
+  const roots: string[] = []
+  const timedOut: PackageManager[] = []
+  for (const manager of managers) {
+    const probe = probeRoot(manager)
+    if (probe.kind === "root") roots.push(probe.root)
+    else if (probe.kind === "timeout") timedOut.push(manager)
+  }
+  return { roots, timedOut, timeoutMs: packageManagerProbeTimeoutMs() }
+}

package/src/cli/probe-deps.ts

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+
+import type { CommandExecutor } from "@/system/providers/shared"
+import type { ProbeDeps } from "@/system/setup-wizard"
+
+// ponytail: shared probe deps for the startup banner and the first-run check.
+// Both call sites use these identical deps, so probeAllCached's single-slot
+// TTL cache returns the same report to both — the banner's probe and the
+// first-run probe don't double the subprocess cost.
+
+export const wizardCommandExecutor: CommandExecutor = {
+  async run(command, args, options) {
+    const { execa } = await import("execa")
+    const result = await execa(command, [...args], {
+      reject: false,
+      timeout: options?.timeoutMs ?? 5_000,
+    })
+    return {
+      exitCode: result.exitCode ?? -1,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+    }
+  },
+}
+
+export const buildStandardProbeDeps = (): ProbeDeps => {
+  const home = homedir()
+  const xdgConfigHome = process.env["XDG_CONFIG_HOME"] ?? `${home}/.config`
+  return {
+    platform: process.platform,
+    homeDir: home,
+    xdgConfigHome,
+    env: process.env,
+    executor: wizardCommandExecutor,
+    fileExists: (p) => existsSync(p),
+    readFile: (p) => {
+      try {
+        return readFileSync(p, "utf8")
+      } catch {
+        return null
+      }
+    },
+  }
+}

package/src/cli/prompt.ts

@@ -0,0 +1,22 @@
+// ponytail: thin re-export of @clack/prompts so backend modules
+// (`packages/cli/src/cli/...`) can pull clack's primitives without
+// each one importing the upstream package name. Lives in `cli/` not
+// `ui/` because the `ui/` tree is reserved for React surface code
+// consumed by `packages/cli/frontend/` and `packages/cli/config-ui/`.
+//
+// Anything that imports this file MUST be in the CLI backend — never
+// the frontend or emulator SPAs.
+export {
+  intro,
+  outro,
+  note,
+  log,
+  tasks,
+  spinner,
+  select,
+  confirm,
+  text,
+  password,
+  isCancel,
+  cancel,
+} from "@clack/prompts"

package/src/cli/startup-display.ts

@@ -0,0 +1,452 @@
+import { connect, type Server, createServer, type Socket } from "node:net"
+
+import qrcode from "qrcode"
+
+import { listDevices, type DeviceDescriptor } from "@/device"
+import type { AddonCheckOutcome } from "@/addon/check-runner"
+
+import {
+  probeAllCached,
+  probeCommandExecution,
+  probeInternetAccess,
+  resetProbeCache,
+  type RuntimeFeatureProbe,
+  type SystemReport,
+} from "@/system/setup-wizard"
+
+import { cancel, intro, log, outro } from "@/cli/prompt"
+
+import {
+  readDaemonEventsFromSnapshot,
+  type DaemonEvent,
+  type DaemonLogSnapshot,
+} from "@/util/log-reader"
+import {
+  readRuntimeState,
+  resolveDaemonPaths,
+  type RuntimeState,
+} from "@/util/daemon"
+import { requestDaemonToken } from "@/util/daemon-control"
+
+import { buildStandardProbeDeps } from "./probe-deps"
+
+interface BannerOptions {
+  readonly emulator: boolean
+  readonly deviceModel?: string
+  readonly port?: number
+}
+
+interface BannerDeps {
+  readonly probeAll: typeof probeAllCached
+  readonly probeExec: typeof probeCommandExecution
+  readonly probeHttp: typeof probeInternetAccess
+  readonly listDevices: typeof listDevices
+  readonly resetCache: typeof resetProbeCache
+}
+
+const defaultBannerDeps: BannerDeps = {
+  probeAll: probeAllCached,
+  probeExec: probeCommandExecution,
+  probeHttp: probeInternetAccess,
+  listDevices,
+  resetCache: resetProbeCache,
+}
+
+export const isLogSuppressed = (
+  argv: Readonly<{ quiet?: boolean; logLevel?: string }>,
+): boolean =>
+  argv.quiet === true || argv.logLevel === "silent" || argv.logLevel === "none"
+
+const DEFAULT_PORT = 52937
+const READY_TIMEOUT_MS = 30_000
+const READY_INTERVAL_MS = 100
+const RUNTIME_STATE_TIMEOUT_MS = 30_000
+const PORT_FREE_TIMEOUT_MS = 3_000
+
+const checkTcp = (
+  host: string,
+  port: number,
+  timeoutMs: number,
+): Promise<boolean> =>
+  new Promise((resolve) => {
+    const sock: Socket = connect(port, host)
+    let settled = false
+    const finish = (ok: boolean): void => {
+      if (settled) return
+      settled = true
+      sock.destroy()
+      resolve(ok)
+    }
+    sock.once("connect", () => finish(true))
+    sock.once("error", () => finish(false))
+    setTimeout(() => finish(false), timeoutMs)
+  })
+
+// ponytail: wrapper around `checkTcp` that polls until the daemon's
+// WS port accepts a connection, or until `timeoutMs` elapses. The
+// caller decides what to do on timeout (CLI: fail loudly with the
+// accumulated daemon events). The TCP probe is intentionally cheap —
+// a single `connect()` per interval — and Node handles the OS-level
+// `ECONNREFUSED` on a closed port without holding the event loop.
+export const waitForDaemonReady = async (
+  port: number = DEFAULT_PORT,
+  timeoutMs: number = READY_TIMEOUT_MS,
+): Promise<void> => {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (await checkTcp("127.0.0.1", port, READY_INTERVAL_MS)) return
+    await new Promise((r) => setTimeout(r, READY_INTERVAL_MS))
+  }
+  throw new DaemonNotReadyError(port, timeoutMs)
+}
+
+export class DaemonNotReadyError extends Error {
+  readonly port: number
+  readonly timeoutMs: number
+  constructor(port: number, timeoutMs: number) {
+    super(
+      `daemon: port ${port} did not accept connections within ${timeoutMs}ms — daemon may have failed to start`,
+    )
+    this.name = "DaemonNotReadyError"
+    this.port = port
+    this.timeoutMs = timeoutMs
+  }
+}
+
+// ponytail: the daemon writes `runtime-state.json` only after its WS
+// bridge + vite supervisors are up. Polling for the file is the
+// canonical "fully ready" signal — much stronger than TCP-on-port
+// (which fires the moment the WS server binds, before supervisors
+// have stabilized). Returns the parsed state, or `null` on timeout.
+export const waitForRuntimeState = async (
+  timeoutMs: number = RUNTIME_STATE_TIMEOUT_MS,
+  notBefore?: number,
+): Promise<RuntimeState | null> => {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const state = readRuntimeState()
+    if (
+      state !== null &&
+      (notBefore === undefined || state.startedAt >= notBefore)
+    ) {
+      return state
+    }
+    await new Promise((r) => setTimeout(r, READY_INTERVAL_MS))
+  }
+  return null
+}
+
+// ponytail: bind a `Server` to the target port. If `EADDRINUSE` fires,
+// the port is bound by some other process (most likely the daemon we
+// just stopped, with a stuck TIME_WAIT or an orphan vite). If the
+// bind succeeds, the port is genuinely free. Used by `stop` to
+// confirm the daemon has fully released its socket.
+export const waitForPortFree = async (
+  port: number,
+  timeoutMs: number = PORT_FREE_TIMEOUT_MS,
+): Promise<boolean> => {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const ok = await tryBind(port)
+    if (ok) return true
+    await new Promise((r) => setTimeout(r, READY_INTERVAL_MS))
+  }
+  return false
+}
+
+const tryBind = (port: number): Promise<boolean> =>
+  new Promise<boolean>((resolve) => {
+    let server: Server | null = null
+    const cleanup = (ok: boolean): void => {
+      if (server !== null) {
+        server.close()
+        server = null
+      }
+      resolve(ok)
+    }
+    server = createServer()
+    server.once("error", () => cleanup(false))
+    server.once("listening", () => cleanup(true))
+    try {
+      server.listen(port, "127.0.0.1")
+    } catch {
+      cleanup(false)
+    }
+  })
+
+interface FeatureItem {
+  readonly name: string
+  readonly available: boolean
+  readonly reason?: string
+}
+
+const formatFeaturesLine = (items: ReadonlyArray<FeatureItem>): string =>
+  items
+    .map((it) =>
+      it.available
+        ? `[✓ ${it.name}]`
+        : `[✗ ${it.name}${it.reason !== undefined ? ` — ${it.reason}` : ""}]`,
+    )
+    .join(" ")
+
+const toFeatureItem = (
+  name: string,
+  probe: RuntimeFeatureProbe,
+): FeatureItem =>
+  probe.reason !== undefined
+    ? { name, available: probe.available, reason: probe.reason }
+    : { name, available: probe.available }
+
+const deviceLabel = (
+  emulator: boolean,
+  deviceModel: string | undefined,
+  devices: ReadonlyArray<DeviceDescriptor>,
+): string => {
+  if (emulator) {
+    return `Emulator (${deviceModel ?? "mk2"})`
+  }
+  if (devices.length === 0) {
+    return "detecting…"
+  }
+  const d = devices[0]
+  return d !== undefined ? `${d.model} (${d.id})` : "detecting…"
+}
+
+export interface BannerResult {
+  readonly featuresLine: string
+  readonly deviceLabel: string
+}
+
+export const buildStartupBanner = async (
+  options: BannerOptions,
+  argv: Readonly<{ quiet?: boolean; logLevel?: string }>,
+  deps: BannerDeps = defaultBannerDeps,
+): Promise<BannerResult | null> => {
+  if (isLogSuppressed(argv) || !process.stdout.isTTY) return null
+
+  deps.resetCache()
+
+  const [report, exec, http, devices] = await Promise.all([
+    deps.probeAll(buildStandardProbeDeps()),
+    deps.probeExec(),
+    deps.probeHttp(),
+    deps.listDevices(),
+  ])
+
+  // ponytail: drop the misleading "media — chromium not installed" probe from
+  // the system-feature line. That probe is for Playwright tests (frontend
+  // chromium install), not the media addon. The actual media tooling check
+  // (playerctl / wpctl / osascript / powershell) lives in the addon-checks
+  // section printed after the URL — see runBuiltinAddonChecks / printAddonCheckResults.
+  const items: FeatureItem[] = [
+    toFeatureItem("keystrokes", toSystemCap(report, "keyMacro")),
+    toFeatureItem("clipboard", toSystemCap(report, "clipboard")),
+    toFeatureItem("notifications", toSystemCap(report, "notification")),
+    toFeatureItem("active-win", toSystemCap(report, "activeApp")),
+    toFeatureItem("exec", exec),
+    toFeatureItem("http", http),
+  ]
+
+  const featuresLine = formatFeaturesLine(items)
+  const label = deviceLabel(options.emulator, options.deviceModel, devices)
+
+  intro("Starting SirenoDeck")
+  log.info(`Device: ${label}`)
+  log.info(featuresLine)
+  return { featuresLine, deviceLabel: label }
+}
+
+const toSystemCap = (
+  report: SystemReport,
+  key: "keyMacro" | "clipboard" | "notification" | "activeApp",
+): RuntimeFeatureProbe => {
+  const cap = report.capabilities[key]
+  if (cap.available) return { available: true }
+  return {
+    available: false,
+    reason:
+      cap.missing.length > 0
+        ? cap.missing.join(", ")
+        : cap.reason.length > 0
+          ? cap.reason
+          : undefined,
+  }
+}
+
+// ponytail: warning / error lines from the daemon, surfaced inline. The
+// CLI is the operator's interface to the daemon — they shouldn't have
+// to grep `service.log` to find out what went wrong during start /
+// ponytail: clack's log.* tools give us a color-coded icon + │ indent
+// for free, matching the rest of the banner. Available → log.info,
+// warn/fatal/error → log.warn/log.error. No manual ANSI escapes; no
+// trailing (HH:MM:SS) — timestamps stay in service.log for correlation.
+export const printDaemonEvents = (events: ReadonlyArray<DaemonEvent>): void => {
+  if (events.length === 0) return
+  for (const ev of events) {
+    const ctx = ev.component.length > 0 ? ` [${ev.component}]` : ""
+    const line = `${ev.message}${ctx}`
+    if (ev.level === "fatal" || ev.level === "error") log.error(line)
+    else if (ev.level === "warn") log.warn(line)
+    else log.info(line)
+  }
+}
+
+// ponytail: the URL the operator needs to open in their browser. The
+// token is regenerated per daemon session, so we always show it in the
+// URL — operators copy-paste the URL into the browser. For `--remote`
+// we use the existing QR banner (phone-friendly); for plain
+// `--emulator` we print a plain text URL — no QR/LAN section, since the daemon only binds 127.0.0.1.
+// For real (hardware) mode we print the Config UI URL. The Config UI owns the
+// clickable preview and embeds the frontend, so the raw frontend URL is not an
+// operator-facing startup endpoint.
+export const printDaemonUrl = async (
+  state: RuntimeState,
+  tokenOrOutput: string | ((text: string) => void) = "",
+  output: (text: string) => void = (text) => process.stdout.write(text),
+): Promise<void> => {
+  const token = typeof tokenOrOutput === "string" ? tokenOrOutput : ""
+  const write = typeof tokenOrOutput === "function" ? tokenOrOutput : output
+  if (state.emulatorMode) {
+    const port = state.configUiUrl.split(":").pop() ?? ""
+    const buildUrl = (host: string, deckOnly: boolean): string => {
+      const params = new URLSearchParams()
+      if (token.length > 0) params.set("token", token)
+      if (deckOnly) params.set("deckOnly", "1")
+      return `http://${host}:${port}?${params.toString()}`
+    }
+    const localUrl = buildUrl("127.0.0.1", false)
+    write(`  Config UI:  ${localUrl}#/config\n`)
+    write(`\n  Emulator:  ${localUrl}\n`)
+    if (state.remote && state.addresses.length > 0) {
+      const isTty = Boolean(process.stdout.isTTY)
+      if (isTty) {
+        write("\n  Emulator (LAN):\n")
+        for (const addr of state.addresses) {
+          const url = buildUrl(addr, true)
+          const qr = await qrcode.toString(url, {
+            type: "terminal",
+            small: true,
+          })
+          write(`\n${qr}  ${url}\n`)
+        }
+      } else {
+        for (const addr of state.addresses) {
+          write(`  ${addr}: ${buildUrl(addr, false)}\n`)
+        }
+      }
+    }
+    write("\n  Manage with: `p dev status`, `p dev reload`, `p dev stop`.\n")
+  } else {
+    const configUiUrl = state.configUiUrl
+    const configUiWithToken =
+      token.length > 0
+        ? `${configUiUrl}${configUiUrl.includes("?") ? "&" : "?"}token=${token}`
+        : configUiUrl
+    const configUi = `${configUiWithToken}#/config`
+    const content = ` Config UI: ${configUi} `
+    const border = `+${"-".repeat(content.length)}+`
+    write(`\n${border}\n|${content}|\n${border}\n`)
+    write("\n  Manage with: `p dev status`, `p dev reload`, `p dev stop`.\n")
+  }
+}
+
+// ponytail: the load-bearing function for the CLI's "wait until fully
+// started, then show the URL" flow. The CLI calls this from the
+// `start` handler and surfaces events + URL inline. On any failure
+// path the caller exits non-zero — operators expect the CLI to fail
+// loudly if the daemon didn't come up, not silently exit 0.
+export interface StartOutcome {
+  readonly state: RuntimeState | null
+  readonly token: string | null
+  readonly events: ReadonlyArray<DaemonEvent>
+  readonly tcpReady: boolean
+  readonly runtimeReady: boolean
+}
+
+export interface WaitForStartOptions {
+  readonly port: number
+  readonly tcpTimeoutMs: number
+  readonly runtimeTimeoutMs: number
+  readonly logPath: string
+  readonly logSnapshot: DaemonLogSnapshot
+  readonly notBefore?: number
+}
+
+export const waitForFullStart = async (
+  options: WaitForStartOptions,
+): Promise<StartOutcome> => {
+  let tcpReady = false
+  try {
+    await waitForDaemonReady(options.port, options.tcpTimeoutMs)
+    tcpReady = true
+  } catch (err) {
+    if (!(err instanceof DaemonNotReadyError)) throw err
+  }
+  const runtimeReady = tcpReady
+  const state = runtimeReady
+    ? await waitForRuntimeState(options.runtimeTimeoutMs, options.notBefore)
+    : null
+  const events = readDaemonEventsFromSnapshot(
+    options.logPath,
+    options.logSnapshot,
+  )
+  const token = runtimeReady
+    ? await requestDaemonToken(resolveDaemonPaths())
+    : null
+  return { state, token, events, tcpReady, runtimeReady }
+}
+
+// ponytail: per-addon requirement check results, surfaced inline next
+// to the URL. Clack's log.* tools give us a color-coded icon + │ indent
+// for free. Available checks → log.info (green ✓), failed → log.warn
+// (yellow ✗) with the reason inline. One log line per outcome so the
+// status banner shows every check independently. Grouping by addon
+// is preserved by the addon name in the message prefix.
+export const printAddonCheckResults = (
+  outcomes: ReadonlyArray<AddonCheckOutcome>,
+): void => {
+  if (outcomes.length === 0) return
+  for (const outcome of outcomes) {
+    const reason = outcome.reason !== undefined ? ` — ${outcome.reason}` : ""
+    if (outcome.available) {
+      log.info(`${outcome.addonName}/${outcome.checkName}`)
+    } else {
+      log.warn(`${outcome.addonName}/${outcome.checkName}${reason}`)
+    }
+  }
+}
+
+export const printStartupComplete = (): void => {
+  if (!process.stdout.isTTY) return
+  outro("✓ Sireno Deck started")
+}
+
+export const printStartupFailed = (err: unknown): void => {
+  if (!process.stdout.isTTY) return
+  cancel(
+    `✗ Failed to start SirenoDeck: ${err instanceof Error ? err.message : String(err)}`,
+  )
+}
+
+export const printRestartComplete = (): void => {
+  if (!process.stdout.isTTY) return
+  outro("✓ Sireno Deck restarted")
+}
+
+export const printRestartFailed = (err: unknown): void => {
+  if (!process.stdout.isTTY) return
+  cancel(
+    `✗ Failed to restart SirenoDeck: ${err instanceof Error ? err.message : String(err)}`,
+  )
+}
+
+export const printStopComplete = (portFree: boolean): void => {
+  if (!process.stdout.isTTY) return
+  if (portFree) {
+    outro("✓ Sireno Deck stopped")
+  } else {
+    cancel(
+      "✗ Sireno Deck process exited but port 52937 is still bound — see `p dev status` for orphans",
+    )
+  }
+}