@tiuxo/opencode-openrgb 0.0.0-stage → 0.1.0

package/src/controller.ts

@@ -0,0 +1,360 @@
+/**
+ * The lighting controller: owns the OpenRGB connection, the aggregated session
+ * state, and everything that decides what the hardware should show.
+ *
+ * Kept separate from `index.ts` so the logic stays directly importable and
+ * testable without going through the plugin entry point.
+ */
+
+import { OpenRGBClient, describe, findDirectMode, type Logger } from "./client.js"
+import { formatColor, scaleColor } from "./palette.js"
+import type { Device, Mode } from "./protocol.js"
+import { selectDevices, type ResolvedOptions, type StateColor } from "./options.js"
+import { StateTracker, type LightingState, type OpencodeEvent } from "./state.js"
+
+const LOG_PREFIX = "[opencode-openrgb]"
+
+/** Breathing effect bounds, as a fraction of the state's base brightness. */
+const PULSE_MIN = 0.25
+const PULSE_MAX = 1
+const PULSE_PERIOD_MS = 2_400
+
+interface Snapshot {
+  activeMode: number
+  colors: number[]
+}
+
+export class Controller {
+  private readonly client: OpenRGBClient
+  private readonly tracker: StateTracker
+  private readonly log: Logger
+
+  private targets: Device[] = []
+  private readonly snapshots = new Map<number, Snapshot>()
+  /** Devices whose active mode we changed, and so must change back. */
+  private readonly modeSwitched = new Set<number>()
+
+  private applied: LightingState | null = null
+  private debounceTimer: NodeJS.Timeout | null = null
+  private pulseTimer: NodeJS.Timeout | null = null
+  private pulseStartedAt = 0
+  private disposed = false
+
+  constructor(private readonly options: ResolvedOptions) {
+    this.log = makeLogger(options.debug)
+
+    this.tracker = new StateTracker({
+      onExpire: () => this.schedule(),
+    })
+
+    this.client = new OpenRGBClient({
+      host: options.host,
+      port: options.port,
+      clientName: "opencode",
+      logger: this.log,
+      onDevicesReloaded: (devices) => this.onDevicesReloaded(devices),
+    })
+  }
+
+  start(): void {
+    void this.client.ensureReady().then((ok) => {
+      if (!ok) {
+        this.log.debug("OpenRGB not reachable yet; will keep retrying in the background")
+      }
+    })
+  }
+
+  handleEvent(event: OpencodeEvent): void {
+    if (this.disposed) return
+    try {
+      if (this.tracker.handle(event)) this.schedule()
+    } catch (error) {
+      this.log.warn(`event handling failed: ${describe(error)}`)
+    }
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Device targeting and snapshots                                            |
+  \*-------------------------------------------------------------------------*/
+
+  private onDevicesReloaded(devices: readonly Device[]): void {
+    this.targets = selectDevices(devices, this.options)
+    this.snapshots.clear()
+    this.modeSwitched.clear()
+
+    for (const device of this.targets) {
+      this.snapshots.set(device.index, {
+        activeMode: device.activeMode,
+        colors: [...device.colors],
+      })
+    }
+
+    if (this.targets.length === 0) {
+      this.log.warn(
+        `no OpenRGB devices matched. Available: ${
+          devices.map((d) => `${d.name} (${d.typeName})`).join(", ") || "none"
+        }`,
+      )
+    } else {
+      this.log.debug(`targeting ${this.targets.map((d) => d.name).join(", ")}`)
+      this.warnIfSnapshotLooksStale()
+    }
+
+    // The connection is new, so whatever we previously applied is meaningless.
+    this.applied = null
+    this.schedule(0)
+  }
+
+  /**
+   * If the lighting we just captured is uniformly one of our own state colors,
+   * a previous run almost certainly failed to restore and we have snapshotted
+   * its leftovers as the "baseline". Say so, rather than silently treating a
+   * status color as the user's lighting.
+   */
+  private warnIfSnapshotLooksStale(): void {
+    const palette = new Map<number, string>()
+    for (const [state, spec] of Object.entries(this.options.colors)) {
+      // Only fixed colors are a tell: a baseline state paints the snapshot
+      // back, so matching it proves nothing.
+      if (spec.kind === "fixed") palette.set(spec.color, state)
+    }
+
+    for (const device of this.targets) {
+      const colors = this.snapshots.get(device.index)?.colors ?? []
+      if (colors.length === 0) continue
+      const first = colors[0]!
+      if (!colors.every((c) => c === first)) continue
+
+      const state = palette.get(first)
+      if (state) {
+        this.log.warn(
+          `"${device.name}" was already showing the ${state} color (${formatColor(first)}) ` +
+            `at startup, so that is now the restore baseline. If a previous run exited ` +
+            `without restoring, reload your OpenRGB profile and restart opencode.`,
+        )
+      }
+    }
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Scheduling                                                                |
+  \*-------------------------------------------------------------------------*/
+
+  private schedule(overrideDelay?: number): void {
+    if (this.disposed) return
+
+    const next = this.tracker.resolve()
+    const delay =
+      overrideDelay ??
+      (next === "idle"
+        ? this.options.debounceMs + this.options.restoreDelayMs
+        : this.options.debounceMs)
+
+    if (this.debounceTimer) clearTimeout(this.debounceTimer)
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null
+      void this.apply()
+    }, delay)
+    this.debounceTimer.unref?.()
+  }
+
+  private async apply(): Promise<void> {
+    if (this.disposed) return
+
+    const state = this.tracker.resolve()
+    if (state === this.applied) return
+
+    const ready = await this.client.ensureReady()
+    if (!ready || this.disposed) return
+    if (this.targets.length === 0) return
+
+    // Re-resolve: awaiting the connection may have taken a while.
+    const current = this.tracker.resolve()
+
+    try {
+      if (current === "idle" && this.options.idle.kind === "restore") {
+        this.stopPulse()
+        this.restore()
+      } else {
+        const spec: StateColor =
+          current === "idle"
+            ? { kind: "fixed", color: (this.options.idle as { color: number }).color }
+            : this.options.colors[current]
+
+        if (this.shouldPulse(current, spec)) {
+          this.startPulse(spec)
+        } else {
+          this.stopPulse()
+          this.paint(spec, 1)
+        }
+      }
+      this.applied = current
+      this.log.debug(
+        `state -> ${current}${
+          current !== "idle" && this.options.colors[current]?.kind === "baseline"
+            ? " (baseline)"
+            : ""
+        }`,
+      )
+    } catch (error) {
+      this.log.warn(`failed to apply state ${current}: ${describe(error)}`)
+    }
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Painting                                                                  |
+  \*-------------------------------------------------------------------------*/
+
+  /**
+   * A state whose color is the baseline must pulse, otherwise it would render
+   * identically to idle and convey nothing. Otherwise, pulsing is opt-in and
+   * applies to the busy state only.
+   */
+  private shouldPulse(state: LightingState, spec: StateColor): boolean {
+    if (spec.kind === "baseline") return true
+    return this.options.pulse && state === "busy"
+  }
+
+  private paint(spec: StateColor, factor: number): void {
+    for (const device of this.targets) {
+      const colors = this.colorsFor(device, spec, factor)
+      if (colors.length === 0) continue
+      this.ensureDirectMode(device)
+      this.client.updateLeds(device.index, colors)
+    }
+  }
+
+  /**
+   * Build the per-LED color array for a device.
+   *
+   * For `baseline` this scales each LED's *own* snapshot color, so a device
+   * whose profile uses several colors keeps that pattern and simply breathes.
+   */
+  private colorsFor(device: Device, spec: StateColor, factor: number): number[] {
+    const count = device.colors.length || device.leds.length
+    if (count === 0) return []
+
+    const intensity = this.options.brightness * factor
+
+    if (spec.kind === "fixed") {
+      return new Array<number>(count).fill(scaleColor(spec.color, intensity))
+    }
+
+    const base = this.snapshots.get(device.index)?.colors ?? []
+    if (base.length === 0) return []
+    return Array.from({ length: count }, (_, i) =>
+      scaleColor(base[i] ?? base[base.length - 1]!, intensity),
+    )
+  }
+
+  /**
+   * Per-LED color only takes effect in a direct/custom mode, so switch the
+   * device into one. Most devices are already there (both reference devices
+   * report "Direct" as the active mode), in which case this is a no-op.
+   */
+  private ensureDirectMode(device: Device): void {
+    const direct = findDirectMode(device)
+    if (!direct) {
+      this.client.setCustomMode(device.index)
+      this.modeSwitched.add(device.index)
+      return
+    }
+    if (device.activeMode === direct.index) return
+    if (this.modeSwitched.has(device.index)) return
+
+    this.client.updateMode(device.index, direct.index, direct.mode)
+    this.modeSwitched.add(device.index)
+  }
+
+  /**
+   * @param sync Use synchronous socket writes. Required when restoring from a
+   * process `exit` handler, where queued writes never reach the server.
+   */
+  private restore(sync = false): void {
+    for (const device of this.targets) {
+      const snapshot = this.snapshots.get(device.index)
+      if (!snapshot) continue
+
+      if (this.modeSwitched.has(device.index)) {
+        const mode: Mode | undefined = device.modes[snapshot.activeMode]
+        if (mode) this.client.updateMode(device.index, snapshot.activeMode, mode, sync)
+        this.modeSwitched.delete(device.index)
+      }
+
+      if (snapshot.colors.length > 0) {
+        this.client.updateLeds(device.index, snapshot.colors, sync)
+      }
+    }
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Pulse                                                                     |
+  \*-------------------------------------------------------------------------*/
+
+  private startPulse(spec: StateColor): void {
+    this.stopPulse()
+    this.pulseStartedAt = Date.now()
+
+    const render = () => {
+      const elapsed = Date.now() - this.pulseStartedAt
+      const phase = ((elapsed % PULSE_PERIOD_MS) / PULSE_PERIOD_MS) * Math.PI * 2
+      // Cosine eased 0..1, mapped into the pulse band.
+      const wave = (1 - Math.cos(phase)) / 2
+      this.paint(spec, PULSE_MIN + (PULSE_MAX - PULSE_MIN) * wave)
+    }
+
+    // Render the first frame immediately so the transition is not delayed by
+    // up to a full frame interval.
+    render()
+
+    const interval = Math.max(16, Math.round(1_000 / this.options.pulseFps))
+    this.pulseTimer = setInterval(() => {
+      if (this.disposed) return this.stopPulse()
+      render()
+    }, interval)
+    this.pulseTimer.unref?.()
+  }
+
+  private stopPulse(): void {
+    if (!this.pulseTimer) return
+    clearInterval(this.pulseTimer)
+    this.pulseTimer = null
+  }
+
+  /*-------------------------------------------------------------------------*\
+  | Shutdown                                                                  |
+  \*-------------------------------------------------------------------------*/
+
+  /**
+   * Best-effort restore on process teardown. Writes are small and go straight
+   * into the socket buffer, so this usually lands, but an abrupt kill can still
+   * leave the last color showing.
+   */
+  shutdown(): void {
+    if (this.disposed) return
+    this.disposed = true
+
+    this.stopPulse()
+    if (this.debounceTimer) clearTimeout(this.debounceTimer)
+
+    try {
+      // Synchronous writes: the event loop will not run again.
+      if (this.client.isReady && this.options.idle.kind === "restore") this.restore(true)
+    } catch {
+      // Nothing useful to do while the process is going away.
+    }
+
+    this.tracker.dispose()
+    this.client.dispose()
+  }
+}
+
+export function makeLogger(debug: boolean): Logger {
+  return {
+    debug: debug
+      ? (message: string) => console.error(`${LOG_PREFIX} ${message}`)
+      : () => {},
+    // Warnings are always surfaced: they indicate misconfiguration.
+    warn: (message: string) => console.error(`${LOG_PREFIX} ${message}`),
+  }
+}

package/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * opencode-openrgb
+ *
+ * Ambient status lighting for opencode. Mirrors aggregate session state onto
+ * OpenRGB-controlled hardware and hands your original lighting back when
+ * everything goes idle.
+ */
+
+import type { Plugin } from "@opencode/plugin"
+
+import { Controller } from "./controller.js"
+import { resolveOptions } from "./options.js"
+import { SUBSCRIBED_EVENTS, type OpencodeEvent } from "./state.js"
+
+export type { ResolvedOptions, IdleBehaviour, ActiveState, StateColor } from "./options.js"
+export type { LightingState, OpencodeEvent } from "./state.js"
+export type { Device, Mode, Zone, Led } from "./protocol.js"
+
+const LOG_PREFIX = "[opencode-openrgb]"
+
+/**
+ * Process-wide shared controller.
+ *
+ * A single opencode server loads this plugin once per location, but the RGB
+ * hardware is global to the machine, so several controllers would fight over
+ * it. Instances share one controller and refcount it: the first caller builds
+ * it, the last one to leave shuts it down. Shutting down on the first unload
+ * instead would darken the lights for every location still running.
+ */
+let shared: { controller: Controller; refs: number } | null = null
+
+function acquire(options: unknown): Controller | null {
+  if (shared) {
+    shared.refs++
+    return shared.controller
+  }
+
+  const resolved = resolveOptions(options, (message) =>
+    console.error(`${LOG_PREFIX} ${message}`),
+  )
+  if (!resolved.enabled) return null
+
+  const controller = new Controller(resolved)
+  shared = { controller, refs: 1 }
+  controller.start()
+  return controller
+}
+
+function release(): void {
+  if (!shared) return
+  shared.refs--
+  if (shared.refs > 0) return
+  shared.controller.shutdown()
+  shared = null
+}
+
+/*
+ * Declared as a `Plugin` literal rather than via `Plugin.define`, which is an
+ * identity function. That keeps `@opencode/plugin` a type-only import, so the
+ * published package has no runtime dependencies at all.
+ */
+const plugin: Plugin.Plugin = {
+  id: "opencode-openrgb",
+  setup(ctx) {
+    const controller = acquire(ctx.options)
+    if (!controller) return
+
+    const subscription = new AbortController()
+
+    void (async () => {
+      try {
+        const events = ctx.event.subscribe({
+          types: [...SUBSCRIBED_EVENTS],
+          signal: subscription.signal,
+        })
+        for await (const event of events) {
+          controller.handleEvent(event as OpencodeEvent)
+        }
+      } catch (error) {
+        // An abort during cleanup is the normal way this loop ends.
+        if (subscription.signal.aborted) return
+        console.error(`${LOG_PREFIX} event subscription failed: ${String(error)}`)
+      }
+    })()
+
+    return () => {
+      subscription.abort()
+      release()
+    }
+  },
+}
+
+export default plugin

package/src/options.ts

@@ -0,0 +1,229 @@
+/**
+ * Plugin option parsing.
+ *
+ * Options arrive from user config and are therefore untrusted. Every field is
+ * validated and falls back to a default on bad input, with a warning; a typo in
+ * `opencode.json` must never prevent the plugin from loading.
+ */
+
+import { DEFAULT_HOST, DEFAULT_PORT, type Device } from "./protocol.js"
+import { parseColor } from "./palette.js"
+import type { LightingState } from "./state.js"
+
+/** Lighting states that map to a solid color. `idle` is handled separately. */
+export type ActiveState = Exclude<LightingState, "idle">
+
+export type IdleBehaviour = { kind: "restore" } | { kind: "color"; color: number }
+
+/**
+ * How a state's color is chosen.
+ *
+ * `baseline` means "whatever the lighting was when the plugin connected",
+ * per LED — so the device keeps its own color identity (your OpenRGB profile)
+ * and only its intensity changes. A baseline state always pulses, because a
+ * static baseline would be indistinguishable from idle.
+ */
+export type StateColor = { kind: "fixed"; color: number } | { kind: "baseline" }
+
+/** Config values that select the baseline rather than a literal color. */
+const BASELINE_ALIASES = new Set(["baseline", "current", "profile"])
+
+export interface ResolvedOptions {
+  enabled: boolean
+  host: string
+  port: number
+  colors: Record<ActiveState, StateColor>
+  idle: IdleBehaviour
+  brightness: number
+  pulse: boolean
+  pulseFps: number
+  /** Debounce applied to all state transitions, to coalesce event bursts. */
+  debounceMs: number
+  /** Extra delay before handing lighting back on idle, to avoid thrashing. */
+  restoreDelayMs: number
+  include: string[]
+  exclude: string[]
+  debug: boolean
+}
+
+const DEFAULT_COLORS: Record<ActiveState, string> = {
+  busy: "#ff8c00",
+  retry: "#ffd000",
+  permission: "#b400ff",
+  error: "#ff0000",
+}
+
+/**
+ * Default targets: ambient/interior lighting only.
+ *
+ * This deliberately excludes `keyboard`, `mouse`, `keypad` and `accessory`.
+ * Those are functional devices whose lighting usually conveys something (an
+ * Elgato Stream Deck's button icons, for instance), and hijacking them by
+ * default would be obnoxious.
+ */
+const DEFAULT_INCLUDE = ["motherboard", "dram", "gpu", "cooler", "case", "ledstrip"]
+
+const ACTIVE_STATES: ActiveState[] = ["busy", "retry", "permission", "error"]
+
+export function resolveOptions(
+  raw: unknown,
+  warn: (message: string) => void = () => {},
+): ResolvedOptions {
+  const o = isRecord(raw) ? raw : {}
+
+  const colors = {} as Record<ActiveState, StateColor>
+  const rawColors = isRecord(o["colors"]) ? o["colors"] : {}
+  for (const state of ACTIVE_STATES) {
+    const fallback: StateColor = { kind: "fixed", color: parseColor(DEFAULT_COLORS[state])! }
+    if (!(state in rawColors)) {
+      colors[state] = fallback
+      continue
+    }
+    colors[state] = stateColorOption(rawColors[state], fallback, `colors.${state}`, warn)
+  }
+
+  const devices = isRecord(o["devices"]) ? o["devices"] : {}
+
+  return {
+    enabled: boolOption(o["enabled"], true),
+    host: stringOption(o["host"], DEFAULT_HOST),
+    port: intOption(o["port"], DEFAULT_PORT, 1, 65535, "port", warn),
+    colors,
+    idle: idleOption(o["idle"], warn),
+    brightness: numberOption(o["brightness"], 1, 0, 1, "brightness", warn),
+    pulse: boolOption(o["pulse"], false),
+    pulseFps: intOption(o["pulseFps"], 15, 1, 60, "pulseFps", warn),
+    debounceMs: intOption(o["debounceMs"], 120, 0, 5_000, "debounceMs", warn),
+    restoreDelayMs: intOption(o["restoreDelayMs"], 400, 0, 60_000, "restoreDelayMs", warn),
+    include: stringArrayOption(devices["include"], DEFAULT_INCLUDE, "devices.include", warn),
+    exclude: stringArrayOption(devices["exclude"], [], "devices.exclude", warn),
+    debug: boolOption(o["debug"], process.env["OPENCODE_OPENRGB_DEBUG"] === "1"),
+  }
+}
+
+function stateColorOption(
+  value: unknown,
+  fallback: StateColor,
+  name: string,
+  warn: (m: string) => void,
+): StateColor {
+  if (typeof value === "string" && BASELINE_ALIASES.has(value.trim().toLowerCase())) {
+    return { kind: "baseline" }
+  }
+  const parsed = parseColor(value)
+  if (parsed === null) {
+    warn(`invalid ${name} (${JSON.stringify(value)}); using default`)
+    return fallback
+  }
+  return { kind: "fixed", color: parsed }
+}
+
+function idleOption(value: unknown, warn: (m: string) => void): IdleBehaviour {
+  if (value === undefined || value === null) return { kind: "restore" }
+  if (typeof value === "string" && value.trim().toLowerCase() === "restore") {
+    return { kind: "restore" }
+  }
+  const parsed = parseColor(value)
+  if (parsed === null) {
+    warn(`invalid idle (${JSON.stringify(value)}); using "restore"`)
+    return { kind: "restore" }
+  }
+  return { kind: "color", color: parsed }
+}
+
+/*---------------------------------------------------------------------------*\
+| Device matching                                                             |
+\*---------------------------------------------------------------------------*/
+
+/**
+ * A pattern matches a device if it equals the device's type name
+ * (e.g. `motherboard`) or glob-matches its product name (e.g. `ASUS*`).
+ * Matching is case-insensitive; `*` and `?` are the supported wildcards.
+ */
+export function deviceMatches(device: Device, patterns: readonly string[]): boolean {
+  return patterns.some((pattern) => {
+    const p = pattern.trim().toLowerCase()
+    if (p.length === 0) return false
+    if (p === "*") return true
+    if (p === device.typeName.toLowerCase()) return true
+    return globToRegExp(p).test(device.name.toLowerCase())
+  })
+}
+
+export function selectDevices(
+  devices: readonly Device[],
+  options: Pick<ResolvedOptions, "include" | "exclude">,
+): Device[] {
+  return devices.filter(
+    (device) =>
+      deviceMatches(device, options.include) && !deviceMatches(device, options.exclude),
+  )
+}
+
+function globToRegExp(glob: string): RegExp {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+  const pattern = escaped.replace(/\*/g, ".*").replace(/\?/g, ".")
+  return new RegExp(`^${pattern}$`)
+}
+
+/*---------------------------------------------------------------------------*\
+| Primitive coercion                                                          |
+\*---------------------------------------------------------------------------*/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function boolOption(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback
+}
+
+function stringOption(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback
+}
+
+function numberOption(
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number,
+  name: string,
+  warn: (m: string) => void,
+): number {
+  if (value === undefined) return fallback
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    warn(`invalid ${name} (${JSON.stringify(value)}); using ${fallback}`)
+    return fallback
+  }
+  if (value < min || value > max) {
+    const clamped = Math.max(min, Math.min(max, value))
+    warn(`${name} ${value} out of range [${min}, ${max}]; clamped to ${clamped}`)
+    return clamped
+  }
+  return value
+}
+
+function intOption(
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number,
+  name: string,
+  warn: (m: string) => void,
+): number {
+  return Math.round(numberOption(value, fallback, min, max, name, warn))
+}
+
+function stringArrayOption(
+  value: unknown,
+  fallback: string[],
+  name: string,
+  warn: (m: string) => void,
+): string[] {
+  if (value === undefined) return [...fallback]
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+    warn(`invalid ${name}; expected an array of strings. Using default`)
+    return [...fallback]
+  }
+  return (value as string[]).map((v) => v.trim()).filter((v) => v.length > 0)
+}