opencode-rgbify-plugin 0.1.3

package/README.md

@@ -0,0 +1,97 @@
+# opencode-rgbify-plugin
+
+An [opencode](https://opencode.ai) plugin that streams chat text deltas to an
+[RGBify](https://github.com/dcerisano/rgbify-projector) 8x8 LED projector over
+BLE, with an always-on host auralizer so the sound never stops even when the
+projector is out of range.
+
+## How it works
+
+```
+opencode events ──► src/index.ts (plugin) ──► raw tail ──► line on stdin
+                                                          │
+                                              bridge/ble_bridge.py
+                                              ├─► BLE write → RGBify projector
+                                              └─► host auralizer (miniaudio)
+```
+
+- **`src/index.ts`** — the opencode plugin. Spawns the Python bridge and
+  forwards each delta's last 8 chars as a newline-delimited line. **No
+  sanitization**: both auralizers treat any out-of-range byte as a rest, so
+  raw text is safe. (Sanitization existed for the scrolling-display era, where
+  tags in the text would scroll across the matrix; the firmware now blits one
+  char at a time, so tags are harmless — and the old tag-swallowing state
+  machine could stick on an unbalanced `<` and silently discard whole streams.
+  That was the long-standing "auralizers go silent" bug.)
+- **`bridge/ble_bridge.py`** — the BLE bridge. Reads lines from stdin, chunks
+  them to the negotiated MTU, writes them to the projector's `TEXT_BRIDGE`
+  characteristic, and auralizes each char on the host at the firmware's native
+  cadence (one ~33ms note per char, log-scale frequency table identical to the
+  firmware).
+
+### Interrupt semantics
+
+Every event is delivered immediately as its own line — no buffering, no
+debounce, no rate limiter. Each sink (BLE write path, host auralizer) keeps
+only the **latest** line, so a newer message supersedes anything still in
+flight. The last message is the only message.
+
+While the projector is connected, the host auralizer plays **exactly** the
+bytes the projector receives (char-perfect sync). While it's down, the host
+keeps auralizing and lines are dropped for the projector — nothing is queued or
+replayed on reconnect.
+
+## Install
+
+The plugin is **self-bootstrapping**: on first use it automatically runs the
+bridge installer, which installs everything it needs (uv, Python, and the
+bridge deps) as the current user — no root/admin required. On Linux/macOS it
+runs `bridge/install.sh`; on Windows it runs `bridge/install.ps1` (via
+PowerShell). No manual setup is needed; just install the plugin into opencode.
+
+You can also run the installer yourself (it's idempotent — re-running is a
+no-op):
+
+```bash
+bash bridge/install.sh                                  # Linux/macOS
+powershell -ExecutionPolicy Bypass -File bridge/install.ps1   # Windows
+```
+
+Each installer ensures `uv` (installing it into the user's home dir if
+missing), uses uv to manage a Python interpreter, creates an isolated `.venv`
+at the plugin root — the exact path `src/index.ts` probes for `VENV_PYTHON`
+(`.venv/bin/python` on Unix, `.venv/Scripts/python.exe` on Windows) — and
+installs `bleak` (required) plus `miniaudio` (host auralizer). `miniaudio`
+bundles its own native audio lib, so the auralizer needs no system deps (no
+PortAudio) and works cross-platform on Windows, macOS, and Linux. If
+`miniaudio` is unavailable, the host auralizer is disabled and the projector
+path still works.
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `RGBIFY_DISABLE` | — | Set to `1`/`true` to disable the plugin |
+| `RGBIFY_PROJECTOR_ADDR` | `40:91:51:AB:50:CE` | Fixed projector address (skips BLE discovery) |
+| `RGBIFY_HOST_AURALIZER` | `1` | Set to `0` to disable the host auralizer |
+| `RGBIFY_VOLUME` | `10` | Initial host volume (0–10) |
+| `RGBIFY_STATE_DIR` | `~/.config/opencode/state` | Where `host-volume` is persisted |
+| `RGBIFY_DEBUG_LOG` | — | Append debug log path |
+
+Host volume is mirrored from the projector's `VOLUME` characteristic whenever
+it's connected and persisted to `host-volume` so it survives restarts. While
+the projector is off you can still adjust the host volume by editing that file.
+
+## Development
+
+```bash
+npm install        # @opencode-ai/plugin types
+bun run ...        # run opencode with the plugin loaded
+```
+
+The bridge logs one line per event to stdout for debugging: `ok <addr>` on
+connect/delivery, `err <message>` on failure (it retries with backoff forever).
+
+## License
+
+MIT