@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/system/providers/key-macro.ts

@@ -0,0 +1,79 @@
+import type pino from "pino"
+
+import { ProviderError } from "./error"
+import { type CommandExecutor } from "./shared"
+
+export interface KeyMacroProvider {
+  sendKey(comboOrText: string): Promise<void>
+  stop(): Promise<void>
+}
+
+export { isValidKey, knownKeys, parseCombo } from "./key-macro/parser"
+export type { ParsedCombo } from "./key-macro/parser"
+
+export const createNullKeyMacroProvider = (
+  logger?: pino.Logger,
+): KeyMacroProvider => {
+  if (logger) {
+    logger.warn(
+      { provider: "key-macro" },
+      "OS key-macro provider unavailable, sendKey will throw ProviderError",
+    )
+  }
+  return {
+    async sendKey(_comboOrText: string): Promise<void> {
+      throw new ProviderError(
+        "NOT_AVAILABLE",
+        "Key-macro provider not available on this platform",
+      )
+    },
+    async stop() {
+      return
+    },
+  }
+}
+
+export interface CreateKeyMacroProviderOptions {
+  readonly platform?: NodeJS.Platform
+  readonly executor: CommandExecutor
+  readonly env: Readonly<Record<string, string>>
+  readonly logger: pino.Logger
+  readonly extraFsProbe?: (tool: string) => boolean
+}
+
+export const createKeyMacroProvider = async (
+  options: CreateKeyMacroProviderOptions,
+): Promise<KeyMacroProvider> => {
+  const platform = options.platform ?? process.platform
+  if (platform === "linux") {
+    const { createLinuxKeyMacroProvider } = await import("./key-macro/linux")
+    return createLinuxKeyMacroProvider({
+      executor: options.executor,
+      env: options.env,
+      logger: options.logger,
+      ...(options.extraFsProbe !== undefined
+        ? { extraFsProbe: options.extraFsProbe }
+        : {}),
+    })
+  }
+  if (platform === "darwin") {
+    const { createDarwinKeyMacroProvider } = await import("./key-macro/darwin")
+    return createDarwinKeyMacroProvider({
+      executor: options.executor,
+      logger: options.logger,
+    })
+  }
+  if (platform === "win32") {
+    const { createWindowsKeyMacroProvider } =
+      await import("./key-macro/windows")
+    return createWindowsKeyMacroProvider({
+      executor: options.executor,
+      logger: options.logger,
+    })
+  }
+  void createNullKeyMacroProvider(options.logger)
+  throw new ProviderError(
+    "UNSUPPORTED_PLATFORM",
+    `Key-macro provider not implemented for platform '${platform}' in this build`,
+  )
+}

package/src/system/providers/notification/darwin.ts

@@ -0,0 +1,36 @@
+import { type CommandExecutor } from "../shared"
+import type { NotificationProvider } from "../notification"
+
+export interface DarwinNotificationDeps {
+  readonly executor: CommandExecutor
+  readonly soundPath?: string
+}
+
+const escapeForAppleScript = (value: string): string =>
+  value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+
+export const createDarwinNotificationProvider = async (
+  deps: DarwinNotificationDeps,
+): Promise<NotificationProvider> => {
+  return {
+    async notify(args) {
+      const script = `display notification "${escapeForAppleScript(args.body)}" with title "${escapeForAppleScript(args.title)}"`
+      try {
+        const result = await deps.executor.run("osascript", ["-e", script])
+        if (result.exitCode !== 0) {
+          // swallow — osascript may fail in headless contexts; notification is best-effort
+        }
+      } catch {
+        // best-effort; never throw
+      }
+
+      if (args.sound === true && deps.soundPath !== undefined) {
+        try {
+          await deps.executor.run("afplay", [deps.soundPath])
+        } catch {
+          // best-effort
+        }
+      }
+    },
+  }
+}

package/src/system/providers/notification/linux.ts

