@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/system/providers/session/windows.ts

@@ -0,0 +1,73 @@
+import type pino from "pino"
+
+import type { CommandExecutor } from "../shared"
+import { type SessionProvider, type SessionState } from "../session"
+
+export interface WindowsSessionDeps {
+  readonly executor: CommandExecutor
+  readonly logger: pino.Logger
+  readonly pollIntervalMs?: number
+}
+
+const toState = (locked: boolean): SessionState =>
+  locked ? "locked" : "unlocked"
+
+const PS_GET_LOGONUI = `if (Get-Process logonui -ErrorAction SilentlyContinue) { 'true' } else { 'false' }`
+
+const parseLockResult = (raw: string): boolean =>
+  raw.trim().toLowerCase() === "true"
+
+export const createWindowsSessionProvider = async (
+  deps: WindowsSessionDeps,
+): Promise<SessionProvider> => {
+  const listeners = new Set<(s: SessionState) => void>()
+  let state: SessionState = "unknown"
+  let stopped = false
+  const pollMs = deps.pollIntervalMs ?? 5_000
+
+  const tick = async (): Promise<SessionState> => {
+    try {
+      const result = await deps.executor.run(
+        "powershell",
+        ["-NoProfile", "-Command", PS_GET_LOGONUI],
+        { timeoutMs: 2_000 },
+      )
+      if (result.exitCode !== 0) return state
+      return toState(parseLockResult(result.stdout))
+    } catch (err) {
+      deps.logger.debug({ err }, "session: powershell failed")
+      return state
+    }
+  }
+
+  state = await tick()
+  let interval: ReturnType<typeof setInterval> | null = setInterval(() => {
+    if (stopped) return
+    void tick().then((s) => {
+      if (stopped) return
+      if (s !== state) {
+        state = s
+        for (const l of listeners) l(state)
+      }
+    })
+  }, pollMs)
+
+  return {
+    getState() {
+      return state
+    },
+    subscribe(handler) {
+      listeners.add(handler)
+      return () => {
+        listeners.delete(handler)
+      }
+    },
+    async stop() {
+      stopped = true
+      if (interval !== null) {
+        clearInterval(interval)
+        interval = null
+      }
+    },
+  }
+}

package/src/system/providers/session.ts

@@ -0,0 +1,89 @@
+import type pino from "pino"
+
+import { noopUnsubscribe } from "./shared"
+
+export type SessionState = "locked" | "unlocked" | "unknown"
+
+export interface SessionProvider {
+  getState(): SessionState
+  subscribe(handler: (state: SessionState) => void): () => void
+  stop(): Promise<void>
+}
+
+export const createNullSessionProvider = (
+  logger?: pino.Logger,
+): SessionProvider => {
+  if (logger) {
+    logger.warn(
+      { provider: "session" },
+      "OS session provider unavailable, using null provider",
+    )
+  }
+  return {
+    getState() {
+      return "unknown"
+    },
+    subscribe() {
+      return noopUnsubscribe
+    },
+    async stop() {
+      return
+    },
+  }
+}
+
+export interface CreateSessionProviderOptions {
+  readonly platform?: NodeJS.Platform
+  readonly dbus?: import("./shared").LinuxDbusBus
+  readonly executor?: import("./shared").CommandExecutor
+  readonly logger: pino.Logger
+  readonly idleMs?: number
+}
+
+export const createSessionProvider = async (
+  options: CreateSessionProviderOptions,
+): Promise<SessionProvider> => {
+  // ponytail: capture mode — force unlocked so screenshots show the real
+  // decks instead of the lock screen. Set by capture-decks.mjs.
+  if (process.env["SIRENO_CAPTURE_UNLOCKED"] === "1") {
+    return {
+      getState: () => "unlocked" as const,
+      subscribe: () => noopUnsubscribe,
+      stop: async () => {},
+    }
+  }
+  const platform = options.platform ?? process.platform
+  if (platform === "linux") {
+    // ponytail: let createLinuxSessionProvider self-own a dbus session bus when
+    // none is injected (mirrors active-app/wayland-gnome.ts:62-74). Returning a
+    // null provider here turned every Linux run into a silent no-op, which is
+    // why core:lock never fired.
+    const { createLinuxSessionProvider } = await import("./session/linux")
+    return createLinuxSessionProvider({
+      ...(options.dbus !== undefined ? { dbus: options.dbus } : {}),
+      logger: options.logger,
+      ...(options.idleMs !== undefined ? { idleMs: options.idleMs } : {}),
+    })
+  }
+  if (platform === "darwin") {
+    if (options.executor === undefined) {
+      return createNullSessionProvider(options.logger)
+    }
+    const { createDarwinSessionProvider } = await import("./session/darwin")
+    return createDarwinSessionProvider({
+      executor: options.executor,
+      logger: options.logger,
+    })
+  }
+  if (platform === "win32") {
+    if (options.executor === undefined) {
+      return createNullSessionProvider(options.logger)
+    }
+    const { createWindowsSessionProvider } = await import("./session/windows")
+    return createWindowsSessionProvider({
+      executor: options.executor,
+      logger: options.logger,
+    })
+  }
+  return createNullSessionProvider(options.logger)
+}

