@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/util/daemon.ts

@@ -0,0 +1,575 @@
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fchmodSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs"
+import { randomBytes } from "node:crypto"
+import { homedir, tmpdir } from "node:os"
+import { join } from "node:path"
+import { getuid, platform } from "node:process"
+
+const getUid = (): number | null => {
+  try {
+    if (typeof getuid !== "function") return null
+    return getuid()
+  } catch {
+    return null
+  }
+}
+
+import type pino from "pino"
+
+export interface DaemonPaths {
+  // XDG_RUNTIME_DIR — tmpfs in Linux user scope; vanishes on reboot.
+  // pidFile identifies the current daemon process.
+  // and child PIDs are re-spawned on every boot, so neither is worth
+  // persisting. childrenFile is XDG_RUNTIME_DIR too — the SPA/vite/playwright
+  // children re-derive on boot anyway, so the file's value across reboots
+  // is post-crash child tracking only.
+  runtimeDir: string
+  pidFile: string
+  controlSocket: string
+  childrenFile: string
+  // XDG_STATE_HOME — persistent. Survives reboot. Holds the bits the
+  // daemon needs to hand the same live experience back to the user on
+  // next boot: last published snapshot (provider agent counts, statuses,
+  // attention flags), restart-mode preferences, and the resolved config
+  // path pointer so the daemon re-loads the user's config without
+  // requiring a fresh `p dev` invocation.
+  dataDir: string
+  configPathFile: string
+  flagsFile: string
+  runtimeStateFile: string
+  // Ponytail: stateFile is the legacy alias for runtimeStateFile —
+  // callers from older builds reference this name. Kept as a re-export
+  // of `runtimeStateFile` so the value is shared regardless of which
+  // an addon reads.
+  stateFile: string
+}
+
+const writeAtomic = (path: string, content: string, mode: number): void => {
+  const tmp = `${path}.tmp.${process.pid}`
+  const fd = openSync(tmp, "w", mode)
+  try {
+    writeFileSync(fd, content, { encoding: "utf8" })
+    fchmodSync(fd, mode)
+  } finally {
+    closeSync(fd)
+  }
+  renameSync(tmp, path)
+}
+
+export interface RuntimeFlags {
+  emulator: boolean
+  remote?: boolean
+  deviceModel?: string
+  port?: number
+  httpPort: number
+  config?: string
+  noAutoOpen?: boolean
+}
+
+const DAEMON_NAME = "sirenodeck"
+
+const defaultRuntimeDir = (): string => {
+  const xdg = process.env["XDG_RUNTIME_DIR"]
+  if (xdg) return xdg
+
+  switch (platform) {
+    case "darwin":
+      return join(homedir(), "Library", "Application Support", DAEMON_NAME)
+    case "win32":
+      return join(process.env["LOCALAPPDATA"] ?? tmpdir(), DAEMON_NAME)
+    default: {
+      // ponytail: getuid is undefined-typed on win32 per @types/node, but this
+      // branch only runs on linux; the runtime check satisfies the type.
+      const uid = typeof getuid === "function" ? getuid() : null
+      return uid !== null
+        ? join(tmpdir(), `sirenodeck-${uid}`)
+        : join(tmpdir(), DAEMON_NAME)
+    }
+  }
+}
+
+// ponytail: persistent storage location. On Linux, XDG_STATE_HOME
+// defaults to ~/.local/state; macOS uses Library/Application Support;
+// Windows uses %LOCALAPPDATA%. Always prefer the env var when set so
+// CI / sandboxed environments can override.
+const defaultDataDir = (): string => {
+  const xdg = process.env["XDG_STATE_HOME"]
+  if (xdg) return join(xdg, DAEMON_NAME)
+  switch (platform) {
+    case "darwin":
+      return join(
+        process.env["XDG_DATA_HOME"] ??
+          join(homedir(), "Library", "Application Support"),
+        DAEMON_NAME,
+      )
+    case "win32":
+      return join(process.env["LOCALAPPDATA"] ?? tmpdir(), DAEMON_NAME)
+    default:
+      return join(
+        process.env["XDG_STATE_HOME"] ??
+          process.env["XDG_DATA_HOME"] ??
+          join(homedir(), ".local", "state"),
+        DAEMON_NAME,
+      )
+  }
+}
+
+// ponytail: AF_UNIX paths are capped by `sun_path` — 104 bytes on macOS/BSD,
+// 108 on Linux — and `bind()` fails with a bare EINVAL when you exceed it, with
+// nothing in the message naming the length as the cause. The macOS default
+// runtime dir (~/Library/Application Support/sirenodeck) already spends ~70 of
+// those bytes, so a long username or an XDG_RUNTIME_DIR override blows the cap.
+// Fall back to a short, uid-scoped path under the system temp dir, which is the
+// same place Linux puts it when XDG_RUNTIME_DIR is unset.
+const SUN_PATH_MAX = platform === "linux" ? 108 : 104
+
+export const resolveSocketPath = (
+  runtimeDir: string,
+  basename = "",
+): string => {
+  const preferred = join(runtimeDir, `${DAEMON_NAME}${basename}.sock`)
+  if (platform === "win32") return preferred
+  if (Buffer.byteLength(preferred, "utf8") < SUN_PATH_MAX) return preferred
+  const uid = typeof getuid === "function" ? getuid() : 0
+  return join(tmpdir(), `${DAEMON_NAME}-${uid}${basename}.sock`)
+}
+
+const resolveControlSocket = (runtimeDir: string): string =>
+  resolveSocketPath(runtimeDir)
+
+export const resolveDaemonPaths = (): DaemonPaths => {
+  const runtimeDir = defaultRuntimeDir()
+  if (!existsSync(runtimeDir)) {
+    mkdirSync(runtimeDir, { recursive: true })
+    if (platform !== "win32") {
+      chmodSync(runtimeDir, 0o700)
+    }
+  }
+  const dataDir = defaultDataDir()
+  if (!existsSync(dataDir)) {
+    mkdirSync(dataDir, { recursive: true })
+    if (platform !== "win32") {
+      chmodSync(dataDir, 0o700)
+    }
+  }
+  const runtimeStateFile = join(dataDir, RUNTIME_STATE_FILE)
+  return {
+    runtimeDir,
+    pidFile: join(runtimeDir, `${DAEMON_NAME}.pid`),
+    controlSocket: resolveControlSocket(runtimeDir),
+    childrenFile: join(runtimeDir, `${DAEMON_NAME}.children.json`),
+    // ponytail: restart-survival — files that have to outlive a reboot
+    // live under dataDir (XDG_STATE_HOME). runtime-state.json is the live
+    // snapshot the daemon rehydrates from; flags.json is the user's
+    // restart-mode preferences (emulator vs real, remote, port); the
+    // config-path pointer lets the daemon re-load the same user config
+    // without requiring a fresh invocation. config and flags used to live
+    // in tmpfs — they now persist.
+    dataDir,
+    configPathFile: join(dataDir, `${DAEMON_NAME}.config`),
+    flagsFile: join(dataDir, `${DAEMON_NAME}.flags.json`),
+    runtimeStateFile,
+    stateFile: runtimeStateFile,
+  }
+}
+
+export interface StartLock {
+  readonly release: () => void
+}
+
+export const acquireStartLock = (
+  paths = resolveDaemonPaths(),
+): StartLock | null => {
+  const lockFile = `${paths.pidFile}.lock`
+  let fd: number
+  try {
+    fd = openSync(lockFile, "wx", 0o600)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err
+    // ponytail: lock already exists. Two ways out:
+    //  1. The PID inside it is dead (previous daemon crashed or was
+    //     SIGKILL'd without releasing). Clear and re-acquire immediately.
+    //  2. The lock is stale by mtime (>60s) — same outcome, defensive
+    //     fallback if the PID is unreadable or the live-check is unsure.
+    // Either case unblocks a fast retry that would otherwise have to wait
+    // out the full window. Without this, the user's exact symptom
+    // ("another start is already in progress") recurs after every daemon
+    // crash during a session of repeated restarts.
+    const holderPid = readLockHolderPid(lockFile)
+    const holderDead = holderPid !== null && !isRunning(holderPid)
+    const ageMs = safeStatAgeMs(lockFile)
+    if (holderDead || (ageMs !== null && ageMs > 60_000)) {
+      try {
+        unlinkSync(lockFile)
+        fd = openSync(lockFile, "wx", 0o600)
+      } catch {
+        return null
+      }
+    } else {
+      return null
+    }
+  }
+  if (fd === undefined!) return null
+  writeFileSync(fd, `${process.pid}\n`, { encoding: "utf8" })
+  return {
+    release: () => {
+      try {
+        closeSync(fd!)
+        unlinkSync(lockFile)
+      } catch {
+        // ignore
+      }
+    },
+  }
+}
+
+const readLockHolderPid = (lockFile: string): number | null => {
+  try {
+    const raw = readFileSync(lockFile, "utf8").trim()
+    const pid = Number.parseInt(raw, 10)
+    return Number.isFinite(pid) && pid > 0 ? pid : null
+  } catch {
+    return null
+  }
+}
+
+const safeStatAgeMs = (lockFile: string): number | null => {
+  try {
+    return Date.now() - statSync(lockFile).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+export const removeStartLock = (paths = resolveDaemonPaths()): void => {
+  const lockFile = `${paths.pidFile}.lock`
+  if (existsSync(lockFile)) {
+    try {
+      unlinkSync(lockFile)
+    } catch {
+      // ignore — best-effort cleanup of an orphaned lock from a dead daemon
+    }
+  }
+}
+
+export const readPid = (paths = resolveDaemonPaths()): number | null => {
+  if (!existsSync(paths.pidFile)) return null
+  const raw = readFileSync(paths.pidFile, "utf8").trim()
+  const pid = Number.parseInt(raw, 10)
+  return Number.isFinite(pid) && pid > 0 ? pid : null
+}
+
+export const writePid = (pid: number, paths = resolveDaemonPaths()): void => {
+  writeAtomic(paths.pidFile, `${pid}\n`, 0o600)
+}
+
+export const removePidFile = (paths = resolveDaemonPaths()): void => {
+  if (existsSync(paths.pidFile)) unlinkSync(paths.pidFile)
+}
+
+/**
+ * Liveness, and nothing else: does this pid exist and can we signal it?
+ *
+ * ponytail: this used to additionally require the target's cmdline to contain
+ * a per-daemon sentinel, which is a test it could never pass. The sentinel was
+ * written only into the daemon's OWN environment, never into its argv, and the
+ * daemon rewrites its process title to `sirenodeck:dm` — so on macOS
+ * `ps -o command=` returns that title and on Linux the argv never carried the
+ * token either. Any caller that had inherited SIRENO_DAEMON_SENTINEL from the
+ * daemon therefore saw a live daemon as dead, and the damage was not cosmetic:
+ * `stopExisting` took its "stale pid file" branch, deleted the file and
+ * returned WITHOUT killing the daemon, leaving start free to boot a second one
+ * alongside the first. Both then ran, fighting over the same ports.
+ *
+ * Liveness and identity are separate questions. This answers the first; the
+ * `isOurDaemon` fingerprint in port-identity answers the second; and the
+ * single-instance lock, not a pid comparison, is what actually keeps two
+ * daemons apart.
+ */
+export const isRunning = (pid: number): boolean => {
+  if (pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM means the pid exists but belongs to another user — still running.
+    return (error as NodeJS.ErrnoException).code === "EPERM"
+  }
+}
+
+export const generateToken = (): string => randomBytes(32).toString("base64url")
+
+export interface ChildrenState {
+  pids: number[]
+}
+
+export const readChildren = (
+  paths = resolveDaemonPaths(),
+): ChildrenState | null => {
+  if (!existsSync(paths.childrenFile)) return null
+  try {
+    const raw = readFileSync(paths.childrenFile, "utf8")
+    const parsed = JSON.parse(raw) as unknown
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "pids" in parsed &&
+      Array.isArray((parsed as { pids: unknown }).pids)
+    ) {
+      const pids = (parsed as { pids: unknown[] }).pids
+        .map((p) => Number.parseInt(String(p), 10))
+        .filter((p) => Number.isFinite(p) && p > 0)
+      return { pids }
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+export const writeChildren = (
+  state: ChildrenState,
+  paths = resolveDaemonPaths(),
+): void => {
+  writeAtomic(paths.childrenFile, JSON.stringify(state), 0o600)
+}
+
+export const removeChildrenFile = (paths = resolveDaemonPaths()): void => {
+  if (existsSync(paths.childrenFile)) unlinkSync(paths.childrenFile)
+}
+
+export const readConfigPath = (paths = resolveDaemonPaths()): string | null => {
+  if (!existsSync(paths.configPathFile)) return null
+  const raw = readFileSync(paths.configPathFile, "utf8").trim()
+  return raw.length > 0 ? raw : null
+}
+
+export const writeConfigPath = (
+  configPath: string,
+  paths = resolveDaemonPaths(),
+): void => {
+  writeAtomic(paths.configPathFile, `${configPath}\n`, 0o600)
+}
+
+export const removeConfigPathFile = (paths = resolveDaemonPaths()): void => {
+  if (existsSync(paths.configPathFile)) unlinkSync(paths.configPathFile)
+}
+
+export const readFlags = (
+  paths = resolveDaemonPaths(),
+): RuntimeFlags | null => {
+  if (!existsSync(paths.flagsFile)) return null
+  try {
+    const raw = readFileSync(paths.flagsFile, "utf8")
+    const parsed = JSON.parse(raw) as Partial<RuntimeFlags>
+    if (
+      typeof parsed.emulator !== "boolean" ||
+      typeof parsed.httpPort !== "number"
+    ) {
+      return null
+    }
+    return {
+      emulator: parsed.emulator,
+      httpPort: parsed.httpPort,
+      ...(typeof parsed.remote === "boolean" ? { remote: parsed.remote } : {}),
+      ...(typeof parsed.deviceModel === "string"
+        ? { deviceModel: parsed.deviceModel }
+        : {}),
+      ...(typeof parsed.port === "number" ? { port: parsed.port } : {}),
+    }
+  } catch {
+    return null
+  }
+}
+
+export const writeFlags = (
+  flags: RuntimeFlags,
+  paths = resolveDaemonPaths(),
+): void => {
+  writeAtomic(paths.flagsFile, JSON.stringify(flags), 0o600)
+}
+
+export const removeFlagsFile = (paths = resolveDaemonPaths()): void => {
+  if (existsSync(paths.flagsFile)) unlinkSync(paths.flagsFile)
+}
+
+export interface RuntimeState {
+  readonly configUiUrl: string
+  readonly wsUrl: string
+  readonly frontendUrl: string
+  readonly lanHost: string
+  readonly addresses: ReadonlyArray<string>
+  readonly emulatorMode: boolean
+  readonly remote: boolean
+  readonly startedAt: number
+  readonly theme?: string
+}
+
+export const RUNTIME_STATE_FILE = "runtime-state.json"
+
+export const writeRuntimeState = (
+  state: RuntimeState,
+  paths = resolveDaemonPaths(),
+): void => {
+  writeAtomic(paths.runtimeStateFile, JSON.stringify(state, null, 2), 0o600)
+}
+
+export const readRuntimeState = (
+  paths = resolveDaemonPaths(),
+): RuntimeState | null => {
+  const filePath = paths.runtimeStateFile
+  if (!existsSync(filePath)) return null
+  try {
+    const raw = readFileSync(filePath, "utf8")
+    const parsed = JSON.parse(raw) as unknown
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      typeof (parsed as RuntimeState).configUiUrl === "string" &&
+      typeof (parsed as RuntimeState).wsUrl === "string" &&
+      typeof (parsed as RuntimeState).frontendUrl === "string" &&
+      typeof (parsed as RuntimeState).lanHost === "string" &&
+      Array.isArray((parsed as RuntimeState).addresses) &&
+      typeof (parsed as RuntimeState).emulatorMode === "boolean" &&
+      typeof (parsed as RuntimeState).remote === "boolean"
+    ) {
+      const p = parsed as RuntimeState
+      return {
+        configUiUrl: p.configUiUrl,
+        wsUrl: p.wsUrl,
+        frontendUrl: p.frontendUrl,
+        lanHost: p.lanHost,
+        addresses: p.addresses,
+        emulatorMode: p.emulatorMode,
+        remote: p.remote,
+        startedAt: typeof p.startedAt === "number" ? p.startedAt : Date.now(),
+        theme: typeof p.theme === "string" ? p.theme : "default",
+      }
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+export const removeRuntimeStateFile = (paths = resolveDaemonPaths()): void => {
+  if (existsSync(paths.runtimeStateFile)) {
+    unlinkSync(paths.runtimeStateFile)
+  }
+}
+
+// ponytail: child tracking is best-effort — orphans from a hard kill are reaped
+// ponytail: terminateChildren first tries the pid as a process (the child
+// itself) and then falls back to the pid as a NEGATIVE pid (process group
+// leader). When vite is spawned with `detached: true` its pid IS the pgid,
+// so kill(-pgid, SIGTERM) takes down the whole group in one shot — that's
+// how we guarantee the frontend port doesn't stay bound by orphans after
+// the daemon dies. Windows ignores the negative pid form silently.
+const signalChildGroup = (pid: number, signal: NodeJS.Signals): void => {
+  try {
+    process.kill(pid, signal)
+  } catch {
+    // pid already dead or no permission — try as process group
+  }
+  try {
+    process.kill(-pid, signal)
+  } catch {
+    // not a pgid or already gone
+  }
+}
+
+export const terminateChildren = async ({
+  timeoutMs = 5000,
+  logger,
+  paths = resolveDaemonPaths(),
+}: {
+  timeoutMs?: number
+  logger?: pino.Logger
+  paths?: DaemonPaths
+}): Promise<void> => {
+  const state = readChildren(paths)
+  if (state === null || state.pids.length === 0) return
+
+  const alive = state.pids.filter((p) => isRunning(p))
+  if (alive.length === 0) {
+    writeChildren({ pids: [] }, paths)
+    return
+  }
+
+  // Phase 1: SIGTERM all
+  for (const pid of alive) {
+    signalChildGroup(pid, "SIGTERM")
+    logger?.debug({ pid }, "daemon: sent SIGTERM to child (+ group)")
+  }
+
+  // Wait for graceful shutdown
+  const deadline = Date.now() + timeoutMs
+  let remaining = alive.filter((p) => isRunning(p))
+  while (remaining.length > 0 && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 200))
+    remaining = remaining.filter((p) => isRunning(p))
+  }
+
+  // Phase 2: SIGKILL stragglers
+  for (const pid of remaining) {
+    signalChildGroup(pid, "SIGKILL")
+    logger?.debug({ pid }, "daemon: sent SIGKILL to child (+ group)")
+  }
+
+  // Prune dead from tracked list
+  const stillAlive = state.pids.filter((p) => isRunning(p))
+  writeChildren({ pids: stillAlive }, paths)
+  if (stillAlive.length < state.pids.length) {
+    logger?.info(
+      { killed: state.pids.length - stillAlive.length },
+      "daemon: cleaned up terminated children",
+    )
+  }
+}
+
+export const appendChild = (
+  pid: number,
+  paths = resolveDaemonPaths(),
+): void => {
+  const current = readChildren(paths) ?? { pids: [] }
+  if (current.pids.includes(pid)) return
+  writeChildren({ pids: [...current.pids, pid] }, paths)
+}
+
+export const removeChild = (
+  pid: number,
+  paths = resolveDaemonPaths(),
+): void => {
+  const current = readChildren(paths)
+  if (current === null) return
+  const next = current.pids.filter((p) => p !== pid)
+  if (next.length === current.pids.length) return
+  writeChildren({ pids: next }, paths)
+}
+
+export const pruneStaleChildren = (
+  paths = resolveDaemonPaths(),
+  logger?: pino.Logger,
+): number => {
+  const current = readChildren(paths)
+  if (current === null) return 0
+  const alive = current.pids.filter((p) => isRunning(p))
+  const pruned = current.pids.length - alive.length
+  if (pruned === 0) return 0
+  writeChildren({ pids: alive }, paths)
+  for (const dead of current.pids.filter((p) => !isRunning(p))) {
+    logger?.info({ pid: dead }, "daemon: pruned stale child pid")
+  }
+  return pruned
+}

package/src/util/device-config.ts

@@ -0,0 +1,56 @@
+import {
+  writeFileSync,
+  renameSync,
+  existsSync,
+  readFileSync,
+  unlinkSync,
+  mkdirSync,
+} from "node:fs"
+import { dirname } from "node:path"
+
+export interface DeviceConfig {
+  readonly serial: string
+  readonly path: string
+  readonly model: string
+}
+
+export interface LoadDeviceConfigOptions {
+  readonly xdgConfigHome: string
+}
+
+export interface SaveDeviceConfigOptions extends LoadDeviceConfigOptions {
+  readonly config: DeviceConfig
+}
+
+const configPathFor = (xdgConfigHome: string): string =>
+  `${xdgConfigHome}/sirenodeck/device.json`
+
+export const loadDeviceConfig = (
+  options: LoadDeviceConfigOptions,
+): DeviceConfig | null => {
+  const path = configPathFor(options.xdgConfigHome)
+  if (!existsSync(path)) return null
+  try {
+    const raw = readFileSync(path, "utf8")
+    const parsed = JSON.parse(raw) as Partial<DeviceConfig>
+    if (
+      typeof parsed.serial === "string" &&
+      typeof parsed.path === "string" &&
+      typeof parsed.model === "string"
+    ) {
+      return { serial: parsed.serial, path: parsed.path, model: parsed.model }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+export const saveDeviceConfig = (options: SaveDeviceConfigOptions): void => {
+  const path = configPathFor(options.xdgConfigHome)
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.tmp`
+  writeFileSync(tmp, JSON.stringify(options.config, null, 2), "utf8")
+  renameSync(tmp, path)
+  if (existsSync(tmp)) unlinkSync(tmp)
+}

package/src/util/errors.ts

@@ -0,0 +1,13 @@
+export class NotImplementedError extends Error {
+  constructor(feature: string) {
+    super(`Not implemented: ${feature}`)
+    this.name = "NotImplementedError"
+  }
+}
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ConfigError"
+  }
+}