@@ -0,0 +1,115 @@
+import type pino from "pino"
+
+import { type CommandExecutor, withTimeout } from "../shared"
+import type { NotificationProvider } from "../notification"
+
+export interface LinuxNotificationDeps {
+  readonly executor: CommandExecutor
+  readonly logger: pino.Logger
+  readonly timeoutMs?: number
+  readonly extraFsProbe?: (tool: string) => boolean
+  readonly soundPath?: string
+}
+
+const NOTIFY_SEND_TOOL = "notify-send"
+const FFPLAY_TOOL = "ffplay"
+const PAPLAY_TOOL = "paplay"
+const DEFAULT_TIMEOUT_MS = 2_000
+const SOUND_TIMEOUT_MS = 5_000
+
+const probeTool = async (
+  executor: CommandExecutor,
+  tool: string,
+  extraFsProbe?: (tool: string) => boolean,
+): Promise<boolean> => {
+  const result = await executor.run("which", [tool])
+  if (result.exitCode === 0 && result.stdout.trim().length > 0) return true
+  return extraFsProbe?.(tool) === true
+}
+
+const shellQuote = (value: string): string =>
+  `'${value.replace(/'/g, "'\\''")}'`
+
+export const createLinuxNotificationProvider = async (
+  deps: LinuxNotificationDeps,
+): Promise<NotificationProvider> => {
+  const notifySendOk = await probeTool(
+    deps.executor,
+    NOTIFY_SEND_TOOL,
+    deps.extraFsProbe,
+  )
+  if (!notifySendOk) {
+    deps.logger.warn(
+      {},
+      "linux notification: notify-send not found; notify() will be a no-op",
+    )
+    return {
+      async notify() {
+        return
+      },
+    }
+  }
+
+  const ffplayOk = await probeTool(
+    deps.executor,
+    FFPLAY_TOOL,
+    deps.extraFsProbe,
+  )
+  const paplayOk =
+    !ffplayOk &&
+    (await probeTool(deps.executor, PAPLAY_TOOL, deps.extraFsProbe))
+  const soundTool: string | null = ffplayOk
+    ? FFPLAY_TOOL
+    : paplayOk
+      ? PAPLAY_TOOL
+      : null
+
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  return {
+    async notify(args) {
+      const sendArgs = [
+        "-t",
+        "5000",
+        shellQuote(args.title),
+        shellQuote(args.body),
+      ]
+      try {
+        const result = await withTimeout(
+          deps.executor.run(NOTIFY_SEND_TOOL, sendArgs),
+          timeoutMs,
+        )
+        if (result.exitCode !== 0) {
+          deps.logger.warn(
+            { stderr: result.stderr.trim() },
+            "linux notification: notify-send returned non-zero",
+          )
+        }
+      } catch (err) {
+        deps.logger.warn({ err }, "linux notification: notify-send failed")
+      }
+
+      if (
+        args.sound === true &&
+        deps.soundPath !== undefined &&
+        soundTool !== null
+      ) {
+        try {
+          await withTimeout(
+            deps.executor.run(soundTool, [
+              "-nodisp",
+              "-autoexit",
+              deps.soundPath,
+            ]),
+            SOUND_TIMEOUT_MS,
+          )
+        } catch (err) {
+          deps.logger.warn(
+            { err, tool: soundTool },
+            "linux notification: sound playback failed",
+          )
+        }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,72 @@
+import type pino from "pino"
+
+import { type CommandExecutor, withTimeout } from "../shared"
+import type { NotificationProvider } from "../notification"
+
+export interface WindowsNotificationDeps {
+  readonly executor: CommandExecutor
+  readonly logger: pino.Logger
+  readonly timeoutMs?: number
+  readonly soundPath?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000
+
+const shellQuote = (value: string): string =>
+  `'${value.replace(/'/g, "''").replace(/'/g, "'\\''")}'`
+
+// ponytail: raw toast template via PowerShell BurntToast-free path. Sufficient
+// for our "Pomodoro done" use case; richer XML templates are out of scope.
+const buildToastScript = (title: string, body: string): string => {
+  const safeTitle = title.replace(/[`$"\\]/g, "\\$&")
+  const safeBody = body.replace(/[`$"\\]/g, "\\$&")
+  return [
+    "Add-Type -AssemblyName System.Windows.Forms | Out-Null",
+    `$balloon = New-Object System.Windows.Forms.NotifyIcon`,
+    `$balloon.Icon = [System.Drawing.SystemIcons]::Information`,
+    `$balloon.BalloonTipTitle = "${safeTitle}"`,
+    `$balloon.BalloonTipText = "${safeBody}"`,
+    `$balloon.Visible = $true`,
+    `$balloon.ShowBalloonTip(5000)`,
+    "Start-Sleep -Milliseconds 5500",
+    "$balloon.Dispose()",
+  ].join("; ")
+}
+
+export const createWindowsNotificationProvider = async (
+  deps: WindowsNotificationDeps,
+): Promise<NotificationProvider> => {
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  return {
+    async notify(args) {
+      const script = buildToastScript(args.title, args.body)
+      try {
+        await withTimeout(
+          deps.executor.run("powershell", ["-NoProfile", "-Command", script]),
+          timeoutMs,
+        )
+      } catch (err) {
+        deps.logger.warn({ err }, "windows notification: toast failed")
+      }
+
+      if (args.sound === true && deps.soundPath !== undefined) {
+        try {
+          await withTimeout(
+            deps.executor.run("powershell", [
+              "-NoProfile",
+              "-Command",
+              `(New-Object Media.SoundPlayer '${shellQuote(deps.soundPath)}').PlaySync()`,
+            ]),
+            timeoutMs,
+          )
+        } catch (err) {
+          deps.logger.warn(
+            { err },
+            "windows notification: sound playback failed",
+          )
+        }
+      }
+    },
+  }
+}

package/src/system/providers/notification.ts

@@ -0,0 +1,75 @@
+import type pino from "pino"
+
+import { logNull, type CommandExecutor } from "./shared"
+
+export interface NotificationArgs {
+  readonly title: string
+  readonly body: string
+  readonly sound?: boolean
+}
+
+export interface NotificationProvider {
+  notify(args: NotificationArgs): Promise<void>
+}
+
+export interface CreateNotificationProviderOptions {
+  readonly platform?: NodeJS.Platform
+  readonly executor: CommandExecutor
+  readonly env: Readonly<Record<string, string>>
+  readonly logger: pino.Logger
+  readonly extraFsProbe?: (tool: string) => boolean
+  readonly soundPath?: string
+}
+
+export const createNullNotificationProvider = (
+  logger?: pino.Logger,
+): NotificationProvider => {
+  logNull(logger, "notification", "platform unsupported, notify() is a no-op")
+  return {
+    async notify() {
+      return
+    },
+  }
+}
+
+export const createNotificationProvider = async (
+  options: CreateNotificationProviderOptions,
+): Promise<NotificationProvider> => {
+  const platform = options.platform ?? process.platform
+  if (platform === "linux") {
+    const { createLinuxNotificationProvider } =
+      await import("./notification/linux")
+    return createLinuxNotificationProvider({
+      executor: options.executor,
+      logger: options.logger,
+      ...(options.extraFsProbe !== undefined
+        ? { extraFsProbe: options.extraFsProbe }
+        : {}),
+      ...(options.soundPath !== undefined
+        ? { soundPath: options.soundPath }
+        : {}),
+    })
+  }
+  if (platform === "darwin") {
+    const { createDarwinNotificationProvider } =
+      await import("./notification/darwin")
+    return createDarwinNotificationProvider({
+      executor: options.executor,
+      ...(options.soundPath !== undefined
+        ? { soundPath: options.soundPath }
+        : {}),
+    })
+  }
+  if (platform === "win32") {
+    const { createWindowsNotificationProvider } =
+      await import("./notification/windows")
+    return createWindowsNotificationProvider({
+      executor: options.executor,
+      logger: options.logger,
+      ...(options.soundPath !== undefined
+        ? { soundPath: options.soundPath }
+        : {}),
+    })
+  }
+  return createNullNotificationProvider(options.logger)
+}

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

@@ -0,0 +1,82 @@
+import type pino from "pino"
+
+import type { CommandExecutor } from "../shared"
+import { type SessionProvider, type SessionState } from "../session"
+
+export interface DarwinSessionDeps {
+  readonly executor: CommandExecutor
+  readonly logger: pino.Logger
+  readonly pollIntervalMs?: number
+}
+
+const toState = (locked: boolean): SessionState =>
+  locked ? "locked" : "unlocked"
+
+// ponytail: this used to ask System Events whether the `loginwindow` process
+// was running, which was wrong twice over. The script was a syntax error
+// (`loginwindow process` instead of `process "loginwindow"`), so every tick
+// exited non-zero and the state stayed "unknown" forever; and had it parsed,
+// loginwindow runs for the whole login session whether or not the screen is
+// locked, so it would have reported "locked" permanently.
+//
+// The real signal is CGSSessionScreenIsLocked in the console session
+// dictionary, which `ioreg` exposes without any Accessibility grant:
+// the key is present and true only while the screen is locked, and absent
+// entirely when unlocked.
+const IOREG_ARGS = ["-n", "Root", "-d1", "-a"] as const
+
+const parseScreenLocked = (raw: string): boolean =>
+  /<key>CGSSessionScreenIsLocked<\/key>\s*<true\/>/.test(raw)
+
+export const createDarwinSessionProvider = async (
+  deps: DarwinSessionDeps,
+): 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("ioreg", [...IOREG_ARGS], {
+        timeoutMs: 2_000,
+      })
+      if (result.exitCode !== 0) return state
+      return toState(parseScreenLocked(result.stdout))
+    } catch (err) {
+      deps.logger.debug({ err }, "session: ioreg 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/linux.ts

@@ -0,0 +1,175 @@
+import { sessionBus } from "dbus-next"
+
+import type pino from "pino"
+
+import {
+  createNullSessionProvider,
+  type SessionProvider,
+  type SessionState,
+} from "../session"
+import type { LinuxDbusBus } from "../shared"
+
+export interface LinuxSessionDeps {
+  readonly dbus?: LinuxDbusBus
+  readonly logger: pino.Logger
+  readonly idleMs?: number
+}
+
+const SCREENSAVER_SERVICE = "org.gnome.ScreenSaver"
+const SCREENSAVER_PATH = "/org/gnome/ScreenSaver"
+const SCREENSAVER_IFACE = "org.gnome.ScreenSaver"
+const IDLE_MONITOR_SERVICE = "org.gnome.Mutter.IdleMonitor"
+const IDLE_MONITOR_PATH = "/org/gnome/Mutter/IdleMonitor/Core"
+const IDLE_MONITOR_IFACE = "org.gnome.Mutter.IdleMonitor"
+
+const toState = (locked: boolean): SessionState =>
+  locked ? "locked" : "unlocked"
+
+export const createLinuxSessionProvider = async (
+  deps: LinuxSessionDeps,
+): Promise<SessionProvider> => {
+  const idleMs = deps.idleMs ?? 5 * 60 * 1000
+  const listeners = new Set<(s: SessionState) => void>()
+  let state: SessionState = "unknown"
+  let stopped = false
+  let idleSupported = false
+  let bus: LinuxDbusBus | null = deps.dbus ?? null
+  if (bus === null) {
+    try {
+      bus = (await sessionBus()) as unknown as LinuxDbusBus
+    } catch (err) {
+      deps.logger.debug({ err }, "session: dbus sessionBus unavailable")
+      return createNullSessionProvider(deps.logger)
+    }
+  }
+
+  let screensaverOk = false
+  try {
+    const proxy = await bus.getProxyObject(
+      SCREENSAVER_SERVICE,
+      SCREENSAVER_PATH,
+    )
+    const saver = proxy.getInterface(SCREENSAVER_IFACE)
+    const initial = (await saver.GetActive?.()) ?? false
+    state = toState(initial)
+    saver.on?.("ActiveChanged", (locked: unknown) => {
+      if (typeof locked === "boolean") {
+        const next = toState(locked)
+        if (next !== state) {
+          state = next
+          for (const l of listeners) l(state)
+        }
+      }
+    })
+    screensaverOk = true
+  } catch (err) {
+    // ponytail: ScreenSaver can be unavailable on non-GNOME sessions; keep
+    // the provider alive so the idle-monitor fallback can still fire.
+    deps.logger.debug({ err }, "session: ScreenSaver init failed")
+  }
+
+  try {
+    const idleProxy = await bus.getProxyObject(
+      IDLE_MONITOR_SERVICE,
+      IDLE_MONITOR_PATH,
+    )
+    const idleIface = idleProxy.getInterface(IDLE_MONITOR_IFACE)
+    await idleIface.GetIdletime?.()
+    idleSupported = true
+  } catch (err) {
+    deps.logger.debug(
+      { err },
+      "session: IdleMonitor init failed; idle polling disabled",
+    )
+  }
+
+  if (!screensaverOk && !idleSupported) {
+    deps.logger.debug("session: no lock source available, returning null")
+    return createNullSessionProvider(deps.logger)
+  }
+
+  void screensaverOk
+
+  let interval: ReturnType<typeof setInterval> | null = null
+  if (idleSupported) {
+    let cachedIdleIface: {
+      GetIdletime?: () => Promise<unknown>
+    } | null = null
+    const getIdleIface = async (): Promise<{
+      GetIdletime?: () => Promise<unknown>
+    } | null> => {
+      if (cachedIdleIface !== null) return cachedIdleIface
+      const p = await bus!.getProxyObject(
+        IDLE_MONITOR_SERVICE,
+        IDLE_MONITOR_PATH,
+      )
+      cachedIdleIface = p.getInterface(IDLE_MONITOR_IFACE) as {
+        GetIdletime?: () => Promise<unknown>
+      }
+      return cachedIdleIface
+    }
+    interval = setInterval(() => {
+      if (stopped) return
+      void getIdleIface()
+        .then((iface) => iface?.GetIdletime?.())
+        .then((idleMsRaw) => {
+          deps.logger.debug(
+            { idleMsRaw, idleMs, currentState: state },
+            "session: idle monitor tick",
+          )
+          if (typeof idleMsRaw === "number") {
+            if (idleMsRaw > idleMs && state === "unlocked") {
+              state = "locked"
+              deps.logger.info(
+                { idleMsRaw, idleMs },
+                "session: locked via idle monitor",
+              )
+              for (const l of listeners) l(state)
+            } else if (idleMsRaw <= idleMs && state === "locked") {
+              state = "unlocked"
+              deps.logger.info(
+                { idleMsRaw, idleMs },
+                "session: unlocked via idle monitor",
+              )
+              for (const l of listeners) l(state)
+            }
+          }
+        })
+        .catch(() => undefined)
+    }, 5_000)
+  }
+
+  return {
+    getState() {
+      return state
+    },
+    subscribe(handler) {
+      let initialFired = false
+      const wrappedHandler = (s: SessionState): void => {
+        initialFired = true
+        handler(s)
+      }
+      listeners.add(wrappedHandler)
+      if (!initialFired && state !== "unknown") {
+        queueMicrotask(() => {
+          if (!initialFired) handler(state)
+        })
+      }
+      return () => {
+        listeners.delete(wrappedHandler)
+      }
+    },
+    async stop() {
+      stopped = true
+      if (interval !== null) {
+        clearInterval(interval)
+        interval = null
+      }
+      try {
+        bus?.disconnect?.()
+      } catch {
+        // ignore
+      }
+    },
+  }
+}