package/src/system/providers/shared.ts

@@ -0,0 +1,65 @@
+import type pino from "pino"
+
+import { ProviderError } from "./error"
+
+export interface CommandExecutor {
+  run(
+    command: string,
+    args: ReadonlyArray<string>,
+    options?: { timeoutMs?: number },
+  ): Promise<{ exitCode: number; stdout: string; stderr: string }>
+}
+
+export interface LinuxDbusBus {
+  getProxyObject(
+    serviceName: string,
+    objectPath: string,
+  ): Promise<LinuxDbusProxyObject>
+  disconnect?(): void
+}
+
+export interface LinuxDbusProxyObject {
+  getInterface(name: string): LinuxDbusInterface
+}
+
+export interface LinuxDbusInterface {
+  Eval?(script: string): Promise<unknown>
+  GetActive?(): Promise<boolean>
+  GetIdletime?(): Promise<number>
+  FocusClass?(): Promise<string>
+  FocusTitle?(): Promise<string>
+  on?(event: string, handler: (...args: unknown[]) => void): void
+  off?(event: string, handler: (...args: unknown[]) => void): void
+}
+
+export const withTimeout = async <T>(
+  promise: Promise<T>,
+  ms: number,
+): Promise<T> => {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new ProviderError("TIMEOUT", `Operation timed out after ${ms}ms`))
+    }, ms)
+  })
+  try {
+    return await Promise.race([promise, timeout])
+  } finally {
+    if (timer !== null) clearTimeout(timer)
+  }
+}
+
+export const noopUnsubscribe = (): void => undefined
+
+export const logNull = (
+  logger: pino.Logger | undefined,
+  name: string,
+  reason: string,
+): void => {
+  if (logger) {
+    logger.warn(
+      { provider: name, reason },
+      "OS provider unavailable, using null provider",
+    )
+  }
+}

package/src/system/requirements.ts

