@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/cli/commands/status.ts

@@ -0,0 +1,110 @@
+import type pino from "pino"
+
+import {
+  isRunning,
+  readChildren,
+  readConfigPath,
+  readFlags,
+  readPid,
+  readRuntimeState,
+  resolveDaemonPaths,
+} from "@/util/daemon"
+import { listDevices } from "@/device"
+
+import { cancel, intro, log, outro } from "@/cli/prompt"
+
+export interface StatusOptions {
+  logger: pino.Logger
+}
+
+const formatUptime = (ms: number): string => {
+  if (ms < 0) return "—"
+  const totalSeconds = Math.floor(ms / 1000)
+  const hours = Math.floor(totalSeconds / 3600)
+  const minutes = Math.floor((totalSeconds % 3600) / 60)
+  const seconds = totalSeconds % 60
+  if (hours > 0) return `${hours}h ${minutes}m`
+  if (minutes > 0) return `${minutes}m ${seconds}s`
+  return `${seconds}s`
+}
+
+export const status = async ({ logger }: StatusOptions): Promise<void> => {
+  void logger // kept for callers that want pino logs out-of-band
+
+  const paths = resolveDaemonPaths()
+  const pid = readPid(paths)
+
+  if (pid === null) {
+    intro("sirenodeck status")
+    log.error("Daemon is not running")
+    cancel("✗ No daemon process found")
+    return
+  }
+
+  const alive = isRunning(pid)
+  const flags = readFlags(paths)
+  const state = alive ? readRuntimeState(paths) : null
+  const childrenState = readChildren(paths)
+  const childPids = childrenState?.pids ?? []
+  const configPath = readConfigPath(paths)
+
+  intro("sirenodeck status")
+
+  if (alive) {
+    const startedAt = state?.startedAt ?? null
+    const uptime =
+      startedAt !== null ? formatUptime(Date.now() - startedAt) : "—"
+    log.info(`Status:    running for ${uptime} (pid ${pid})`)
+  } else {
+    log.warn(`Status:    stale pid file (pid ${pid} not alive)`)
+  }
+
+  const isEmulator = state?.emulatorMode === true || flags?.emulator === true
+  const deviceModel =
+    typeof flags?.deviceModel === "string" ? flags.deviceModel : "mk2"
+
+  if (isEmulator) {
+    log.info(`Device :   Emulator (${deviceModel}) (emulator mode)`)
+  } else {
+    let hardwareLabel = "—"
+    try {
+      const devices = await listDevices()
+      if (devices.length > 0 && devices[0] !== undefined) {
+        hardwareLabel = devices[0].label
+      }
+    } catch {
+      // ponytail: HID enumeration can throw on missing kernel modules or
+      // permission errors. Fall through to the "—" placeholder — status
+      // must not blow up if device detection is unavailable.
+    }
+    log.info(`Device :   ${hardwareLabel} (hardware mode)`)
+  }
+
+  const remoteOn = state?.remote === true || flags?.remote === true
+  log.info(`Remote:    ${remoteOn ? "on" : "off"}`)
+
+  log.info(`Config:    ${configPath ?? "—"}`)
+
+  const theme = state?.theme ?? "default"
+  log.info(`Theme:     ${theme}`)
+
+  if (childPids.length > 0) {
+    log.info(`Children:  ${childPids.length} (${childPids.join(", ")})`)
+  } else {
+    log.info("Children:  none tracked")
+  }
+
+  if (alive && state !== null) {
+    const frontendUrl = state.frontendUrl
+    log.info(`Frontend URL : ${frontendUrl}`)
+    if (state.configUiUrl.length > 0) {
+      log.info(`Config UI URL : ${state.configUiUrl}`)
+    }
+    log.info(`Bridge URL   : ${state.wsUrl}`)
+    outro("✓ Status snapshot")
+  } else {
+    cancel("✗ Stale pid file — run `p dev stop` to clean up")
+  }
+}
+
+export default status

package/src/cli/commands/stop.ts

