@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/cli/index.ts

@@ -0,0 +1,355 @@
+import { join } from "node:path"
+
+import type { ArgumentsCamelCase, CommandModule } from "yargs"
+
+import { createLogger } from "@/util/logger"
+import { BIN_NAME, PACKAGE_NAME, VERSION } from "@/version"
+
+import { logsCommand } from "./commands/logs"
+import { reload, type ReloadOptions } from "./commands/reload"
+import { restart, type RestartOptions } from "./commands/restart"
+import start, { type StartOptions } from "./commands/start"
+import { status, type StatusOptions } from "./commands/status"
+import { stop, type StopOptions } from "./commands/stop"
+import { systemRequirementsCommand } from "./commands/system-requirements"
+import { snapshotDaemonLog } from "@/util/log-reader"
+import {
+  buildStartupBanner,
+  printAddonCheckResults,
+  printDaemonEvents,
+  printDaemonUrl,
+  printStartupComplete,
+  printStartupFailed,
+  waitForFullStart,
+  type StartOutcome,
+} from "./startup-display"
+import { runBuiltinAddonChecks } from "@/addon/check-runner"
+import { installPackage, type InstallOptions } from "./commands/install"
+import type { PackageManager } from "./package-manager"
+import { openBrowser } from "@/outputClient/open-browser"
+import { requestDaemonToken } from "@/util/daemon-control"
+import {
+  isRunning,
+  readPid,
+  readRuntimeState,
+  resolveDaemonPaths,
+} from "@/util/daemon"
+import { cancel, intro, log } from "./prompt"
+
+export interface GlobalOptions {
+  verbose?: boolean
+  logLevel?: string
+  quiet?: boolean
+  json?: boolean
+}
+
+interface StartArgs extends GlobalOptions {
+  config?: string
+  port?: number
+  emulator?: boolean
+  remote?: boolean
+  deviceModel?: string
+  httpPort?: number
+  logs?: boolean
+  system?: boolean
+  autoopen?: boolean
+}
+
+interface StatusArgs extends GlobalOptions {}
+interface StopArgs extends GlobalOptions {}
+interface LogsArgs extends GlobalOptions {
+  follow?: boolean
+  lines?: number
+}
+interface ReloadArgs extends GlobalOptions {
+  logs?: boolean
+}
+interface RestartArgs extends GlobalOptions {
+  logs?: boolean
+}
+
+interface InstallArgs extends GlobalOptions {
+  packageName: string
+  config?: string
+  global?: boolean
+  packageManager?: PackageManager
+}
+
+export const buildLogger = (
+  argv: ArgumentsCamelCase<GlobalOptions>,
+): ReturnType<typeof createLogger> => {
+  const normalized = argv.logLevel === "none" ? "silent" : argv.logLevel
+  const level =
+    argv.quiet || normalized === "silent"
+      ? "silent"
+      : (normalized ?? (argv.verbose ? "debug" : "info"))
+  return createLogger({
+    verbose: argv.verbose,
+    json: argv.json ?? false,
+    level,
+  })
+}
+
+const startCommand: CommandModule<object, StartArgs> = {
+  command: "start",
+  describe: "Start the sirenodeck daemon",
+  builder: (yargs) =>
+    yargs
+      .option("config", { type: "string", description: "Path to config.yml" })
+      .option("port", {
+        type: "number",
+        description: "Port for the local server (0 = random free port)",
+      })
+      .option("emulator", {
+        type: "boolean",
+        default: false,
+        description:
+          "Run the emulator (full UI with sidebar, toolbar, device selector) at 127.0.0.1. Browser auto-opens unless --no-autoopen.",
+      })
+      .option("autoopen", {
+        type: "boolean",
+        default: true,
+        description:
+          "Auto-open the emulator URL in a browser after start. Pass --no-autoopen for headless / capture runs.",
+      })
+      .option("remote", {
+        type: "boolean",
+        default: false,
+        description:
+          "Open the emulator server to LAN clients. Implies --emulator. Binds 0.0.0.0; prints a QR for the deck-only view with token-gated HTTP.",
+      })
+      .option("device-model", {
+        type: "string",
+        description: "Emulator device model (mk2, plus, mini, xl)",
+      })
+      .option("http-port", {
+        type: "number",
+        default: 3939,
+        description:
+          "Port for the prod HTTP server that serves the bundled frontend with WS token injection",
+      })
+      .option("system", {
+        type: "boolean",
+        default: false,
+        description:
+          "Auto-install as system-wide service (requires root). Default: user-level.",
+      })
+      .option("logs", {
+        type: "boolean",
+        default: false,
+        description: "After start, follow the service log (Ctrl+C to exit)",
+      }),
+  handler: async (argv) => {
+    const logger = buildLogger(argv)
+    const options: StartOptions = {
+      logger,
+      ...(argv.config !== undefined ? { config: argv.config } : {}),
+      ...(argv.port !== undefined ? { port: argv.port } : {}),
+      ...(argv.emulator !== undefined ? { emulator: argv.emulator } : {}),
+      ...(argv.remote !== undefined ? { remote: argv.remote } : {}),
+      ...(argv.deviceModel !== undefined
+        ? { deviceModel: argv.deviceModel }
+        : {}),
+      ...(argv.httpPort !== undefined
+        ? { httpPort: argv.httpPort as number }
+        : {}),
+      ...(argv.system === true ? { system: true } : {}),
+      ...(argv.autoopen === false ? { noAutoOpen: true } : {}),
+    }
+    try {
+      await buildStartupBanner(
+        {
+          emulator: argv.emulator === true,
+          ...(argv.deviceModel !== undefined
+            ? { deviceModel: argv.deviceModel }
+            : {}),
+          ...(argv.port !== undefined ? { port: argv.port } : {}),
+        },
+        argv,
+      )
+      // ponytail: snapshot the daemon log size BEFORE the daemon's
+      // restart writes anything new. We use this to surface
+      // daemon-emitted warnings inline after the start completes,
+      // without reading the full log history.
+      const logSnapshot = snapshotDaemonLog()
+      const logPath = join(resolveDaemonPaths().runtimeDir, "service.log")
+      const startRequestedAt = Date.now()
+      const startPromise = start(options)
+      const outcome: StartOutcome = await waitForFullStart({
+        port: options.port ?? 52937,
+        tcpTimeoutMs: 30_000,
+        runtimeTimeoutMs: 30_000,
+        logPath,
+        logSnapshot,
+        notBefore: startRequestedAt,
+      })
+      // ponytail: print events the daemon emitted between the snapshot
+      // and now, BEFORE the success/failure line — operator's eye
+      // lands on each one even when stdout is a pipe. Silent on 0
+      // events.
+      printDaemonEvents(outcome.events)
+
+      if (outcome.runtimeReady && outcome.state !== null) {
+        await printDaemonUrl(outcome.state, outcome.token ?? "")
+        // ponytail: per-addon requirement checks (playerctl for media, etc.).
+        // Never blocks the daemon — failing checks are surfaced as warnings so
+        // the operator can act on them without digging into the log.
+        printAddonCheckResults(await runBuiltinAddonChecks())
+        printStartupComplete()
+      } else if (outcome.tcpReady) {
+        // ponytail: TCP is bound but the daemon didn't write runtime
+        // state in 30s. The daemon is alive but the runtime pipeline
+        // is still booting (or stuck). Fail loudly with whatever
+        // warnings the daemon emitted so the operator doesn't have to
+        // dig into the log file.
+        const message =
+          "daemon: TCP bound on 52937 but runtime state did not appear in 30s"
+        logger.warn(message)
+        process.exitCode = 1
+        printStartupFailed(message)
+        return
+      } else {
+        // ponytail: TCP never bound. Either the daemon crashed during
+        // boot, or port 52937 is held by an unrelated process. Either
+        // way, the start failed — the operator needs to know.
+        const message = `daemon: port ${options.port ?? 52937} did not accept connections in 30s`
+        logger.warn(message)
+        process.exitCode = 1
+        printStartupFailed(message)
+        return
+      }
+      await startPromise
+    } catch (err) {
+      printStartupFailed(err)
+      const e = err as { issues?: unknown; message?: unknown }
+      const message =
+        e &&
+        typeof e === "object" &&
+        "message" in e &&
+        typeof e.message === "string"
+          ? e.message
+          : "command failed"
+      logger.error({ err }, message)
+      process.exitCode = 1
+    }
+  },
+}
+
+const stopCommand: CommandModule<object, StopArgs> = {
+  command: "stop",
+  describe: "Stop the running sirenodeck daemon",
+  handler: async (argv) => {
+    const logger = buildLogger(argv)
+    const options: StopOptions = { logger }
+    await stop(options)
+  },
+}
+
+const statusCommand: CommandModule<object, StatusArgs> = {
+  command: "status",
+  describe: "Check sirenodeck daemon status",
+  handler: async (argv) => {
+    const logger = buildLogger(argv)
+    const options: StatusOptions = { logger }
+    await status(options)
+  },
+}
+
+const configUiCommand: CommandModule<object, GlobalOptions> = {
+  command: "config-ui",
+  describe: "Open the visual configuration editor",
+  handler: async (argv) => {
+    const logger = buildLogger(argv)
+    const paths = resolveDaemonPaths()
+    const pid = readPid(paths)
+    const state =
+      pid !== null && isRunning(pid) ? readRuntimeState(paths) : null
+    if (state === null) {
+      intro("sirenodeck config-ui")
+      log.error("Daemon is not running")
+      cancel("✗ Run `sirenodeck start` first")
+      return
+    }
+    const token = await requestDaemonToken(paths)
+    if (token === null) {
+      throw new Error("Could not retrieve the daemon token")
+    }
+    const base = state.configUiUrl
+    const url = `${base}${base.includes("?") ? "&" : "?"}token=${encodeURIComponent(token)}#/config`
+    log.info(`Config UI: ${url}`)
+    openBrowser(url, logger)
+  },
+}
+
+const reloadCommand: CommandModule<object, ReloadArgs> = {
+  command: "reload",
+  describe: "Send SIGUSR1 to the daemon (in-place reload)",
+  handler: async (argv) => {
+    const logger = buildLogger(argv)
+    const options: ReloadOptions = { logger }
+    await reload(options)
+  },
+}
+
+const restartCommand: CommandModule<object, RestartArgs> = {
+  command: "restart",
+  describe: "Restart the sirenodeck daemon",
+  handler: async (argv) => {
+    const logger = buildLogger(argv)
+    const options: RestartOptions = { logger }
+    await restart(options)
+  },
+}
+
+const installCommand: CommandModule<object, InstallArgs> = {
+  command: "install <packageName>",
+  describe: "Install and configure an addon or theme",
+  builder: (yargs) =>
+    yargs
+      .positional("packageName", {
+        type: "string",
+        demandOption: true,
+        description: "npm package name",
+      })
+      .option("config", { type: "string", description: "Path to config.yml" })
+      .option("global", {
+        type: "boolean",
+        default: false,
+        description: "Install globally",
+      })
+      .option("package-manager", { choices: ["pnpm", "npm", "yarn"] as const }),
+  handler: async (argv) => {
+    await installPackage({
+      packageName: argv.packageName,
+      ...(argv.config !== undefined ? { config: argv.config } : {}),
+      ...(argv.global === true ? { global: true } : {}),
+      ...(argv.packageManager !== undefined
+        ? { packageManager: argv.packageManager }
+        : {}),
+    } satisfies InstallOptions)
+  },
+}
+
+export const buildCli = async (): Promise<{
+  scriptName: string
+  commands: CommandModule<object, GlobalOptions>[]
+  packageName: string
+  version: string
+}> => {
+  return {
+    scriptName: BIN_NAME,
+    commands: [
+      configUiCommand,
+      startCommand,
+      stopCommand,
+      statusCommand,
+      restartCommand,
+      reloadCommand,
+      logsCommand as CommandModule<object, GlobalOptions>,
+      systemRequirementsCommand as CommandModule<object, GlobalOptions>,
+      installCommand as CommandModule<object, GlobalOptions>,
+    ],
+    packageName: PACKAGE_NAME,
+    version: VERSION,
+  }
+}