@@ -0,0 +1,235 @@
+import type { CommandExecutor } from "./providers/shared"
+import {
+  ACCESSIBILITY_HINT,
+  hasDarwinAccessibility,
+} from "./setup-wizard/probe"
+
+export type SystemCapability = "keyMacro" | "clipboard" | "notification"
+
+/**
+ * Stand-in used in `missingCommands` when the capability is blocked by an OS
+ * permission rather than a missing binary — there is nothing to install.
+ */
+export const PERMISSION_SENTINEL = "accessibility-permission"
+
+export interface CapabilityRequirement {
+  readonly name: SystemCapability
+  readonly commands: ReadonlyArray<string>
+  readonly reason: string
+}
+
+export interface CapabilityStatus {
+  readonly available: boolean
+  readonly commands: ReadonlyArray<string>
+  readonly missingCommands: ReadonlyArray<string>
+  readonly reason: string
+  readonly preferred: string
+}
+
+export type RequirementsCheckResult = Readonly<
+  Record<SystemCapability, CapabilityStatus>
+>
+
+export interface RequirementsCheckDeps {
+  readonly platform: string
+  readonly executor: CommandExecutor
+  readonly env?: NodeJS.ProcessEnv
+  // ponytail: fallback probe for stripped-PATH environments
+  // (systemd/launchd/IDE). `which` may return nothing even when the binary
+  // exists on disk at a non-default bin dir. The caller wires this with a
+  // statSync-based probe over `/usr/local/bin`, `~/.local/bin`, etc.
+  readonly extraFsProbe?: (command: string) => boolean
+}
+
+const capabilityConfig: Readonly<
+  Record<
+    SystemCapability,
+    {
+      readonly commands: ReadonlyArray<string>
+      readonly reason: string
+      readonly preferred: (platform: string, env: NodeJS.ProcessEnv) => string
+    }
+  >
+> = {
+  keyMacro: {
+    commands: [
+      "ydotool",
+      "wtype",
+      "xdotool",
+      "dotool",
+      "osascript",
+      "powershell",
+    ],
+    reason:
+      "type:// keystrokes need a key input tool. Install ydotool (works on most compositors via uinput) or wtype (wlroots compositors only). macOS uses osascript; Windows uses PowerShell with Win32 SendInput.",
+    preferred: (platform) => {
+      if (platform === "darwin") return "osascript"
+      if (platform === "win32") return "powershell"
+      return "ydotool"
+    },
+  },
+  clipboard: {
+    commands: ["wl-copy", "xclip", "xsel", "pbcopy"],
+    reason:
+      "non-ASCII literal text (emoji, accented letters, CJK) needs a clipboard tool because ydotool's `type` does not handle non-BMP characters. Install the wl-clipboard package (provides wl-copy) on Wayland; xclip / xsel work on X11; macOS ships pbcopy.",
+    preferred: (platform, env) => {
+      if (platform === "darwin") return "pbcopy"
+      return env["WAYLAND_DISPLAY"] === undefined &&
+        env["DISPLAY"] !== undefined
+        ? "xclip"
+        : "wl-copy"
+    },
+  },
+  notification: {
+    commands: ["notify-send", "osascript", "powershell"],
+    reason:
+      "OS-level notifications (toast/notification-center) need a host tool. Linux uses notify-send (libnotify); macOS uses osascript; Windows uses PowerShell with System.Windows.Forms.NotifyIcon.",
+    preferred: (platform) => {
+      if (platform === "darwin") return "osascript"
+      if (platform === "win32") return "powershell"
+      return "notify-send"
+    },
+  },
+}
+
+// ponytail: `command` is a POSIX shell builtin, not a binary — execFile can't
+// spawn it, so the old `executor.run("command", ["-v", x])` failed for EVERY
+// candidate and the probe silently degraded to the `--version` fallback (which
+// osascript, pbcopy and clip don't even support). Wrap in `sh -c`, matching
+// setup-wizard/probe.ts, and shell-quote so the argument stays one token.
+const probeCommandV = async (
+  executor: CommandExecutor,
+  command: string,
+): Promise<boolean> => {
+  const quoted = `'${command.replaceAll(`'`, `'\\''`)}'`
+  const result = await executor.run("sh", ["-c", `command -v ${quoted}`])
+  return result.exitCode === 0 && result.stdout.trim().length > 0
+}
+
+const probeVersion = async (
+  executor: CommandExecutor,
+  command: string,
+): Promise<boolean> => {
+  try {
+    const result = await executor.run(command, ["--version"], {
+      timeoutMs: 1_000,
+    })
+    return result.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+const probeCommand = async (
+  executor: CommandExecutor,
+  command: string,
+  extraFsProbe?: (command: string) => boolean,
+): Promise<boolean> => {
+  if (await probeCommandV(executor, command)) return true
+  if (extraFsProbe?.(command) === true) return true
+  return await probeVersion(executor, command)
+}
+
+// ponytail: the clipboard candidate list is session-dependent on Linux, so it
+// can't just be `config.commands`. The old ternary keyed off `preferred ===
+// "xclip"` and sent every other platform down the `["wl-copy"]` branch — so on
+// macOS the probe looked for a Wayland tool, never for pbcopy, and every run
+// logged "clipboard: none of wl-copy found" on a machine that ships pbcopy.
+const clipboardCandidates = (
+  platform: string,
+  preferred: string,
+): ReadonlyArray<string> => {
+  if (platform === "darwin") return ["pbcopy"]
+  if (platform === "win32") return ["clip"]
+  return preferred === "xclip" ? ["xclip", "xsel"] : ["wl-copy"]
+}
+
+export const checkRequirements = async ({
+  platform,
+  executor,
+  env = process.env,
+  extraFsProbe,
+}: RequirementsCheckDeps): Promise<RequirementsCheckResult> => {
+  const result: Partial<Record<SystemCapability, CapabilityStatus>> = {}
+
+  for (const [name, config] of Object.entries(capabilityConfig)) {
+    const commands =
+      name === "clipboard"
+        ? clipboardCandidates(platform, config.preferred(platform, env))
+        : config.commands
+    const availability = await Promise.all(
+      commands.map((command) => probeCommand(executor, command, extraFsProbe)),
+    )
+    const found = commands.filter((_, index) => availability[index])
+    const missing = commands.filter((_, index) => !availability[index])
+    result[name as SystemCapability] = {
+      available: found.length > 0,
+      commands: found,
+      missingCommands: missing,
+      reason: config.reason,
+      preferred: config.preferred(platform, env),
+    }
+  }
+
+  // ponytail: darwin-only. `osascript` ships with macOS, so probing for the
+  // binary always succeeds and the daemon started reporting keyMacro as
+  // available while every keystroke failed with -1719/1002. The setup wizard
+  // already checks the Accessibility grant; without the same check here the
+  // runtime never warned at boot, and a tapped macro button showed a generic
+  // "action-failed" tile instead of being pre-empted with the real reason.
+  // Linux and Windows are untouched — they return before this block.
+  if (platform === "darwin") {
+    const keyMacro = result.keyMacro
+    if (
+      keyMacro?.available === true &&
+      !(await hasDarwinAccessibility(executor))
+    ) {
+      result.keyMacro = {
+        ...keyMacro,
+        available: false,
+        missingCommands: [PERMISSION_SENTINEL],
+        reason: `osascript is installed but has no Accessibility permission — ${ACCESSIBILITY_HINT}`,
+      }
+    }
+  }
+
+  return result as RequirementsCheckResult
+}
+
+const CAPABILITY_LABEL: Readonly<Record<SystemCapability, string>> = {
+  keyMacro: "Key macros",
+  clipboard: "Clipboard",
+  notification: "Notifications",
+}
+
+export const formatCapabilityWarning = (
+  name: SystemCapability,
+  status: CapabilityStatus,
+): string => {
+  const label = CAPABILITY_LABEL[name]
+  if (status.available) {
+    const missingPreferred =
+      status.preferred.length > 0 &&
+      !status.commands.includes(status.preferred) &&
+      status.missingCommands.length > 0
+    if (missingPreferred) {
+      return `${label}: using ${status.commands.join(", ")} as fallback; preferred ${status.preferred} is missing — ${status.reason}`
+    }
+    return ""
+  }
+  // ponytail: "none of accessibility-permission found" reads like a missing
+  // binary. A denied OS permission is not something the user can install, so
+  // state it as a permission and let the reason carry the remedy.
+  if (status.missingCommands.includes(PERMISSION_SENTINEL)) {
+    return `${label}: ${status.reason}`
+  }
+  return `${label}: none of ${status.missingCommands.join(", ")} found — ${status.reason}`
+}
+
+export const getRequiredCapability = (
+  action: string,
+): SystemCapability | null => {
+  if (action.startsWith("type://")) return "keyMacro"
+  if (action.startsWith("macro://")) return "keyMacro"
+  return null
+}

package/src/system/setup-wizard/config-seed.ts

@@ -0,0 +1,30 @@
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export interface ConfigSeedResult {
+  readonly seeded: boolean
+  readonly targetPath: string
+  readonly sourcePath: string
+}
+
+const here = (): string => dirname(fileURLToPath(import.meta.url))
+
+// ponytail: seed `starter-config.yml`, NOT `default-config.yml`. The latter is
+// the repo's own dev config — it carries `!include demos/*.yml` and
+// `src: ./packages/addons/*`, both resolved relative to the config file. Copied
+// to ~/.config/sirenodeck/ those paths point at directories that don't exist,
+// so the very first `sirenodeck start` after the wizard died with
+// "Included file not found". The starter config is self-contained by design.
+export const defaultConfigSourcePath = (): string =>
+  join(here(), "..", "..", "..", "config", "starter-config.yml")
+
+export const seedDefaultConfig = (targetPath: string): ConfigSeedResult => {
+  const sourcePath = defaultConfigSourcePath()
+  mkdirSync(dirname(targetPath), { recursive: true })
+  copyFileSync(sourcePath, targetPath)
+  writeFileSync(targetPath, readFileSync(targetPath, "utf8"), {
+    mode: 0o600,
+  })
+  return { seeded: true, targetPath, sourcePath }
+}