@sirenodeck/sirenodeck 0.1.1-alpha.0

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

@@ -0,0 +1,275 @@
+import type {
+  CapabilityName,
+  CapabilityProbe,
+  InstallStep,
+  InstallStepResult,
+  SystemReport,
+  SystemReportSummary,
+} from "./types"
+
+const SESSION_LABEL: Readonly<Record<string, string>> = {
+  wayland: "Wayland",
+  x11: "X11",
+  unknown: "unknown",
+}
+
+// ponytail: ANSI helpers, no dep. `colorette` would pull in transitive types
+// for a single use site — terminal escape sequences are stable. Returns the
+// input untouched when stdout is not a TTY so piped output stays clean.
+const useColor = (): boolean =>
+  Boolean(process.stdout.isTTY) && process.env["NO_COLOR"] === undefined
+
+const ESC = "\u001b["
+export const color = {
+  green: (s: string): string => (useColor() ? `${ESC}32m${s}${ESC}0m` : s),
+  red: (s: string): string => (useColor() ? `${ESC}31m${s}${ESC}0m` : s),
+  yellow: (s: string): string => (useColor() ? `${ESC}33m${s}${ESC}0m` : s),
+  dim: (s: string): string => (useColor() ? `${ESC}2m${s}${ESC}0m` : s),
+}
+
+export const stripAnsi = (s: string): string =>
+  s.replace(/\u001b\[[0-9;]*m/g, "")
+
+export const summarizeReport = (report: SystemReport): SystemReportSummary => {
+  const missingCapabilities: Array<
+    "keyMacro" | "clipboard" | "notification" | "activeApp"
+  > = []
+  for (const [name, cap] of Object.entries(report.capabilities)) {
+    if (!cap.available) {
+      missingCapabilities.push(
+        name as "keyMacro" | "clipboard" | "notification" | "activeApp",
+      )
+    }
+  }
+
+  const lines: string[] = []
+  const ok =
+    missingCapabilities.length === 0 &&
+    report.udev.rulesInstalled &&
+    report.config.exists
+
+  lines.push(
+    `Platform: ${report.platform} (${SESSION_LABEL[report.session] ?? "unknown"} session)`,
+  )
+  lines.push(`Package manager: ${report.packageManager}`)
+  lines.push(`Config target: ${report.config.path}`)
+
+  if (missingCapabilities.length === 0) {
+    lines.push("Capabilities: all present")
+  } else {
+    // ponytail: same two problems the interactive panel had — internal keys
+    // ("keyMacro") instead of names a user recognises, and the full remedy
+    // repeated once per capability that happens to need the same grant. Lead
+    // with the capability and print each distinct remedy once.
+    lines.push("Missing capabilities:")
+    const remedies: string[] = []
+    for (const name of missingCapabilities) {
+      const cap = report.capabilities[name]
+      const label = CAPABILITY_LABEL[name]
+      const permission = cap.permission
+      const blocked =
+        cap.toolInstalled && permission !== null && !permission.granted
+      const state = blocked
+        ? `${cap.preferred} installed, ${permission.label} permission not granted`
+        : `${cap.preferred} not installed`
+      const remedy = blocked
+        ? `${permission.label}: ${permission.hint}`
+        : cap.reason
+      if (!remedies.includes(remedy)) remedies.push(remedy)
+      lines.push(`  - ${label}: ${state} [${remedies.indexOf(remedy) + 1}]`)
+    }
+    remedies.forEach((remedy, index) => {
+      lines.push(`  [${index + 1}] ${remedy}`)
+    })
+  }
+
+  if (report.platform === "linux") {
+    lines.push(
+      report.udev.rulesInstalled
+        ? "udev rules: installed at " + report.udev.rulesPath
+        : "udev rules: missing at " + report.udev.rulesPath,
+    )
+    lines.push(
+      report.udev.streamDeckConnected
+        ? "Stream Deck: connected (" +
+            report.udev.matchedProductIds.join(", ") +
+            ")"
+        : "Stream Deck: not detected",
+    )
+  }
+
+  lines.push(
+    report.config.exists
+      ? "Config: present"
+      : "Config: missing (run `sirenodeck system-requirements` to seed)",
+  )
+
+  return {
+    ok,
+    session: report.session,
+    packageManager: report.packageManager,
+    missingCapabilities,
+    udevMissing: !report.udev.rulesInstalled,
+    configMissing: !report.config.exists,
+    configPath: report.config.path,
+    streamDeckConnected: report.udev.streamDeckConnected,
+    lines,
+  }
+}
+
+// ponytail: the panel used to lead with the tool name, so macOS printed
+// "osascript" three times — once per capability that happens to be driven by
+// AppleScript — and repeated the same 200-character Accessibility hint twice.
+// The capability is what the user cares about and the tool is an
+// implementation detail, so capability now leads and the long hints collapse
+// into numbered footnotes shared by every row that needs them.
+const CAPABILITY_LABEL: Readonly<Record<CapabilityName, string>> = {
+  keyMacro: "Key macros",
+  clipboard: "Clipboard",
+  notification: "Notifications",
+  activeApp: "Active app",
+}
+
+const CAPABILITY_ORDER: ReadonlyArray<CapabilityName> = [
+  "keyMacro",
+  "clipboard",
+  "notification",
+  "activeApp",
+]
+
+const FOOTNOTE_WIDTH = 64
+
+const wrapText = (text: string, width: number): string[] => {
+  const words = text.split(/\s+/).filter((w) => w.length > 0)
+  const lines: string[] = []
+  let current = ""
+  for (const word of words) {
+    if (current.length === 0) {
+      current = word
+    } else if (current.length + 1 + word.length <= width) {
+      current = `${current} ${word}`
+    } else {
+      lines.push(current)
+      current = word
+    }
+  }
+  if (current.length > 0) lines.push(current)
+  return lines.length > 0 ? lines : [""]
+}
+
+interface CapabilityRow {
+  readonly mark: string
+  readonly label: string
+  readonly tool: string
+  readonly status: string
+  readonly note: number | null
+}
+
+/**
+ * Splits a capability into the two independent facts the old renderer
+ * conflated: whether the tool is installed, and whether it has the permission
+ * it needs. A denied grant is not "Not installed".
+ */
+const describeCapability = (
+  cap: CapabilityProbe,
+): { status: string; detail: string | null } => {
+  if (!cap.toolInstalled) {
+    return { status: color.red("not installed"), detail: cap.reason }
+  }
+  const permission = cap.permission
+  if (permission === null) {
+    return { status: color.green("installed"), detail: null }
+  }
+  if (permission.granted) {
+    return {
+      status: `${color.green("installed")}${color.dim(" · ")}${color.green(`${permission.label} granted`)}`,
+      detail: null,
+    }
+  }
+  return {
+    status: `${color.green("installed")}${color.dim(" · ")}${color.red(`${permission.label} not granted`)}`,
+    detail: `${permission.label} permission — ${permission.hint}.`,
+  }
+}
+
+export const formatCapabilityPanel = (
+  capabilities: Readonly<Record<CapabilityName, CapabilityProbe>>,
+): string => {
+  const footnotes: string[] = []
+  const footnoteFor = (detail: string): number => {
+    const existing = footnotes.indexOf(detail)
+    if (existing !== -1) return existing + 1
+    footnotes.push(detail)
+    return footnotes.length
+  }
+
+  const rows: CapabilityRow[] = []
+  for (const name of CAPABILITY_ORDER) {
+    const cap = capabilities[name]
+    if (cap === undefined) continue
+    const { status, detail } = describeCapability(cap)
+    rows.push({
+      mark: cap.available ? color.green("●") : color.red("○"),
+      label: CAPABILITY_LABEL[name],
+      tool: cap.preferred,
+      status,
+      note: detail === null ? null : footnoteFor(detail),
+    })
+  }
+
+  const labelWidth = Math.max(...rows.map((r) => r.label.length))
+  const toolWidth = Math.max(...rows.map((r) => r.tool.length))
+
+  const lines = rows.map((r) => {
+    const label = `${r.label}:`.padEnd(labelWidth + 2)
+    const tool = color.dim(r.tool.padEnd(toolWidth))
+    const marker = r.note === null ? "" : color.dim(` [${r.note}]`)
+    return `${r.mark} ${label} ${tool}  ${r.status}${marker}`
+  })
+
+  if (footnotes.length > 0) {
+    lines.push("")
+    footnotes.forEach((detail, index) => {
+      const wrapped = wrapText(detail, FOOTNOTE_WIDTH)
+      wrapped.forEach((line, lineIndex) => {
+        lines.push(
+          lineIndex === 0
+            ? `${color.dim(`[${index + 1}]`)} ${line}`
+            : `    ${line}`,
+        )
+      })
+    })
+  }
+
+  return lines.join("\n")
+}
+
+export const formatStepInstructions = (step: InstallStep): string => {
+  if (step.manualInstructions.length > 0) return step.manualInstructions
+  if (step.packageManager === "none") {
+    return `No package manager detected. Install manually: ${step.packages.join(", ")}.`
+  }
+  const verb =
+    step.packageManager === "brew"
+      ? "brew install"
+      : `sudo ${step.packageManager} install -y`
+  return `${verb} ${step.packages.join(" ")}`
+}
+
+export const formatSummaryLine = (line: string): string => line
+
+export const formatResultLine = (
+  step: InstallStep,
+  result: InstallStepResult,
+): string => {
+  switch (result) {
+    case "installed":
+      return `${color.green("✓")} ${step.title}`
+    case "skipped":
+      return `${color.dim("·")} ${step.title} ${color.dim("(skipped)")}`
+    case "failed":
+      return `${color.red("✗")} ${step.title} ${color.red(`(failed — see ${step.manualInstructions.length > 0 ? "instructions below" : "logs"})`)}`
+    case "manual":
+      return `${color.dim("→")} ${step.title} ${color.dim(`(manual — ${step.manualInstructions.slice(0, 60)}…)`)}`
+  }
+}

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

@@ -0,0 +1,45 @@
+export {
+  type CapabilityName,
+  type CapabilityProbe,
+  type ConfigProbe,
+  type DesktopSession,
+  type InstallStep,
+  type InstallStepResult,
+  type PackageManager,
+  type ProbeDeps,
+  type SystemReport,
+  type SystemReportSummary,
+  type UdevProbe,
+  type WizardOutcome,
+  UDEV_RULES_PATH,
+} from "./types"
+
+export {
+  probeAll,
+  ACCESSIBILITY_HINT,
+  ACCESSIBILITY_SETTINGS_URL,
+  hasDarwinAccessibility,
+} from "./probe"
+export { probeAllCached, resetProbeCache } from "./probe-cache"
+export {
+  probeMediaAccess,
+  probeCommandExecution,
+  probeInternetAccess,
+  type RuntimeFeatureProbe,
+} from "./runtime-features"
+export {
+  buildInstallPlan,
+  needsConfigSeed,
+  DARWIN_ACCESSIBILITY_STEP_ID,
+} from "./plan"
+export {
+  formatCapabilityPanel,
+  formatResultLine,
+  formatStepInstructions,
+  formatSummaryLine,
+  summarizeReport,
+} from "./format"
+export { openSettingsUrl } from "./open-settings"
+export { defaultConfigSourcePath, seedDefaultConfig } from "./config-seed"
+export { isSudoNopasswd, runWithSudo, capturePassword } from "./sudo"
+export type { SudoRunResult } from "./sudo"

package/src/system/setup-wizard/open-settings.ts

@@ -0,0 +1,26 @@
+import type { CommandExecutor } from "../providers/shared"
+
+/**
+ * Opens a System Settings pane by its `x-apple.systempreferences:` deep link.
+ *
+ * ponytail: the Accessibility grant is the one setup step no package manager
+ * can perform, and the old flow just printed a System Settings → Privacy &
+ * Security → Accessibility breadcrumb and left the user to navigate it. macOS
+ * can jump straight to the pane, so offer that instead of prose.
+ *
+ * Returns false (never throws) on non-darwin platforms or when `open` fails —
+ * the caller falls back to printing the manual instructions.
+ */
+export const openSettingsUrl = async (
+  executor: CommandExecutor,
+  url: string,
+  platform: string = process.platform,
+): Promise<boolean> => {
+  if (platform !== "darwin") return false
+  try {
+    const result = await executor.run("open", [url])
+    return result.exitCode === 0
+  } catch {
+    return false
+  }
+}

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

@@ -0,0 +1,230 @@
+import { UDEV_RULES } from "../../device/linux-udev"
+import { EXTENSION_INSTALL_URL } from "../providers/active-app/wayland-gnome"
+import {
+  type CapabilityName,
+  type InstallStep,
+  type PackageManager,
+  type SystemReport,
+  ACCESSIBILITY_SETTINGS_URL,
+  UDEV_RULES_PATH,
+} from "./types"
+
+interface PackageMap {
+  readonly apt: ReadonlyArray<string>
+  readonly dnf: ReadonlyArray<string>
+  readonly pacman: ReadonlyArray<string>
+  readonly zypper: ReadonlyArray<string>
+  readonly brew: ReadonlyArray<string>
+}
+
+const KEYMACRO_PACKAGES: PackageMap = {
+  apt: ["ydotool"],
+  dnf: ["ydotool"],
+  pacman: ["ydotool"],
+  zypper: ["ydotool"],
+  brew: [],
+}
+
+const CLIPBOARD_WAYLAND_PACKAGES: PackageMap = {
+  apt: ["wl-clipboard"],
+  dnf: ["wl-clipboard"],
+  pacman: ["wl-clipboard"],
+  zypper: ["wl-clipboard"],
+  brew: [],
+}
+
+const CLIPBOARD_X11_PACKAGES: PackageMap = {
+  apt: ["xclip"],
+  dnf: ["xclip"],
+  pacman: ["xclip"],
+  zypper: ["xclip"],
+  brew: [],
+}
+
+const NOTIFICATION_PACKAGES: PackageMap = {
+  apt: ["libnotify-bin"],
+  dnf: ["libnotify"],
+  pacman: ["libnotify"],
+  zypper: ["libnotify"],
+  brew: [],
+}
+
+const ACTIVEAPP_X11_PACKAGES: PackageMap = {
+  apt: ["xdotool", "x11-utils"],
+  dnf: ["xdotool", "xorg-x11-utils"],
+  pacman: ["xdotool"],
+  zypper: ["xdotool"],
+  brew: [],
+}
+
+const resolvePackages = (
+  map: PackageMap,
+  pm: PackageManager,
+): ReadonlyArray<string> => {
+  if (pm === "none") return []
+  return map[pm]
+}
+
+const capId = (name: CapabilityName): string => `cap:${name}`
+
+const udevInstruction = (rulesPath: string): string =>
+  `sudo tee ${rulesPath} > /dev/null <<'EOF'
+${UDEV_RULES.trimEnd()}
+EOF
+sudo udevadm control --reload-rules && sudo udevadm trigger`
+
+const buildCapabilityStep = (
+  name: CapabilityName,
+  title: string,
+  description: string,
+  packages: ReadonlyArray<string>,
+  pm: PackageManager,
+  verifyCommand: string,
+): InstallStep => ({
+  id: capId(name),
+  capability: name,
+  title,
+  description,
+  packageManager: pm,
+  packages,
+  sudo: pm !== "brew",
+  manualOnly: packages.length === 0,
+  manualInstructions:
+    packages.length === 0
+      ? `No supported package manager found for this platform. Install ${name} manually for your distro.`
+      : pm === "none"
+        ? `No package manager detected. Install manually: ${packages.join(", ")}.`
+        : "",
+  ...(verifyCommand.length > 0 ? { verifyCommand } : {}),
+})
+
+const buildUdevStep = (streamDeckConnected: boolean): InstallStep => ({
+  id: "udev:rules",
+  capability: "udev",
+  title: "Stream Deck udev rules",
+  description: streamDeckConnected
+    ? "Stream Deck detected but udev rules are missing. Without them, the daemon can't access the device without sudo."
+    : "Install udev rules so a Stream Deck can be accessed without sudo when you plug one in.",
+  packageManager: "none",
+  packages: [],
+  sudo: true,
+  manualOnly: false,
+  manualInstructions: udevInstruction(UDEV_RULES_PATH),
+  verifyCommand: `test -f ${UDEV_RULES_PATH} && echo installed || echo missing`,
+})
+
+const buildGnomeExtensionStep = (): InstallStep => ({
+  id: "cap:activeApp:gnome-extension",
+  capability: "activeApp",
+  title: "GNOME 'Window Calls Extended' extension",
+  description: `Wayland GNOME requires this extension for active-app detection. Install from ${EXTENSION_INSTALL_URL}.`,
+  packageManager: "none",
+  packages: [],
+  sudo: false,
+  manualOnly: true,
+  manualInstructions: `Open ${EXTENSION_INSTALL_URL} in your browser, toggle the extension ON, then log out / log in (or restart GNOME Shell).`,
+  verifyCommand: undefined,
+})
+
+// ponytail: macOS UI scripting is gated by a TCC grant that no package manager
+// can install, so this is manual-only. Before this step the wizard had no
+// darwin branch at all — it printed "Capabilities: all present" while every
+// keystroke silently failed with -1719.
+export const DARWIN_ACCESSIBILITY_STEP_ID = "cap:darwin:accessibility"
+
+const buildDarwinAccessibilityStep = (): InstallStep => ({
+  id: DARWIN_ACCESSIBILITY_STEP_ID,
+  capability: "keyMacro",
+  title: "macOS Accessibility permission",
+  description:
+    "Key macros and window-title detection drive the UI through AppleScript, which macOS gates behind Accessibility.",
+  packageManager: "none",
+  packages: [],
+  sudo: false,
+  manualOnly: true,
+  manualInstructions: `Open the pane directly: open "${ACCESSIBILITY_SETTINGS_URL}"
+Then enable the app running sirenodeck (your terminal, or SirenoDeck.app) and restart it.
+Verify with: osascript -e 'tell application "System Events" to get UI elements enabled'  # should print true`,
+  verifyCommand: `osascript -e 'tell application "System Events" to get UI elements enabled'`,
+})
+
+export const buildInstallPlan = (report: SystemReport): InstallStep[] => {
+  const steps: InstallStep[] = []
+  const { platform, session, packageManager, capabilities, udev } = report
+
+  if (
+    platform === "darwin" &&
+    (!capabilities.keyMacro.available || !capabilities.activeApp.available)
+  ) {
+    steps.push(buildDarwinAccessibilityStep())
+  }
+
+  if (capabilities.keyMacro.missing.length > 0 && platform === "linux") {
+    steps.push(
+      buildCapabilityStep(
+        "keyMacro",
+        "Key macro tool (ydotool)",
+        capabilities.keyMacro.reason,
+        resolvePackages(KEYMACRO_PACKAGES, packageManager),
+        packageManager,
+        "which ydotool || which wtype || which xdotool",
+      ),
+    )
+  }
+
+  if (capabilities.clipboard.missing.length > 0 && platform === "linux") {
+    const map =
+      session === "wayland"
+        ? CLIPBOARD_WAYLAND_PACKAGES
+        : CLIPBOARD_X11_PACKAGES
+    steps.push(
+      buildCapabilityStep(
+        "clipboard",
+        session === "wayland" ? "wl-clipboard (wl-copy)" : "xclip",
+        capabilities.clipboard.reason,
+        resolvePackages(map, packageManager),
+        packageManager,
+        session === "wayland" ? "which wl-copy" : "which xclip",
+      ),
+    )
+  }
+
+  if (capabilities.notification.missing.length > 0 && platform === "linux") {
+    steps.push(
+      buildCapabilityStep(
+        "notification",
+        "Notification tool (notify-send)",
+        capabilities.notification.reason,
+        resolvePackages(NOTIFICATION_PACKAGES, packageManager),
+        packageManager,
+        "which notify-send",
+      ),
+    )
+  }
+
+  if (capabilities.activeApp.missing.length > 0 && platform === "linux") {
+    if (session === "wayland") {
+      steps.push(buildGnomeExtensionStep())
+    } else if (session === "x11") {
+      steps.push(
+        buildCapabilityStep(
+          "activeApp",
+          "Active-app detection (xdotool, xprop)",
+          capabilities.activeApp.reason,
+          resolvePackages(ACTIVEAPP_X11_PACKAGES, packageManager),
+          packageManager,
+          "which xdotool",
+        ),
+      )
+    }
+  }
+
+  if (platform === "linux" && !udev.rulesInstalled) {
+    steps.push(buildUdevStep(udev.streamDeckConnected))
+  }
+
+  return steps
+}
+
+export const needsConfigSeed = (report: SystemReport): boolean =>
+  !report.config.exists

package/src/system/setup-wizard/probe-cache.ts

@@ -0,0 +1,34 @@
+import { probeAll, type ProbeDeps, type SystemReport } from "."
+
+let cached: { report: SystemReport; at: number; key: string } | null = null
+const DEFAULT_TTL_MS = 5_000
+
+// ponytail: the config path is the one dep that differs between two call sites
+// in the same run — the banner probes the XDG default while the first-run gate
+// probes the explicit --config. Keying on it stops the first probe's
+// "Config: missing" from being replayed to the second.
+const cacheKey = (deps: ProbeDeps): string =>
+  `${deps.platform}\u0000${deps.xdgConfigHome}\u0000${deps.configPath ?? ""}`
+
+// ponytail: single-slot TTL cache. probeAll runs subprocesses (which, sudo,
+// lsusb, ...); the startup banner and runFirstRunCheckIfNeeded both probe the
+// same machine within ms of each other — caching avoids paying for it twice.
+// Single-slot because a CLI invocation probes one machine. Reset between runs
+// via resetProbeCache() for tests.
+export const probeAllCached = async (
+  deps: ProbeDeps,
+  ttlMs: number = DEFAULT_TTL_MS,
+): Promise<SystemReport> => {
+  const now = Date.now()
+  const key = cacheKey(deps)
+  if (cached !== null && cached.key === key && now - cached.at < ttlMs) {
+    return cached.report
+  }
+  const report = await probeAll(deps)
+  cached = { report, at: now, key }
+  return report
+}
+
+export const resetProbeCache = (): void => {
+  cached = null
+}