package/src/cli/install-root.ts

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/**
+ * Resolve the install root of the distributed bundle:
+ *   <root>/sirenodeck, <root>/lib/cli/main.mjs, <root>/frontend/dist, <root>/etc/install.json
+ *
+ * Priority: SIRENO_INSTALL_ROOT (set by the launcher/installer) → walk up from
+ * this module looking for the install markers (`etc/install.json`,
+ * `frontend/dist/index.html`). Returns null in the dev checkout so callers
+ * fall back to the monorepo layout.
+ */
+export const resolveInstallRoot = (): string | null => {
+  const env = process.env["SIRENO_INSTALL_ROOT"]
+  if (env !== undefined && env.length > 0) return env
+  let dir = dirname(fileURLToPath(import.meta.url))
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(dir, "etc", "install.json"))) return dir
+    if (existsSync(join(dir, "frontend", "dist", "index.html"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}

package/src/cli/main.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url"
+
+import yargs from "yargs"
+import { hideBin } from "yargs/helpers"
+
+import { buildCli } from "./index"
+import { createLogger } from "@/util/logger"
+import { terminateChildren } from "@/util/daemon"
+import { holdsInstanceLock } from "@/util/single-instance"
+import {
+  DAEMON_TITLE,
+  FOREGROUND_TITLE,
+  setProcessTitle,
+  startParentDeathWatchdog,
+} from "@/util/process-title"
+
+// ponytail: process name shows up in `ps`/`top`/`pstree` so operators can
+// tell which role is holding a port. The detached daemon is `sirenodeck:dm`
+// (12 chars, fits Linux 15-char `comm`); foreground CLI invocations are
+// `sirenodeck:cli`. Naming is diagnostic only — the kill identity gate
+// still relies on cmdline + port + tracked PIDs.
+const isDaemon = process.env["SIRENO_DAEMON_CHILD"] === "1"
+setProcessTitle(isDaemon ? DAEMON_TITLE : FOREGROUND_TITLE)
+
+/**
+ * Install global handlers for uncaught exceptions and unhandled promise
+ * rejections BEFORE any command runs. Without these, an error in an
+ * async addon poller or a stray promise rejection in the deck runtime
+ * would kill the process with no log output and no exit code.
+ *
+ * Handlers log at `fatal` level, then exit 1 so supervisors (systemd,
+ * launchd, the bin/sirenodeck.js wrapper) can detect the failure.
+ *
+ * `processExitInProgress` guards against double-exit when both `exit`
+ * events fire in sequence (common when child processes are still alive).
+ */
+let processExitInProgress = false
+
+const killChildrenAndExit = (
+  logger: ReturnType<typeof createLogger>,
+  code: number,
+): void => {
+  if (processExitInProgress) return
+  processExitInProgress = true
+  // Only the daemon that holds the instance lock owns the tracked children.
+  // Without this, a CLI whose start was refused because a daemon was already
+  // running would still run this cleanup on its way out — reading the shared
+  // children file and killing the RUNNING daemon's frontend. The start had
+  // changed nothing, but the deck went dark for as long as the daemon took to
+  // notice and respawn it.
+  if (!holdsInstanceLock()) {
+    process.exit(code)
+    return
+  }
+  // ponytail: 5s grace matches the run-pipeline's pushBlackFrame + drain delay
+  // so the SIGINT handler doesn't cut off the in-flight device clear writes.
+  void terminateChildren({ logger, timeoutMs: 5_000 })
+    .catch((err: unknown) => {
+      logger.warn({ err }, "main: terminate children failed")
+    })
+    .finally(() => {
+      process.exit(code)
+    })
+}
+
+const installProcessGuards = (
+  logger: ReturnType<typeof createLogger>,
+): void => {
+  process.on("uncaughtException", (err, origin) => {
+    logger.fatal(
+      { err, origin },
+      "uncaughtException — exiting to surface the failure",
+    )
+    killChildrenAndExit(logger, 1)
+  })
+  process.on("unhandledRejection", (reason, promise) => {
+    // ponytail: pino's `{ reason }` field serializes empty objects as `{}`,
+    // which hides the actual rejection value during operator triage. The
+    // `errSerializer` only fires on the literal key `err`, so dump the
+    // reason as a string fallback (so a thrown Error, a string, or a
+    // bare object all show up) and log the promise's stack when we can.
+    const reasonDump =
+      reason instanceof Error
+        ? { type: reason.name, message: reason.message, stack: reason.stack }
+        : { value: String(reason) }
+    const stackDump =
+      promise &&
+      typeof (promise as unknown as { stack?: unknown }).stack === "string"
+        ? (promise as unknown as { stack: string }).stack
+        : undefined
+    logger.fatal(
+      {
+        reason: reasonDump,
+        ...(stackDump !== undefined ? { stack: stackDump } : {}),
+      },
+      "unhandledRejection — exiting to surface the failure",
+    )
+    killChildrenAndExit(logger, 1)
+  })
+  // ponytail: SIGINT/SIGTERM also reap children — supervisors (systemd,
+  // launchd, our `stop`) send SIGTERM and we don't want orphaned vite/playwright.
+  process.on("SIGTERM", () => {
+    logger.info("main: SIGTERM received")
+    killChildrenAndExit(logger, 0)
+  })
+  process.on("SIGINT", () => {
+    logger.info("main: SIGINT received")
+    killChildrenAndExit(logger, 0)
+  })
+  // ponytail: parent-death watchdog — when the dev wrapper dies (tsx watcher
+  // killed, `bin/dev.js` SIGKILL'd, ...) the daemon is reparented to init and
+  // its vite children keep their ports. The 1s ppid poll catches that and
+  // routes through the same teardown as a graceful shutdown. Linux-only and
+  // inactive when the daemon already runs under systemd (ppid=1 from boot).
+  if (isDaemon) {
+    startParentDeathWatchdog({
+      logger,
+      onOrphan: () => killChildrenAndExit(logger, 0),
+    })
+  }
+}
+
+const main = async (): Promise<void> => {
+  const args = process.argv
+  const isJson = args.indexOf("--json") !== -1
+  const isVerbose =
+    args.indexOf("--verbose") !== -1 || args.indexOf("-v") !== -1
+  const logger = createLogger({ verbose: isVerbose, json: isJson })
+  installProcessGuards(logger)
+  const { scriptName, commands, packageName, version } = await buildCli()
+
+  const parser = yargs(hideBin(process.argv))
+    .scriptName(scriptName)
+    .usage("$0 <command> [options]")
+    .option("verbose", {
+      alias: "v",
+      type: "boolean",
+      description: "Enable verbose debug logging",
+      default: false,
+    })
+    .option("json", {
+      type: "boolean",
+      description: "Emit logs as JSON (default: human-friendly)",
+      default: false,
+    })
+    .option("log-level", {
+      type: "string",
+      description:
+        "Override log level (trace, debug, info, warn, error, fatal, silent, none)",
+    })
+    .option("quiet", {
+      alias: "q",
+      type: "boolean",
+      default: false,
+      description: "Suppress all logs and the startup banner (silent level)",
+    })
+    // ponytail: yargs only expands $0 in usage/command strings, not in the
+    // demandCommand message — it printed the literal "Run 0 --help". Build the
+    // sentence from scriptName instead.
+    .demandCommand(1, `Run ${scriptName} --help to see available commands.`)
+    .strict()
+    .help()
+    .alias("help", "h")
+    .version(`${packageName} ${version}`)
+    .alias("version", "V")
+
+  for (const cmd of commands) {
+    parser.command(cmd)
+  }
+
+  try {
+    await parser.parseAsync()
+  } catch (error) {
+    const e = error as { issues?: unknown; message?: string }
+    const message =
+      e &&
+      typeof e === "object" &&
+      "message" in e &&
+      typeof e.message === "string"
+        ? e.message
+        : "command failed"
+    if (e && Array.isArray(e.issues)) {
+      logger.error({ err: error }, message)
+    } else {
+      logger.error({ err: error }, "command failed")
+    }
+    process.exitCode = 1
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  void main()
+}