@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/system/setup-wizard/sudo.ts

@@ -0,0 +1,178 @@
+import { execFile, spawn } from "node:child_process"
+import { promisify } from "node:util"
+
+import type pino from "pino"
+
+const execFileAsync = promisify(execFile)
+
+export interface SudoRunOptions {
+  readonly command: string
+  readonly args: ReadonlyArray<string>
+  readonly logger?: pino.Logger
+  readonly stdinInput?: string
+  readonly timeoutMs?: number
+}
+
+export interface SudoRunResult {
+  readonly exitCode: number
+  readonly stdout: string
+  readonly stderr: string
+  readonly neededPassword: boolean
+  readonly succeeded: boolean
+}
+
+const PROBE_TIMEOUT_MS = 3_000
+
+export const isSudoNopasswd = async (): Promise<boolean> => {
+  try {
+    await execFileAsync("sudo", ["-n", "true"], {
+      timeout: PROBE_TIMEOUT_MS,
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ponytail: match the real-world sudo failure patterns. The last pattern
+// catches the PAM-style prompt sudo emits when it has eaten the password
+// from stdin and decides auth failed — `[sudo: authenticate] Password:` is
+// what appears when -S doesn't read from a TTY and the user didn't type
+// anything. Without this match the wizard reports a bare "exit 1" with no
+// hint that the password was the cause.
+const NEEDS_PASSWORD = [
+  /password is required/i,
+  /sorry,? try again/i,
+  /incorrect password attempt/i,
+  /authentication required but not attempted/i,
+  /^\[sudo:?\s*\w*\]?\s*Password:?$/m,
+]
+
+const stderrNeedsPassword = (stderr: string): boolean =>
+  NEEDS_PASSWORD.some((re) => re.test(stderr))
+
+// ponytail: spawn (not execFile) so we control the stdin lifecycle. The
+// previous execFile + `input` race lost the password to the pipe close —
+// `child.stdin.write(input)` is queued, but sudo reads EOF before Node.js
+// flushes it. spawn gives us an explicit write → drain → close sequence.
+export const runWithSudo = async (
+  options: SudoRunOptions,
+): Promise<SudoRunResult> => {
+  const args = ["-S", "--", options.command, ...options.args]
+  const timeoutMs = options.timeoutMs ?? 60_000
+  const logger = options.logger
+
+  return new Promise((resolve) => {
+    const child = spawn("sudo", args, { stdio: ["pipe", "pipe", "pipe"] })
+    let stdout = ""
+    let stderr = ""
+    let settled = false
+
+    const settle = (result: SudoRunResult): void => {
+      if (settled) return
+      settled = true
+      resolve(result)
+    }
+
+    child.stdout.on("data", (c: Buffer) => {
+      stdout += c.toString()
+    })
+    child.stderr.on("data", (c: Buffer) => {
+      stderr += c.toString()
+    })
+    child.stdin.on("error", () => {
+      // ignore EPIPE if sudo exits before we finish writing
+    })
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL")
+      settle({
+        exitCode: 124,
+        stdout,
+        stderr: stderr + "\n[sirenodeck] sudo timed out",
+        neededPassword: stderrNeedsPassword(stderr),
+        succeeded: false,
+      })
+    }, timeoutMs)
+
+    child.on("error", (err) => {
+      clearTimeout(timeout)
+      settle({
+        exitCode: 1,
+        stdout,
+        stderr: stderr + (stderr.length > 0 ? "\n" : "") + err.message,
+        neededPassword: false,
+        succeeded: false,
+      })
+    })
+
+    child.on("close", (code) => {
+      clearTimeout(timeout)
+      const exitCode = code ?? 1
+      const neededPassword = stderrNeedsPassword(stderr)
+      if (exitCode !== 0) {
+        logger?.warn(
+          { exitCode, stderr: stderr.slice(0, 500) },
+          "sudo run failed",
+        )
+      }
+      settle({
+        exitCode,
+        stdout,
+        stderr,
+        neededPassword,
+        succeeded: code === 0,
+      })
+    })
+
+    if (options.stdinInput !== undefined && options.stdinInput.length > 0) {
+      child.stdin.write(options.stdinInput, (err) => {
+        if (err) return
+        child.stdin.end()
+      })
+    } else {
+      child.stdin.end()
+    }
+  })
+}
+
+export const capturePassword = (prompt: string): Promise<string> =>
+  new Promise((resolve, reject) => {
+    if (!process.stdin.isTTY) {
+      reject(new Error("cannot read sudo password: no TTY"))
+      return
+    }
+    const stdin = process.stdin
+    const oldRaw = (stdin as { isRaw?: boolean }).isRaw
+    stdin.setRawMode?.(true)
+    stdin.resume()
+    stdin.write("")
+    let password = ""
+    const onData = (chunk: Buffer | string): void => {
+      const str = chunk.toString()
+      for (const ch of str) {
+        if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+          stdin.removeListener("data", onData)
+          stdin.setRawMode?.(oldRaw ?? false)
+          stdin.pause()
+          process.stdout.write("\n")
+          resolve(password)
+          return
+        }
+        if (ch === "\u0003") {
+          stdin.removeListener("data", onData)
+          stdin.setRawMode?.(oldRaw ?? false)
+          stdin.pause()
+          reject(new Error("user cancelled password prompt"))
+          return
+        }
+        if (ch === "\u007f" || ch === "\b") {
+          password = password.slice(0, -1)
+          continue
+        }
+        password += ch
+      }
+    }
+    stdin.on("data", onData)
+    process.stdout.write(prompt)
+  })

package/src/system/setup-wizard/types.ts

@@ -0,0 +1,133 @@
+import type { CommandExecutor } from "../providers/shared"
+
+export type CapabilityName =
+  | "keyMacro"
+  | "clipboard"
+  | "notification"
+  | "activeApp"
+
+export type PackageManager =
+  | "apt"
+  | "dnf"
+  | "pacman"
+  | "zypper"
+  | "brew"
+  | "none"
+
+export type DesktopSession = "wayland" | "x11" | "unknown"
+
+/**
+ * An OS permission a capability needs on top of its binary. `null` on
+ * platforms where the capability needs no grant.
+ *
+ * ponytail: without this, a denied grant was squeezed into `missing` as a fake
+ * command name, so the panel rendered "osascript: Not installed" for a binary
+ * that ships with macOS and is very much installed. Installed-ness and
+ * permission are two independent facts and the report now carries both.
+ */
+export interface CapabilityPermission {
+  /** Human name of the grant, e.g. "Accessibility". */
+  readonly label: string
+  readonly granted: boolean
+  /** One sentence telling the user how to grant it. */
+  readonly hint: string
+  /** Deep link we can hand to `open`, when the OS offers one. */
+  readonly settingsUrl: string | null
+}
+
+export interface CapabilityProbe {
+  readonly name: CapabilityName
+  /** Binary present AND any required permission granted. */
+  readonly available: boolean
+  /** Binary present, regardless of permissions. */
+  readonly toolInstalled: boolean
+  readonly permission: CapabilityPermission | null
+  readonly missing: ReadonlyArray<string>
+  readonly preferred: string
+  readonly reason: string
+}
+
+export interface UdevProbe {
+  readonly rulesInstalled: boolean
+  readonly rulesPath: string
+  readonly streamDeckConnected: boolean
+  readonly matchedProductIds: ReadonlyArray<string>
+}
+
+export interface ConfigProbe {
+  readonly exists: boolean
+  readonly path: string
+}
+
+export interface SystemReport {
+  readonly platform: string
+  readonly homeDir: string
+  readonly xdgConfigHome: string
+  readonly session: DesktopSession
+  readonly packageManager: PackageManager
+  readonly capabilities: Readonly<Record<CapabilityName, CapabilityProbe>>
+  readonly udev: UdevProbe
+  readonly config: ConfigProbe
+}
+
+export interface InstallStep {
+  readonly id: string
+  readonly capability: CapabilityName | "udev" | "config"
+  readonly title: string
+  readonly description: string
+  readonly packageManager: PackageManager
+  readonly packages: ReadonlyArray<string>
+  readonly sudo: boolean
+  readonly manualOnly: boolean
+  readonly manualInstructions: string
+  readonly verifyCommand?: string
+}
+
+export type InstallStepResult = "installed" | "skipped" | "failed" | "manual"
+
+export interface WizardOutcome {
+  readonly report: SystemReport
+  readonly steps: ReadonlyArray<InstallStep>
+  readonly results: Readonly<Record<string, InstallStepResult>>
+  readonly configSeeded: boolean
+  readonly configPath: string
+}
+
+export interface ProbeDeps {
+  readonly platform: string
+  readonly homeDir: string
+  readonly xdgConfigHome: string
+  readonly env: NodeJS.ProcessEnv
+  readonly executor: CommandExecutor
+  readonly extraFsProbe?: (command: string) => boolean
+  readonly fileExists: (path: string) => boolean
+  readonly readFile: (path: string) => string | null
+  // ponytail: the config the caller actually intends to run with. Without it
+  // the probe only ever stats $XDG_CONFIG_HOME/sirenodeck/config.yml, so a
+  // valid `--config ./my.yml` still reported "Config: missing" and the
+  // first-run gate refused to start the daemon.
+  readonly configPath?: string
+}
+
+export interface SystemReportSummary {
+  readonly ok: boolean
+  readonly session: DesktopSession
+  readonly packageManager: PackageManager
+  readonly missingCapabilities: ReadonlyArray<CapabilityName>
+  readonly udevMissing: boolean
+  readonly configMissing: boolean
+  readonly configPath: string
+  readonly streamDeckConnected: boolean
+  readonly lines: ReadonlyArray<string>
+}
+
+export const UDEV_RULES_PATH = "/etc/udev/rules.d/70-sirenodeck.rules"
+
+/**
+ * Deep link that opens System Settings straight at the Accessibility pane, so
+ * the user does not have to hunt through Privacy & Security by hand. This URL
+ * scheme is the documented way to target a settings pane and has survived the
+ * System Preferences → System Settings rename.
+ */
+export const ACCESSIBILITY_SETTINGS_URL =
+  "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

package/src/system/virtual-stream-deck.ts

@@ -0,0 +1,67 @@
+import { EventEmitter } from "node:events"
+
+export type StreamDeckKeyEventType = "down" | "up"
+
+export interface StreamDeckKeyEvent {
+  readonly type: StreamDeckKeyEventType
+  readonly keyIndex: number
+  readonly timestamp: number
+}
+
+export interface VirtualStreamDeckOptions {
+  readonly keyCount: number
+  readonly autoTimestamp?: boolean
+}
+
+export interface VirtualStreamDeckLifecycle {
+  getKeyCount(): number
+  injectKeyEvent(event: StreamDeckKeyEvent): void
+  injectKey(type: StreamDeckKeyEventType, keyIndex: number): void
+  onKeyEvent(handler: (event: StreamDeckKeyEvent) => void): () => void
+  clear(): void
+}
+
+export const createVirtualStreamDeckLifecycle = (
+  options: VirtualStreamDeckOptions,
+): VirtualStreamDeckLifecycle => {
+  const emitter = new EventEmitter()
+  const { autoTimestamp = true } = options
+
+  const getKeyCount = (): number => options.keyCount
+
+  const injectKeyEvent = (event: StreamDeckKeyEvent): void => {
+    emitter.emit("key", event)
+  }
+
+  const injectKey = (type: StreamDeckKeyEventType, keyIndex: number): void => {
+    if (keyIndex < 0 || keyIndex >= options.keyCount) {
+      throw new Error(
+        `injectKey: keyIndex ${keyIndex} out of range (0..${options.keyCount - 1})`,
+      )
+    }
+    injectKeyEvent({
+      type,
+      keyIndex,
+      timestamp: autoTimestamp ? Date.now() : 0,
+    })
+  }
+
+  const onKeyEvent = (
+    handler: (event: StreamDeckKeyEvent) => void,
+  ): (() => void) => {
+    emitter.on("key", handler)
+    return () => emitter.off("key", handler)
+  }
+
+  const clear = (): void => {
+    emitter.removeAllListeners("key")
+  }
+
+  return {
+    getKeyCount,
+    injectKeyEvent,
+    injectKey,
+    onKeyEvent,
+    clear,
+  }
+}

package/src/themes/css.ts

@@ -0,0 +1,210 @@
+import type { ThemeJsonManifest } from "./manifest"
+
+function toFontFamilyValue(fontFamily: string): string {
+  return fontFamily.includes(",")
+    ? fontFamily
+    : `'${fontFamily.replace(/'/g, "\\'")}'`
+}
+
+function formatRoleName(name: string): string {
+  if (name === "main_text") return "main"
+  if (name === "auxiliary_text") return "aux"
+  if (name === "monospace") return "mono"
+  return name
+}
+
+function formatTypographyRoleVariables(
+  roleName: string,
+  role: {
+    fontFamily: string
+    fontSize: number
+    fontWeight: number
+    letterSpacing?: number
+  },
+): string[] {
+  const cssRoleName = formatRoleName(roleName)
+  return [
+    `  --sireno-font-${cssRoleName}-family: ${toFontFamilyValue(role.fontFamily)};`,
+    `  --sireno-font-${cssRoleName}-size: ${role.fontSize}px;`,
+    `  --sireno-font-${cssRoleName}-weight: ${role.fontWeight};`,
+    `  --sireno-font-${cssRoleName}-tracking: ${role.letterSpacing ?? 0}px;`,
+  ]
+}
+
+const FORMAT_BY_EXT: Record<string, string> = {
+  ".woff2": "woff2",
+  ".woff": "woff",
+  ".ttf": "truetype",
+  ".otf": "opentype",
+}
+
+/**
+ * Derive the CSS `format()` token from the font src extension. Falls back to
+ * truetype for unknown / extensionless paths so legacy manifests keep working.
+ */
+function fontFormatForSrc(src: string): string {
+  const match = src.match(/\.[a-z0-9]+(?:\?.*)?$/i)
+  if (match === null) return "truetype"
+  return FORMAT_BY_EXT[match[0].toLowerCase()] ?? "truetype"
+}
+
+const MANIFEST_TO_CSS_TOKEN: Record<string, string> = {
+  background: "bg",
+  foreground: "fg",
+  "foreground-contrast": "foreground-contrast",
+  frame: "frame",
+  primary: "primary",
+  accent: "accent",
+  success: "success",
+  danger: "danger",
+}
+
+export function buildThemeCss(
+  manifest: ThemeJsonManifest,
+  stylesheetContents: ReadonlyArray<string>,
+): string {
+  const { colorTokens, typography, fonts } = manifest
+
+  const parts: string[] = []
+
+  // Tailwind @theme block — emitted last so the @theme block is the
+  // final block the Tailwind v4 PostCSS plugin sees. Empirically the
+  // vite plugin truncates a leading @theme block to only the first
+  // few entries; emitting it after @font-face / :root makes the full
+  // set of variables land in @layer theme and produce utilities like
+  // bg-frame, text-accent, font-mono, etc.
+  const themeLines = ["@theme {"]
+  for (const [token, value] of Object.entries(colorTokens)) {
+    const cssToken =
+      MANIFEST_TO_CSS_TOKEN[token] ??
+      token.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+    themeLines.push(`  --color-${cssToken}: ${value};`)
+  }
+  for (const [roleName, role] of Object.entries(typography)) {
+    const cssRoleName = formatRoleName(roleName)
+    themeLines.push(
+      `  --font-${cssRoleName}: ${toFontFamilyValue(role.fontFamily)}, ui-sans-serif, system-ui, sans-serif;`,
+    )
+  }
+  themeLines.push("}")
+
+  // @font-face declarations
+  if (fonts.length > 0) {
+    const fontFaces = fonts.map((f) => {
+      // Variable fonts — emit a single @font-face with from..to range when
+      // the manifest declares axes. Otherwise preserve the single weight.
+      const axes = f.axes
+      const weightRange = axes?.weight
+      const weight =
+        weightRange !== undefined
+          ? `${weightRange[0]} ${weightRange[1]}`
+          : f.fontStyle === "italic"
+            ? `${f.fontWeight} italic`
+            : String(f.fontWeight)
+      const format = fontFormatForSrc(f.src)
+      return `@font-face {\n  font-family: '${f.fontFamily}';\n  font-style: ${f.fontStyle};\n  font-weight: ${weight};\n  src: url('${f.src}') format('${format}');\n}`
+    })
+    parts.push(fontFaces.join("\n\n"))
+  }
+
+  // :root CSS variables (runtime) — emit only the --sireno-color-* prefixed
+  // runtime values. We deliberately avoid also setting the plain --color-*
+  // names here, because Tailwind v4 will only keep a @theme variable in
+  // @layer theme when it is the unique declaration of that name. If we
+  // duplicate --color-frame in :root, Tailwind considers the @theme entry
+  // redundant and silently drops it, leaving bg-frame / text-frame / etc.
+  // utilities un-generated.
+  const rootLines = [":root {"]
+  for (const [token, value] of Object.entries(colorTokens)) {
+    const cssToken =
+      MANIFEST_TO_CSS_TOKEN[token] ??
+      token.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+    rootLines.push(`  --sireno-color-${cssToken}: ${value};`)
+  }
+  for (const [roleName, role] of Object.entries(typography)) {
+    rootLines.push(...formatTypographyRoleVariables(roleName, role))
+  }
+  // Variant tokens — every theme must declare the 5 required keys; themes
+  // may add extras. ButtonFrame reads --sireno-variant-<name>-{bg,border,fg,glow}
+  // directly, so addons and themes both go through one surface.
+  //
+  // buttonColor variants may also declare a `tokens` block to override
+  // primary/accent/foreground/foreground-contrast/success/danger per-variant.
+  // For 4-slot variants (no tokens block), fall back to theme colorTokens so
+  // primitives reading --sireno-color-* via cascade get the right value.
+  const VARIANT_TOKEN_KEYS = [
+    "primary",
+    "accent",
+    "foreground",
+    "foreground-contrast",
+    "success",
+    "danger",
+    "muted",
+  ] as const
+  for (const [variantName, styles] of Object.entries(manifest.variants)) {
+    rootLines.push(
+      `  --sireno-variant-${variantName}-bg: ${styles.background};`,
+    )
+    rootLines.push(
+      `  --sireno-variant-${variantName}-border: ${styles.border};`,
+    )
+    rootLines.push(
+      `  --sireno-variant-${variantName}-fg: ${styles.foreground};`,
+    )
+    rootLines.push(
+      `  --sireno-variant-${variantName}-glow: ${styles.glow ?? "0 0 0 transparent"};`,
+    )
+    const tokens = styles.tokens
+    for (const tokenKey of VARIANT_TOKEN_KEYS) {
+      const cssToken =
+        MANIFEST_TO_CSS_TOKEN[tokenKey] ??
+        tokenKey.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+      const themeValue =
+        colorTokens[tokenKey as keyof typeof colorTokens] ?? "#000000"
+      const variantValue =
+        tokens?.[tokenKey as keyof typeof tokens] ?? themeValue
+      rootLines.push(
+        `  --sireno-variant-${variantName}-${cssToken}: ${variantValue};`,
+      )
+    }
+  }
+  // Effect tokens — glow / shadow / blur, optional. Themes without effects
+  // still get sane defaults so component CSS never reads `undefined` for a
+  // token.
+  const effects = manifest.effects
+  rootLines.push(
+    `  --sireno-glow-sm: ${effects?.glow?.sm ?? "0 0 4px transparent"};`,
+  )
+  rootLines.push(
+    `  --sireno-glow-md: ${effects?.glow?.md ?? "0 0 12px transparent"};`,
+  )
+  rootLines.push(
+    `  --sireno-glow-lg: ${effects?.glow?.lg ?? "0 0 24px transparent"};`,
+  )
+  rootLines.push(
+    `  --sireno-shadow-soft: ${effects?.shadow?.soft ?? "0 1px 2px transparent"};`,
+  )
+  rootLines.push(
+    `  --sireno-shadow-hard: ${effects?.shadow?.hard ?? "0 4px 12px transparent"};`,
+  )
+  rootLines.push(`  --sireno-blur-sm: ${effects?.blur?.sm ?? "4px"};`)
+  rootLines.push(`  --sireno-blur-md: ${effects?.blur?.md ?? "10px"};`)
+  // Default pressed / holding glow hooks — every theme gets these for free
+  // (Gaps 10). Themes can override in their own stylesheet under @layer.
+  rootLines.push(`  --sireno-pressed-glow: var(--sireno-glow-md);`)
+  rootLines.push(`  --sireno-held-glow: var(--sireno-glow-lg);`)
+  rootLines.push("}")
+  parts.push(rootLines.join("\n"))
+
+  // Concatenated stylesheets — wrap in @layer so theme styles override
+  // built-in styles predictably (Tailwind v4 layer order is fixed:
+  // theme < base < components < utilities < user-overrides).
+  if (stylesheetContents.length > 0) {
+    parts.push(`@layer theme-override {\n${stylesheetContents.join("\n\n")}\n}`)
+  }
+
+  // @theme block emitted last — see comment above the @theme block.
+  parts.push(themeLines.join("\n"))
+
+  return parts.join("\n\n")
+}