@@ -0,0 +1,121 @@
+import type pino from "pino"
+
+import { join } from "node:path"
+
+import {
+  isRunning,
+  readChildren,
+  readPid,
+  removeChildrenFile,
+  removePidFile,
+  removeRuntimeStateFile,
+  resolveDaemonPaths,
+} from "@/util/daemon"
+import { removeDaemonControl } from "@/util/daemon-control"
+import {
+  readDaemonEventsFromSnapshot,
+  snapshotDaemonLog,
+} from "@/util/log-reader"
+
+import {
+  printDaemonEvents,
+  printStopComplete,
+  waitForPortFree,
+} from "../startup-display"
+
+export interface StopOptions {
+  readonly logger: pino.Logger
+}
+
+const DEFAULT_PORT = 52937
+
+const killGracefully = async (
+  pid: number,
+  logger: pino.Logger,
+  label: string,
+): Promise<void> => {
+  if (!isRunning(pid)) {
+    logger.debug({ pid, label }, "stop: already exited")
+    return
+  }
+  logger.info({ pid, label }, "stop: SIGTERM")
+  try {
+    process.kill(pid, "SIGTERM")
+  } catch (err) {
+    logger.warn({ err, pid, label }, "stop: SIGTERM failed")
+    return
+  }
+  const deadline = Date.now() + 5_000
+  while (Date.now() < deadline && isRunning(pid)) {
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  if (isRunning(pid)) {
+    logger.warn({ pid, label }, "stop: did not exit in 5s, sending SIGKILL")
+    try {
+      process.kill(pid, "SIGKILL")
+    } catch (err) {
+      logger.warn({ err, pid, label }, "stop: SIGKILL failed")
+    }
+  }
+}
+
+export const stop = async ({ logger }: StopOptions): Promise<void> => {
+  const pid = readPid()
+  if (pid === null) {
+    logger.info("stop: no running daemon found")
+    return
+  }
+
+  // ponytail: snapshot the log BEFORE we kill the daemon. After the
+  // kill, the daemon may write a final fatal/warn ("received SIGTERM"
+  // or vite-shutdown errors); we surface those inline so the
+  // operator sees the daemon's last words before the "stopped" line.
+  const snapshot = snapshotDaemonLog()
+  const logPath = join(resolveDaemonPaths().runtimeDir, "service.log")
+
+  const childrenState = readChildren()
+  const childPids = childrenState?.pids ?? []
+
+  for (const childPid of childPids) {
+    await killGracefully(childPid, logger, `child`)
+  }
+
+  await killGracefully(pid, logger, "daemon")
+
+  // ponytail: confirm the daemon's WS port is genuinely free. After
+  // SIGTERM/SIGKILL the kernel usually releases the port within ~50ms,
+  // but TIME_WAIT or a stuck vite can hold it. A timeout here means
+  // the next `start` will see "port in use" — surface that to the
+  // operator so they don't have to wait until they re-run start to
+  // discover the leftover.
+  const portFree = await waitForPortFree(DEFAULT_PORT)
+
+  removePidFile()
+  removeDaemonControl(resolveDaemonPaths())
+  removeRuntimeStateFile()
+  removeChildrenFile()
+
+  // ponytail: print any warn / error / fatal the daemon wrote during
+  // its shutdown window BEFORE the success/failure line. On a clean
+  // stop this is empty; on a SIGKILL escalation it surfaces the
+  // daemon's last words ("vite didn't respond to SIGTERM within 5s")
+  // without the operator having to read service.log.
+  printDaemonEvents(readDaemonEventsFromSnapshot(logPath, snapshot))
+
+  printStopComplete(portFree)
+
+  if (!portFree) {
+    // ponytail: the daemon process exited (the pid file is gone) but
+    // the WS port is still bound. That's a TIME_WAIT or a stuck
+    // orphan vite — log it as a warning but don't exit 1, since the
+    // daemon IS stopped from a process-management perspective.
+    logger.warn(
+      { port: DEFAULT_PORT },
+      "stop: daemon exited but port 52937 is still bound — check for orphans with `p dev status`",
+    )
+  }
+
+  logger.info("stop: cleanup complete")
+}
+
+export default stop

package/src/cli/commands/subprocess-supervisor.ts

@@ -0,0 +1,203 @@
+import type { ChildProcess } from "node:child_process"
+
+import type pino from "pino"
+
+// ponytail: incremental retry schedule for vite children + service-level
+// supervision. 5 entries: 2s for transient blips, 60s tail for sticky failures.
+// Total worst-case wallclock ~2 min before giving up. Replace the previous
+// flat 60s × 2 retry which could take 3 min and never recovered from a brief
+// fail without a 60s blank-period.
+export const DEFAULT_VITE_RETRY_SCHEDULE_MS = [
+  2_000, 5_000, 15_000, 30_000, 60_000,
+] as const
+
+export const DEFAULT_SERVICE_RETRY_SCHEDULE_MS = [
+  2_000, 5_000, 15_000, 30_000, 60_000,
+] as const
+
+// ponytail: minimal retry helper. Watches a single child; on unexpected exit
+// schedules a respawn after `delayScheduleMs[retriesUsed - 1]` (or `delayMs`
+// for the flat schedule). After the schedule is exhausted, gives up via
+// `onGiveUp`. Graceful shutdown (via stop() or isShuttingDown()) suppresses
+// both respawn and give-up — the parent is in control.
+//
+// Two schedule modes:
+//  - delayScheduleMs: incremental backoff. maxRetries defaults to the schedule's
+//    length. Use this for transient-restart-friendly children (vite).
+//  - delayMs + maxRetries: flat backoff. Kept for callers that don't need
+//    varying delays. If both are set, delayScheduleMs wins.
+export interface SuperviseOptions {
+  readonly label: string
+  readonly spawn: () => Promise<ChildProcess>
+  readonly onGiveUp: () => void
+  readonly isShuttingDown: () => boolean
+  readonly logger: pino.Logger
+  readonly delayScheduleMs?: ReadonlyArray<number>
+  readonly delayMs?: number
+  readonly maxRetries?: number
+  readonly kill?: (child: ChildProcess) => Promise<void>
+  /**
+   * Called when the child exits unexpectedly — BEFORE the respawn timer is
+   * scheduled. Awaited so the next respawn waits for the side effect (e.g.
+   * black-frame push) to finish. Skipped when isShuttingDown() returns true.
+   */
+  readonly onChildExit?: (
+    code: number | null,
+    signal: NodeJS.Signals | null,
+  ) => void | Promise<void>
+}
+
+export interface SuperviseHandle {
+  readonly process: ChildProcess
+  readonly stop: () => Promise<void>
+}
+
+const defaultKill = (child: ChildProcess): Promise<void> =>
+  new Promise<void>((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve()
+      return
+    }
+    let killTimer: ReturnType<typeof setTimeout> | null = null
+    child.once("exit", () => {
+      if (killTimer !== null) clearTimeout(killTimer)
+      resolve()
+    })
+    try {
+      child.kill("SIGTERM")
+    } catch {
+      if (killTimer !== null) clearTimeout(killTimer)
+      resolve()
+      return
+    }
+    killTimer = setTimeout(() => {
+      killTimer = null
+      if (child.exitCode === null && child.signalCode === null) {
+        try {
+          child.kill("SIGKILL")
+        } catch {
+          // already gone
+        }
+      }
+    }, 2_000)
+  })
+
+const resolveDelay = (
+  options: SuperviseOptions,
+  retriesUsed: number,
+): number => {
+  if (options.delayScheduleMs !== undefined) {
+    const schedule = options.delayScheduleMs
+    if (schedule.length === 0) return options.delayMs ?? 60_000
+    const idx = Math.min(retriesUsed - 1, schedule.length - 1)
+    return schedule[idx] ?? schedule[schedule.length - 1] ?? 60_000
+  }
+  return options.delayMs ?? 60_000
+}
+
+const resolveMaxRetries = (options: SuperviseOptions): number => {
+  if (options.delayScheduleMs !== undefined) {
+    return options.maxRetries ?? options.delayScheduleMs.length
+  }
+  return options.maxRetries ?? 2
+}
+
+export const supervise = async (
+  options: SuperviseOptions,
+): Promise<SuperviseHandle> => {
+  const maxRetries = resolveMaxRetries(options)
+  const killChild = options.kill ?? defaultKill
+  let stopped = false
+  let respawnTimer: ReturnType<typeof setTimeout> | null = null
+  let retriesUsed = 0
+  let current: ChildProcess | null = null
+  let initial: ChildProcess | null = null
+
+  const clearTimer = (): void => {
+    if (respawnTimer !== null) {
+      clearTimeout(respawnTimer)
+      respawnTimer = null
+    }
+  }
+
+  const giveUp = (): void => {
+    options.logger.fatal(
+      {
+        label: options.label,
+        retriesUsed,
+        maxRetries,
+      },
+      "subprocess exhausted retries — giving up",
+    )
+    stopped = true
+    clearTimer()
+    options.onGiveUp()
+  }
+
+  const scheduleRespawn = (): void => {
+    const delay = resolveDelay(options, retriesUsed)
+    respawnTimer = setTimeout(() => {
+      respawnTimer = null
+      if (stopped || options.isShuttingDown()) return
+      void spawnAndWire().catch((err) => {
+        options.logger.error(
+          { err, label: options.label },
+          "subprocess respawn failed",
+        )
+        giveUp()
+      })
+    }, delay)
+  }
+
+  const onExit = async (
+    code: number | null,
+    signal: NodeJS.Signals | null,
+  ): Promise<void> => {
+    if (stopped || options.isShuttingDown()) return
+    options.logger.warn(
+      { label: options.label, code, signal, retriesUsed },
+      "subprocess exited unexpectedly",
+    )
+    if (options.onChildExit !== undefined) {
+      try {
+        await options.onChildExit(code, signal)
+      } catch (err) {
+        options.logger.error(
+          { err, label: options.label },
+          "subprocess onChildExit failed",
+        )
+      }
+    }
+    if (retriesUsed >= maxRetries) {
+      giveUp()
+      return
+    }
+    retriesUsed += 1
+    scheduleRespawn()
+  }
+
+  const spawnAndWire = async (): Promise<ChildProcess> => {
+    const child = await options.spawn()
+    current = child
+    child.once("exit", onExit)
+    return child
+  }
+
+  initial = await spawnAndWire()
+
+  return {
+    get process(): ChildProcess {
+      // Return the current mutable child so callers that capture the handle
+      // after a respawn still see the live process. Falls back to the initial
+      // child before the first spawn resolves (defensive — shouldn't happen).
+      return current ?? initial ?? (undefined as unknown as ChildProcess)
+    },
+    stop: async (): Promise<void> => {
+      stopped = true
+      clearTimer()
+      const target = current ?? initial
+      if (target === null) return
+      await killChild(target)
+    },
+  }
+}