opencode-rgbify-plugin 0.1.3 → 0.1.5

package/dist/index.js

@@ -1,7 +1,8 @@
 import { spawn } from "bun";
-import { existsSync, appendFileSync } from "node:fs";
+import { existsSync, appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
+import os from "node:os";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const PLUGIN_ROOT = path.join(here, "..");
 const BRIDGE = path.join(here, "..", "bridge", "ble_bridge.py");
@@ -17,14 +18,36 @@ const VENV_PYTHON = IS_WINDOWS
     ? path.join(here, "..", ".venv", "Scripts", "python.exe")
     : path.join(here, "..", ".venv", "bin", "python");
 const DEBUG_LOG = process.env.RGBIFY_DEBUG_LOG;
-function debug(line) {
-    if (!DEBUG_LOG)
+// Debug logging must never run synchronously on opencode's stream fiber: the
+// plugin's `event` hook is invoked inline in the awaited event listener chain
+// (see mem:opencode/delta-control-flow), so a per-delta appendFileSync would
+// stall the whole LLM stream. Batch lines and flush on a timer instead.
+const debugLines = [];
+let debugTimer = null;
+function flushDebug() {
+    if (debugTimer !== null) {
+        clearTimeout(debugTimer);
+        debugTimer = null;
+    }
+    if (!DEBUG_LOG || debugLines.length === 0)
         return;
+    const batch = debugLines.splice(0);
     try {
-        appendFileSync(DEBUG_LOG, `${Date.now()} ${line}\n`);
+        appendFileSync(DEBUG_LOG, batch.join(""));
     }
     catch { }
 }
+function debug(line) {
+    if (!DEBUG_LOG)
+        return;
+    debugLines.push(`${Date.now()} ${line}\n`);
+    if (debugTimer === null) {
+        debugTimer = setTimeout(() => {
+            debugTimer = null;
+            flushDebug();
+        }, 50);
+    }
+}
 // Self-bootstrap: on first use, if the bridge venv doesn't exist, run the
 // platform installer to install EVERYTHING (uv, Python, bleak, miniaudio) as
 // the user, no root/admin. A shared promise guards against concurrent send()s
@@ -63,6 +86,32 @@ async function bootstrapPython() {
 function isEnabled() {
     return process.env.RGBIFY_DISABLE !== "1" && process.env.RGBIFY_DISABLE !== "true";
 }
+// Desktop volume is a plain shared file the bridge's `watch_host_volume` task
+// polls and applies live (works with the projector off). The /rgbify slash
+// command just writes it. Path defaults to the opencode global state dir.
+function stateDir() {
+    return (process.env.RGBIFY_STATE_DIR ||
+        path.join(os.homedir(), ".config", "opencode", "state"));
+}
+const VOLUME_FILE = path.join(stateDir(), "host-volume");
+function readHostVolume() {
+    try {
+        const v = parseInt(readFileSync(VOLUME_FILE, "utf8").trim(), 10);
+        return Number.isFinite(v) ? Math.max(0, Math.min(10, v)) : 10;
+    }
+    catch {
+        return 10;
+    }
+}
+function writeHostVolume(v) {
+    try {
+        mkdirSync(stateDir(), { recursive: true });
+        writeFileSync(VOLUME_FILE, String(Math.max(0, Math.min(10, Math.round(v)))));
+    }
+    catch {
+        // Non-fatal: volume just won't persist.
+    }
+}
 // NO sanitization — raw delta text goes straight to the bridge. Both auralizers
 // tolerate any byte (out-of-range chars play as rests), so nothing can crash or
 // wedge. History: sanitize() existed for the scrolling-display era, where tags
@@ -76,6 +125,50 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
         return {};
     let procPromise = null;
     const seenEventTypes = new Set();
+    // One-way, non-blocking delivery: a ReadableStream fed into the bridge's
+    // stdin. pull() waits for a queued line and enqueues the oldest first (FIFO);
+    // every line is delivered in order — nothing is dropped or replaced. There is
+    // NO synchronous FileSink write/flush on opencode's event loop — that was the
+    // freeze (blocking the TUI whenever the pipe backed up under load).
+    let enqueueLine = null;
+    let pendingLine = null;
+    function makeStdinStream() {
+        const lines = [];
+        let wake = null;
+        let closed = false;
+        const enc = new TextEncoder();
+        const stream = new ReadableStream({
+            async pull(controller) {
+                while (lines.length === 0 && !closed) {
+                    await new Promise((resolve) => {
+                        wake = resolve;
+                    });
+                }
+                if (closed)
+                    return;
+                controller.enqueue(enc.encode(lines.shift() + "\n"));
+            },
+            cancel() {
+                closed = true;
+                if (wake) {
+                    const w = wake;
+                    wake = null;
+                    w();
+                }
+            },
+        });
+        enqueueLine = (line) => {
+            if (closed)
+                return;
+            lines.push(line);
+            if (wake) {
+                const w = wake;
+                wake = null;
+                w();
+            }
+        };
+        return stream;
+    }
     function startBridge() {
         if (procPromise)
             return procPromise;
@@ -84,7 +177,7 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
             if (!python)
                 throw new Error("bridge deps not installed (install.sh failed)");
             const proc = spawn([python, BRIDGE], {
-                stdin: "pipe",
+                stdin: makeStdinStream(),
                 stdout: "pipe",
                 stderr: "pipe",
                 // Skip BLE discovery (a ~5s scan) on every connect: default to the
@@ -101,18 +194,25 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
             // `.finally` so a dead bridge is replaced by the next send().
             void proc.exited.finally(() => {
                 procPromise = null;
+                enqueueLine = null;
+                pendingLine = null;
             });
+            // Flush any line that arrived before the bridge was up (single pending slot).
+            if (pendingLine !== null) {
+                enqueueLine?.(pendingLine);
+                pendingLine = null;
+            }
             return proc;
         })();
         return procPromise;
     }
     // Delivery: raw delta text is COALESCED into full-length messages. opencode
-    // emits deltas in bursts of tiny fragments (avg ~4 chars); per-delta sends
-    // produced 140ms notes separated by 600-800ms holes. Instead, accumulate
+    // emits deltas in bursts of tiny fragments (~4 chars); per-delta sends would
+    // produce fragmented notes under the bridge's ACK gate. Instead, accumulate
     // text and emit a full TAIL_CHARS message whenever the buffer fills — or
     // after FLUSH_MS of quiet, so tails aren't lost and sound stops promptly
-    // when printing stops. The bridge chains whatever is queued straight after
-    // each ACK, so during continuous printing the notes play back-to-back.
+    // when printing stops. The bridge writes one line per ACK (gated), so during
+    // continuous printing the notes play back-to-back. Firmware cap is MAX_TEXT.
     const TAIL_CHARS = 8;
     const FLUSH_MS = 150;
     let buf = "";
@@ -129,24 +229,22 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
     }
     function writeLine(line) {
         debug(`send len=${line.length}`);
-        startBridge()
-            .then((proc) => {
-            // We always spawn the bridge with stdin: "pipe", so it's a FileSink.
-            const stdin = proc.stdin;
-            stdin.write(line + "\n");
-            // Bun's FileSink buffers writes; without flush() the bridge receives
-            // them in delayed bursts, desyncing the projector/host from opencode.
-            const r = stdin.flush();
-            if (r && typeof r.then === "function") {
-                ;
-                r.catch(() => { });
-            }
-        })
-            .catch(async (err) => {
-            await client.app.log({
-                body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
+        if (enqueueLine) {
+            enqueueLine(line);
+        }
+        else {
+            pendingLine = line;
+        }
+        // Keep the hot path free of spawn work: the bridge is started once at
+        // plugin init (and respawned only after a death clears procPromise), so a
+        // steady stream of deltas never re-enters startBridge().
+        if (procPromise === null) {
+            startBridge().catch(async (err) => {
+                await client.app.log({
+                    body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
+                });
             });
-        });
+        }
     }
     function send(text) {
         // Raw text, coalesced — no sanitization (see the note above).
@@ -195,6 +293,36 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
                 return;
             }
         },
+        // /rgbify volume <0-10>: the server plugin handles it directly (no model
+        // needed to act) — writes host-volume, which the bridge's watch_host_volume
+        // task applies live. The command still flows through the normal command
+        // pipeline, so we replace the parts with a crisp confirmation for the model
+        // to echo. In-place mutation: opencode passes the `parts` array by reference
+        // (plugin.trigger), so clearing + pushing takes effect on the prompt.
+        "command.execute.before": async (input, output) => {
+            if (input.command !== "rgbify")
+                return;
+            const args = (input.arguments || "").trim();
+            const base = {
+                id: `rgbify-${Date.now()}`,
+                sessionID: input.sessionID,
+                messageID: input.sessionID,
+            };
+            const m = args.match(/^volume\s+([0-9]+)$/);
+            output.parts.length = 0;
+            if (m) {
+                const v = Math.max(0, Math.min(10, parseInt(m[1], 10)));
+                writeHostVolume(v);
+                output.parts.push({ ...base, type: "text", text: `RGBify desktop volume set to ${v}.` });
+            }
+            else {
+                output.parts.push({
+                    ...base,
+                    type: "text",
+                    text: `RGBify desktop volume is ${readHostVolume()}. Usage: /rgbify volume <0-10>.`,
+                });
+            }
+        },
         "chat.message": async (_input, output) => {
             for (const part of output.parts) {
                 if (part.type !== "text")
@@ -209,8 +337,9 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
             send("tool out");
         },
         // When opencode shuts down, kill the bridge so it doesn't linger as an
-        // orphan holding the projector connection. Closing its stdin would also do
-        // it (the bridge exits on EOF), but kill is immediate and explicit.
+        // orphan. The bridge exits WITHOUT a BLE disconnect (bluetoothd keeps the
+        // shared link), so the RGBify website stays connected. Closing stdin would
+        // also do it (the bridge exits on EOF), but kill is immediate and explicit.
         dispose: async () => {
             // Drop any pending coalesced text — the session is over.
             if (flushTimer) {
@@ -218,6 +347,9 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
                 flushTimer = null;
             }
             buf = "";
+            enqueueLine = null;
+            pendingLine = null;
+            flushDebug();
             if (procPromise) {
                 try {
                     const proc = await procPromise;

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "opencode-rgbify-plugin",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "opencode plugin: stream chat text deltas to an RGBify 8x8 projector over BLE",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "rgbify",
+    "ble",
+    "bluetooth",
+    "led",
+    "matrix",
+    "esp32",
+    "auralizer",
+    "sonification"
+  ],
+  "homepage": "https://github.com/dcerisano/opencode-rgbify-plugin",
+  "bugs": {
+    "url": "https://github.com/dcerisano/opencode-rgbify-plugin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dcerisano/opencode-rgbify-plugin.git"
+  },
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",

package/src/index.ts

@@ -1,8 +1,9 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { spawn } from "bun"
-import { existsSync, appendFileSync } from "node:fs"
+import { existsSync, appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 import path from "node:path"
+import os from "node:os"
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const PLUGIN_ROOT = path.join(here, "..")
@@ -20,13 +21,36 @@ const VENV_PYTHON = IS_WINDOWS
   : path.join(here, "..", ".venv", "bin", "python")
 const DEBUG_LOG = process.env.RGBIFY_DEBUG_LOG
 
-function debug(line: string) {
-  if (!DEBUG_LOG) return
+// Debug logging must never run synchronously on opencode's stream fiber: the
+// plugin's `event` hook is invoked inline in the awaited event listener chain
+// (see mem:opencode/delta-control-flow), so a per-delta appendFileSync would
+// stall the whole LLM stream. Batch lines and flush on a timer instead.
+const debugLines: string[] = []
+let debugTimer: ReturnType<typeof setTimeout> | null = null
+
+function flushDebug() {
+  if (debugTimer !== null) {
+    clearTimeout(debugTimer)
+    debugTimer = null
+  }
+  if (!DEBUG_LOG || debugLines.length === 0) return
+  const batch = debugLines.splice(0)
   try {
-    appendFileSync(DEBUG_LOG, `${Date.now()} ${line}\n`)
+    appendFileSync(DEBUG_LOG, batch.join(""))
   } catch {}
 }
 
+function debug(line: string) {
+  if (!DEBUG_LOG) return
+  debugLines.push(`${Date.now()} ${line}\n`)
+  if (debugTimer === null) {
+    debugTimer = setTimeout(() => {
+      debugTimer = null
+      flushDebug()
+    }, 50)
+  }
+}
+
 // Self-bootstrap: on first use, if the bridge venv doesn't exist, run the
 // platform installer to install EVERYTHING (uv, Python, bleak, miniaudio) as
 // the user, no root/admin. A shared promise guards against concurrent send()s
@@ -65,6 +89,36 @@ function isEnabled(): boolean {
   return process.env.RGBIFY_DISABLE !== "1" && process.env.RGBIFY_DISABLE !== "true"
 }
 
+// Desktop volume is a plain shared file the bridge's `watch_host_volume` task
+// polls and applies live (works with the projector off). The /rgbify slash
+// command just writes it. Path defaults to the opencode global state dir.
+function stateDir(): string {
+  return (
+    process.env.RGBIFY_STATE_DIR ||
+    path.join(os.homedir(), ".config", "opencode", "state")
+  )
+}
+
+const VOLUME_FILE = path.join(stateDir(), "host-volume")
+
+function readHostVolume(): number {
+  try {
+    const v = parseInt(readFileSync(VOLUME_FILE, "utf8").trim(), 10)
+    return Number.isFinite(v) ? Math.max(0, Math.min(10, v)) : 10
+  } catch {
+    return 10
+  }
+}
+
+function writeHostVolume(v: number): void {
+  try {
+    mkdirSync(stateDir(), { recursive: true })
+    writeFileSync(VOLUME_FILE, String(Math.max(0, Math.min(10, Math.round(v)))))
+  } catch {
+    // Non-fatal: volume just won't persist.
+  }
+}
+
 // NO sanitization — raw delta text goes straight to the bridge. Both auralizers
 // tolerate any byte (out-of-range chars play as rests), so nothing can crash or
 // wedge. History: sanitize() existed for the scrolling-display era, where tags
@@ -80,13 +134,57 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
   let procPromise: Promise<ReturnType<typeof spawn>> | null = null
   const seenEventTypes = new Set<string>()
 
+  // One-way, non-blocking delivery: a ReadableStream fed into the bridge's
+  // stdin. pull() waits for a queued line and enqueues the oldest first (FIFO);
+  // every line is delivered in order — nothing is dropped or replaced. There is
+  // NO synchronous FileSink write/flush on opencode's event loop — that was the
+  // freeze (blocking the TUI whenever the pipe backed up under load).
+  let enqueueLine: ((line: string) => void) | null = null
+  let pendingLine: string | null = null
+
+  function makeStdinStream(): ReadableStream<Uint8Array> {
+    const lines: string[] = []
+    let wake: (() => void) | null = null
+    let closed = false
+    const enc = new TextEncoder()
+    const stream = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        while (lines.length === 0 && !closed) {
+          await new Promise<void>((resolve) => {
+            wake = resolve
+          })
+        }
+        if (closed) return
+        controller.enqueue(enc.encode(lines.shift() + "\n"))
+      },
+      cancel() {
+        closed = true
+        if (wake) {
+          const w = wake
+          wake = null
+          w()
+        }
+      },
+    })
+    enqueueLine = (line: string) => {
+      if (closed) return
+      lines.push(line)
+      if (wake) {
+        const w = wake
+        wake = null
+        w()
+      }
+    }
+    return stream
+  }
+
   function startBridge(): Promise<ReturnType<typeof spawn>> {
     if (procPromise) return procPromise
     procPromise = (async () => {
       const python = await bootstrapPython()
       if (!python) throw new Error("bridge deps not installed (install.sh failed)")
       const proc = spawn([python, BRIDGE], {
-        stdin: "pipe",
+        stdin: makeStdinStream(),
         stdout: "pipe",
         stderr: "pipe",
         // Skip BLE discovery (a ~5s scan) on every connect: default to the
@@ -106,19 +204,26 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
       // `.finally` so a dead bridge is replaced by the next send().
       void proc.exited.finally(() => {
         procPromise = null
+        enqueueLine = null
+        pendingLine = null
       })
+      // Flush any line that arrived before the bridge was up (single pending slot).
+      if (pendingLine !== null) {
+        enqueueLine?.(pendingLine)
+        pendingLine = null
+      }
       return proc
     })()
     return procPromise
   }
 
   // Delivery: raw delta text is COALESCED into full-length messages. opencode
-  // emits deltas in bursts of tiny fragments (avg ~4 chars); per-delta sends
-  // produced 140ms notes separated by 600-800ms holes. Instead, accumulate
+  // emits deltas in bursts of tiny fragments (~4 chars); per-delta sends would
+  // produce fragmented notes under the bridge's ACK gate. Instead, accumulate
   // text and emit a full TAIL_CHARS message whenever the buffer fills — or
   // after FLUSH_MS of quiet, so tails aren't lost and sound stops promptly
-  // when printing stops. The bridge chains whatever is queued straight after
-  // each ACK, so during continuous printing the notes play back-to-back.
+  // when printing stops. The bridge writes one line per ACK (gated), so during
+  // continuous printing the notes play back-to-back. Firmware cap is MAX_TEXT.
   const TAIL_CHARS = 8
   const FLUSH_MS = 150
   let buf = ""
@@ -136,26 +241,21 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
 
   function writeLine(line: string) {
     debug(`send len=${line.length}`)
-    startBridge()
-      .then((proc) => {
-        // We always spawn the bridge with stdin: "pipe", so it's a FileSink.
-        const stdin = proc.stdin as unknown as {
-          write(s: string): void
-          flush(): number | Promise<number>
-        }
-        stdin.write(line + "\n")
-        // Bun's FileSink buffers writes; without flush() the bridge receives
-        // them in delayed bursts, desyncing the projector/host from opencode.
-        const r = stdin.flush()
-        if (r && typeof (r as Promise<number>).then === "function") {
-          ;(r as Promise<number>).catch(() => {})
-        }
-      })
-      .catch(async (err) => {
+    if (enqueueLine) {
+      enqueueLine(line)
+    } else {
+      pendingLine = line
+    }
+    // Keep the hot path free of spawn work: the bridge is started once at
+    // plugin init (and respawned only after a death clears procPromise), so a
+    // steady stream of deltas never re-enters startBridge().
+    if (procPromise === null) {
+      startBridge().catch(async (err) => {
         await client.app.log({
           body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
         })
       })
+    }
   }
 
   function send(text: string) {
@@ -207,6 +307,34 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
         return
       }
     },
+    // /rgbify volume <0-10>: the server plugin handles it directly (no model
+    // needed to act) — writes host-volume, which the bridge's watch_host_volume
+    // task applies live. The command still flows through the normal command
+    // pipeline, so we replace the parts with a crisp confirmation for the model
+    // to echo. In-place mutation: opencode passes the `parts` array by reference
+    // (plugin.trigger), so clearing + pushing takes effect on the prompt.
+    "command.execute.before": async (input, output) => {
+      if (input.command !== "rgbify") return
+      const args = (input.arguments || "").trim()
+      const base = {
+        id: `rgbify-${Date.now()}`,
+        sessionID: input.sessionID,
+        messageID: input.sessionID,
+      }
+      const m = args.match(/^volume\s+([0-9]+)$/)
+      output.parts.length = 0
+      if (m) {
+        const v = Math.max(0, Math.min(10, parseInt(m[1], 10)))
+        writeHostVolume(v)
+        output.parts.push({ ...base, type: "text", text: `RGBify desktop volume set to ${v}.` })
+      } else {
+        output.parts.push({
+          ...base,
+          type: "text",
+          text: `RGBify desktop volume is ${readHostVolume()}. Usage: /rgbify volume <0-10>.`,
+        })
+      }
+    },
     "chat.message": async (_input, output) => {
       for (const part of output.parts) {
         if (part.type !== "text") continue
@@ -220,8 +348,9 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
       send("tool out")
     },
     // When opencode shuts down, kill the bridge so it doesn't linger as an
-    // orphan holding the projector connection. Closing its stdin would also do
-    // it (the bridge exits on EOF), but kill is immediate and explicit.
+    // orphan. The bridge exits WITHOUT a BLE disconnect (bluetoothd keeps the
+    // shared link), so the RGBify website stays connected. Closing stdin would
+    // also do it (the bridge exits on EOF), but kill is immediate and explicit.
     dispose: async () => {
       // Drop any pending coalesced text — the session is over.
       if (flushTimer) {
@@ -229,6 +358,9 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
         flushTimer = null
       }
       buf = ""
+      enqueueLine = null
+      pendingLine = null
+      flushDebug()
       if (procPromise) {
         try {
           const proc = await procPromise